API Documentation

Complete guide to integrating with the IBANValidation API. Validate IBANs, lookup bank information, and ensure payment compliance.

Base URL

http://localhost:4000

All API endpoints are relative to this base URL. For production, use your deployed server URL.

Quick Start

Get started with a simple IBAN validation request:

curl -X GET "http://localhost:4000/iban/details/GB82WEST12345698765432"

Authentication

Currently, the API does not require authentication for basic usage. All endpoints are publicly accessible.

Future Enhancement

API key authentication will be added for production usage with rate limiting and usage tracking.

Rate Limits

Current rate limits are generous for development and testing:

• No rate limits currently enforced
• Recommended: Max 100 requests per minute
• Bulk operations: Process in batches of 50

IBAN Validation

GET /iban/validate/{iban}

Validate an IBAN and get basic information.

Parameters

Parameter	Type	Description
iban	string	The IBAN to validate (with or without spaces)

Example Request

curl -X GET "http://localhost:4000/iban/validate/GB82WEST12345698765432"

Response

{
  "valid": true,
  "iban": "GB82WEST12345698765432",
  "country": "United Kingdom",
  "countryCode": "GB"
}

GET /iban/details/{iban}

Get detailed IBAN validation with bank information.

Example Request

curl -X GET "http://localhost:4000/iban/details/GB82WEST12345698765432"

Response

{
  "valid": true,
  "iban": "GB82WEST12345698765432",
  "country": "United Kingdom",
  "countryCode": "GB",
  "bankCode": "WEST",
  "bic": "BARCGB22",
  "bankInfo": {
    "Bank Name": "Barclays Bank PLC",
    "City": "London",
    "Country": "United Kingdom"
  }
}

GET /iban/generate/{country}

Generate a valid test IBAN for a specific country.

Example Request

curl -X GET "http://localhost:4000/iban/generate/GB"

Response

{
  "iban": "GB82WEST12345698765432",
  "country": "United Kingdom",
  "countryCode": "GB",
  "bankCode": "WEST"
}

Bank Lookup

GET /banks/{country}

Get a list of banks for a specific country.

Query Parameters

Parameter	Type	Description
limit	integer	Number of results to return (default: 50)
offset	integer	Number of results to skip (default: 0)

Example Request

curl -X GET "http://localhost:4000/banks/GB?limit=5"

Response

{
  "country": "GB",
  "count": 5,
  "total": 150,
  "results": [
    {
      "Bank Name": "Barclays Bank PLC",
      "City": "London",
      "SWIFT Code": "BARCGB22",
      "Country": "United Kingdom"
    }
  ]
}

GET /search/{country}

Search for banks within a specific country.

Query Parameters

Parameter	Type	Description
q	string	Search query (bank name, city, etc.)
limit	integer	Number of results to return (default: 20)

Example Request

curl -X GET "http://localhost:4000/search/GB?q=Barclays"

Response

{
  "country": "GB",
  "query": "Barclays",
  "count": 3,
  "results": [
    {
      "Bank Name": "Barclays Bank PLC",
      "City": "London",
      "SWIFT Code": "BARCGB22",
      "Country": "United Kingdom"
    }
  ]
}

BIC/SWIFT Lookup

GET /bic/{bic_code}

Lookup bank information by BIC/SWIFT code.

Example Request

curl -X GET "http://localhost:4000/bic/BARCGB22"

Response

{
  "swift_code": "BARCGB22",
  "bank_name": "Barclays Bank PLC",
  "country": "United Kingdom",
  "city": "London",
  "connection": "Live"
}

Country Data

GET /countries

Get a list of all supported countries with IBAN information.

Example Request

curl -X GET "http://localhost:4000/countries"

Response

{
  "countries": [
    {
      "code": "GB",
      "name": "United Kingdom",
      "ibanLength": 22,
      "ibanExample": "GB82 WEST 1234 5698 7654 32"
    }
  ]
}

GET /stats

Get API statistics and coverage information.

Example Request

curl -X GET "http://localhost:4000/stats"

Response

{
  "totalCountries": 75,
  "countriesWithData": 45,
  "totalBanks": 5247,
  "lastUpdated": "2025-01-09T10:00:00Z"
}

Credit Card Validation

GET /creditcard/validate/{card_number}

Validate credit card numbers using the Luhn algorithm.

Example Request

curl -X GET "http://localhost:4000/creditcard/validate/4532015112830366"

Response

{
  "valid": true,
  "cardNumber": "4532015112830366",
  "cardType": "Visa",
  "luhnValid": true
}

Error Handling

The API uses conventional HTTP response codes to indicate the success or failure of requests.

HTTP Status Codes

200 OK - Request successful

400 Bad Request - Invalid parameters

404 Not Found - Resource not found

500 Internal Server Error

Error Response Format

{
  "error": "Invalid IBAN format",
  "code": "INVALID_IBAN",
  "details": "IBAN must be between 15 and 34 characters"
}

Code Examples

JavaScript (Node.js)

const fetch = require('node-fetch');

async function validateIBAN(iban) {
  try {
    const response = await fetch(`http://localhost:4000/iban/details/${iban}`);
    const data = await response.json();
    
    if (response.ok) {
      console.log('IBAN is valid:', data);
      return data;
    } else {
      console.error('IBAN validation failed:', data.error);
      return null;
    }
  } catch (error) {
    console.error('Request failed:', error);
    return null;
  }
}

// Usage
validateIBAN('GB82WEST12345698765432');

Python

import requests
import json

def validate_iban(iban):
    url = f"http://localhost:4000/iban/details/{iban}"
    
    try:
        response = requests.get(url)
        data = response.json()
        
        if response.status_code == 200:
            print("IBAN is valid:", json.dumps(data, indent=2))
            return data
        else:
            print("IBAN validation failed:", data.get('error'))
            return None
    except requests.RequestException as e:
        print("Request failed:", e)
        return None

# Usage
validate_iban('GB82WEST12345698765432')

PHP

<?php
function validateIBAN($iban) {
    $url = "http://localhost:4000/iban/details/" . urlencode($iban);
    
    $ch = curl_init();
    curl_setopt($ch, CURLOPT_URL, $url);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_HTTPHEADER, [
        'Content-Type: application/json'
    ]);
    
    $response = curl_exec($ch);
    $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
    curl_close($ch);
    
    $data = json_decode($response, true);
    
    if ($httpCode === 200) {
        echo "IBAN is valid: " . json_encode($data, JSON_PRETTY_PRINT);
        return $data;
    } else {
        echo "IBAN validation failed: " . $data['error'];
        return null;
    }
}

// Usage
validateIBAN('GB82WEST12345698765432');
?>