Validate IBAN
Validate a single IBAN with full checksum verification, country-specific BBAN structure parsing, automatic BIC/institution lookup, SEPA compliance data, issuer classification (bank vs. EMI/neobank), and risk indicators for compliance agents.
Endpoint
POST https://api.ibanforge.com/v1/iban/validate
Cost: $0.005 USDC per request
Request
Headers
| Header | Value | Required |
|---|---|---|
Content-Type | application/json | Yes |
Authorization | Bearer ifk_... (free API key) | One of the two |
X-PAYMENT | x402 payment token | One of the two |
Body
{
"iban": "CH10 0023 0000 0000 1234 5"
}| Field | Type | Description |
|---|---|---|
iban | string | The IBAN to validate. Spaces and hyphens are stripped automatically. Case-insensitive. |
Response
Success (200)
{
"iban": "CH1000230000000012345",
"valid": true,
"country": {
"code": "CH",
"name": "Switzerland"
},
"check_digits": "10",
"bban": {
"bank_code": "00230",
"account_number": "000000012345"
},
"bic": {
"code": "UBSWCHZH",
"bank_name": "UBS Switzerland AG",
"city": "Zürich"
},
"sepa": {
"member": true,
"schemes": ["SCT", "SDD"],
"vop_required": false
},
"issuer": {
"type": "bank",
"name": "UBS Switzerland AG"
},
"risk_indicators": {
"issuer_type": "bank",
"country_risk": "standard",
"test_bic": false,
"sepa_reachable": true,
"vop_coverage": false
},
"clearing": {
"iid": "00230",
"name": "UBS Switzerland AG",
"type": "bank",
"town": "Zürich",
"sic": true,
"instant_payments_chf": true,
"eurosic": true,
"qr_iid": null
},
"formatted": "CH10 0023 0000 0000 1234 5",
"cost_usdc": 0.005,
"processing_ms": 1.23
}Response fields
Top-level fields:
| Field | Type | Present | Description |
|---|---|---|---|
iban | string | Always | Cleaned IBAN (uppercase, no spaces) |
valid | boolean | Always | Whether the IBAN passed all validation checks |
country | object | Valid IBANs | Country code and name |
check_digits | string | Valid IBANs | The two-digit check number |
bban | object | Valid IBANs | Parsed BBAN components |
bic | object | null | Valid IBANs | BIC/SWIFT code and institution data (null if no match found) |
sepa | object | Valid IBANs | SEPA membership, schemes, and VoP requirement |
issuer | object | Valid IBANs with BIC | Institution classification |
risk_indicators | object | Valid IBANs | Composite risk signal for compliance |
clearing | object | null | Valid CH/LI IBANs | Swiss clearing data from the SIX BankMaster (BC-Nummer, rail participation, QR-IID); null when the IID is not listed |
formatted | string | Valid IBANs | IBAN with spaces every 4 characters |
error | string | Invalid IBANs | Error code |
error_detail | string | Invalid IBANs | Human-readable error description |
cost_usdc | number | Always | Cost of this request in USDC |
processing_ms | number | Always | Processing time in milliseconds |
country object:
| Field | Type | Description |
|---|---|---|
code | string | ISO 3166-1 alpha-2 country code |
name | string | Full country name in English |
bban object:
| Field | Type | Description |
|---|---|---|
bank_code | string | Bank/institution identifier extracted from BBAN |
branch_code | string? | Branch code (present for countries like FR, GB, ES, IT) |
account_number | string | Account number extracted from BBAN |
bic object (present when a matching BIC is found):
| Field | Type | Description |
|---|---|---|
code | string | BIC/SWIFT code (8 characters) |
bank_name | string | null | Financial institution name |
city | string | null | City of the institution |
sepa object:
| Field | Type | Description |
|---|---|---|
member | boolean | Whether this country is in the SEPA zone |
schemes | string[] | Available SEPA schemes: SCT (Credit Transfer), SDD (Direct Debit), SCT_INST (Instant) |
vop_required | boolean | Whether Verification of Payee is mandatory (EU regulation, since Oct 2025 for eurozone) |
issuer object (present when BIC is resolved):
| Field | Type | Description |
|---|---|---|
type | string | bank (traditional), digital_bank (neobank), emi (Electronic Money Institution), or payment_institution |
name | string | Institution name |
vIBAN detection: If
issuer.typeisemi,digital_bank, orpayment_institution, the IBAN is more likely to be a virtual IBAN (vIBAN). This is useful for AML/CFT compliance under the EU AMLR regulation (July 2027).
risk_indicators object:
| Field | Type | Description |
|---|---|---|
issuer_type | string | Same as issuer.type — bank, digital_bank, emi, or payment_institution |
country_risk | string | standard, elevated (FATF grey list), or high (FATF black list / EU high-risk) |
test_bic | boolean | Whether the BIC is a test/sandbox code |
sepa_reachable | boolean | Whether the account is in the SEPA zone |
vop_coverage | boolean | Whether VoP is mandatory for this country |
Invalid IBAN (200)
When the IBAN is invalid, the response still returns 200 but with valid: false:
{
"iban": "CH5604835012345678000",
"valid": false,
"error": "checksum_failed",
"error_detail": "Modulo 97 check returned 42, expected 1.",
"cost_usdc": 0.005
}Error codes
| Code | Description |
|---|---|
invalid_format | IBAN contains invalid characters or is too short |
unsupported_country | Country code is not recognized |
wrong_length | IBAN length does not match expected length for this country |
checksum_failed | MOD-97 checksum verification failed |
Code examples
cURL
curl -X POST https://api.ibanforge.com/v1/iban/validate \
-H "Content-Type: application/json" \
-d '{"iban": "DE89 3704 0044 0532 0130 00"}'Python
import requests
response = requests.post(
"https://api.ibanforge.com/v1/iban/validate",
json={"iban": "DE89370400440532013000"},
)
data = response.json()
if data["valid"]:
print(f"Bank: {data['bic']['bank_name']}")
print(f"Country: {data['country']['name']}")
print(f"SEPA: {data['sepa']['member']}")
print(f"Issuer type: {data['issuer']['type']}")
print(f"Risk: {data['risk_indicators']['country_risk']}")
else:
print(f"Invalid: {data['error_detail']}")TypeScript
const response = await fetch(
"https://api.ibanforge.com/v1/iban/validate",
{
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({ iban: "DE89370400440532013000" }),
}
);
const data = await response.json();
if (data.valid) {
console.log(`Bank: ${data.bic.bank_name}`);
console.log(`SEPA: ${data.sepa.member}, VoP: ${data.sepa.vop_required}`);
console.log(`Issuer: ${data.issuer.type} — ${data.issuer.name}`);
console.log(`Country risk: ${data.risk_indicators.country_risk}`);
} else {
console.log(`Invalid: ${data.error_detail}`);
}