Skip to content
FinCode

IBAN validation & bank lookup

Validate IBAN format, country, length, MOD-97 checksum and BBAN structure, and resolve the bank behind the IBAN (SWIFT/BIC).

This documentation covers API V1.

Endpoint

Validates an IBAN end-to-end: normalization, country support, length, allowed characters, MOD-97 checksum, national structure and BBAN segment parsing.

http
GET https://api.ecommica.com/v1/iban/validate?iban={iban}

Parameters

NameTypeInDescription
ibanstringqueryThe IBAN to validate. Spaces and dashes are stripped; input is uppercased.

Example request

bash
curl -s "https://api.ecommica.com/v1/iban/validate?iban=DE89 3704 0044 0532 0130 00" \
  -H "Authorization: Bearer sk_xxx"

Example response

json
{
  "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

CodeDescription
INVALID_IBANThe IBAN failed format, checksum or structure validation.
IBAN_UNSUPPORTED_COUNTRYThe country does not participate in IBAN.
MISSING_PARAMETERThe 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.

http
GET https://api.ecommica.com/v1/iban/{iban}

Parameters

NameTypeInDescription
ibanstringpathThe IBAN to validate and enrich with bank details.

Example request

bash
curl -s "https://api.ecommica.com/v1/iban/DE16200700000532013000" \
  -H "Authorization: Bearer sk_xxx"

Example response

json
{
  "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.