GET /iban/resolve

Resolves an IBAN in a single call: structural validity (all ISO 13616 countries), issuing bank, BIC and reachability (countries covered by the local bank registry) — including SEPA reachability per scheme (SCT, SCT Inst, SDD Core/B2B) from the EPC register when the bank’s BIC is known. Purely local lookup → response in milliseconds.

x402 golden rule: the agent pays for the answer to its question. “This IBAN is invalid” is a successful answer → 200 with valid: false. The 4xx range is reserved for requests the service cannot answer.

Parameters

200 response — UnifiedResponse

{
  "data": { ... },
  "provenance": {
    "source": "national-bank-registries",
    "fetched_at": "2026-06-12T09:30:00Z",
    "freshness": { "kind": "snapshot", "as_of": "2026-06-11T00:00:00Z" }
  }
}

• provenance.source: stable identifier of the bank registry.
• freshness.as_of: date of the registry snapshot (meta.json).

A single provenance block describes the whole answer. SEPA reachability comes from a second snapshot (the EPC register); its own freshness is exposed by the gateway’s /health (data.reachability.as_of) rather than a second provenance block here.

Fields of data

sepa_reachability

Present only when the bank’s BIC is known and listed in the EPC register. Otherwise it is null (unknowable) — never a false false, exactly like reachable.

"sepa_reachability": {
  "sct": true,
  "sct_inst": true,
  "sdd_core": true,
  "sdd_b2b": false,
  "schemes": ["SCT", "SCT_INST", "SDD_CORE"]
}

This answers the payout question — will a SEPA Instant transfer go through before I send? — at the PSP level.

Reference-BIC caveat. The EPC register lists reference BICs. The block reports reachability at the PSP level for each scheme; it is not a routing guarantee for a specific account. Treat it as a decision-support signal, not a settlement promise.

Case 1 — valid IBAN, bank found

coverage: "full", reachable: true.

{
  "iban": "DE77100000000000000000",
  "valid": true,
  "country": "DE",
  "bank_code": "10000000",
  "branch_code": null,
  "bank": { "name": "Bundesbank", "bic": "MARKDEF1100" },
  "reachable": true,
  "coverage": "full",
  "issue": null,
  "sepa_reachability": {
    "sct": true,
    "sct_inst": true,
    "sdd_core": true,
    "sdd_b2b": false,
    "schemes": ["SCT", "SCT_INST", "SDD_CORE"]
  }
}

When the BIC is unknown or absent from the EPC register (Cases 2–4 below), sepa_reachability is null.

Case 2 — valid IBAN, country covered but bank unknown

Strong signal: the account is probably unreachable.

{
  "iban": "DE36000000000000000000",
  "valid": true,
  "country": "DE",
  "bank_code": "00000000",
  "branch_code": null,
  "bank": null,
  "reachable": false,
  "coverage": "full",
  "issue": null
}

Case 3 — valid IBAN, country outside the registry

Only the structure is guaranteed: reachable is unknowable.

{
  "iban": "FR1420041010050500013M02606",
  "valid": true,
  "country": "FR",
  "bank_code": "20041",
  "branch_code": null,
  "bank": null,
  "reachable": null,
  "coverage": "structure_only",
  "issue": null
}

Case 4 — invalid IBAN (successful answer → 200)

country/bank_code are filled in if they could be extracted before the failure (e.g. INVALID_BBAN), otherwise null.

{
  "iban": "DE89370400440532013001",
  "valid": false,
  "country": null,
  "bank_code": null,
  "branch_code": null,
  "bank": null,
  "reachable": null,
  "coverage": null,
  "issue": "BAD_CHECKSUM"
}

Possible issue codes: BAD_CHARACTERS, BAD_LENGTH, BAD_FORMAT, BAD_CHECKSUM, UNKNOWN_COUNTRY, INVALID_BBAN.

Errors

{ "error": "missing or empty required parameter: iban", "code": "MISSING_PARAMETER" }