IBAN validation & bank lookup
Validate IBAN format, country, length, MOD-97 checksum and BBAN structure, and resolve the bank behind the IBAN (SWIFT/BIC).
本文档适用于 API V1。
本页内容
Endpoint
Validates an IBAN end-to-end: normalization, country support, length, allowed characters, MOD-97 checksum, national structure and BBAN segment parsing.
GET https://api.ecommica.com/v1/iban/validate?iban={iban}Parameters
| Name | Type | In | Description |
|---|---|---|---|
| iban | string | query | The IBAN to validate. Spaces and dashes are stripped; input is uppercased. |
Example request
curl -s "https://api.ecommica.com/v1/iban/validate?iban=DE89 3704 0044 0532 0130 00" \
-H "Authorization: Bearer sk_xxx"Example response
{
"data": {
"valid": true,
"iban": "DE89370400440532013000",
"country": "DE",
"check_digits": "89",
"bank_code": "37040044",
"account_number": "0532013000",
"length": 22,
"expected_length": 22,
"checks": {
"charset": true,
"country": true,
"length": true,
"checksum": true,
"structure": true
}
},
"meta": { "request_id": "req_1a2b3c4d" }
}Errors
| Code | Description |
|---|---|
| INVALID_IBAN | The IBAN failed format, checksum or structure validation. |
| IBAN_UNSUPPORTED_COUNTRY | The country does not participate in IBAN. |
| MISSING_PARAMETER | The iban query parameter is absent. |
Bank lookup
The lookup endpoint validates the IBAN and resolves the bank behind it, local-first: the BBAN bank code is mapped through the FinCode bank-code → SWIFT/BIC directory, and the SWIFT directory supplies the institution details. Unknown banks are enriched from the upstream provider and persisted, so later lookups hit the directory directly. A valid IBAN whose bank is not in the directory yet still returns valid: true — the bank field is simply omitted.
GET https://api.ecommica.com/v1/iban/{iban}Parameters
| Name | Type | In | Description |
|---|---|---|---|
| iban | string | path | The IBAN to validate and enrich with bank details. |
Example request
curl -s "https://api.ecommica.com/v1/iban/DE16200700000532013000" \
-H "Authorization: Bearer sk_xxx"Example response
{
"data": {
"valid": true,
"iban": "DE16200700000532013000",
"country": "DE",
"check_digits": "16",
"bank_code": "20070000",
"account_number": "0532013000",
"length": 22,
"expected_length": 22,
"bank": {
"swift_code": "DEUTDEHH",
"bic": "DEUTDEHH",
"bank": {
"name_en": "DEUTSCHE BANK AG",
"country": "DE"
},
"city": "Hamburg",
"status": "ACTIVE"
}
},
"meta": { "request_id": "req_5f8d2c41" }
}Notes
This endpoint is also available anonymously for the website IBAN checker and is rate-limited per network address. Bank availability never affects the validity result — validation is a pure format and checksum computation.
Notes
A valid IBAN confirms format, length and checksum — it does not confirm that the account exists. FinCode never claims account existence from format validation alone.