Validate an IBAN and identify the institution that holds the account.
Performs format check, country-specific length check, and
ISO 7064 mod-97 checksum verification. Also returns COUNTRY-level
banking rules for the IBAN's country prefix (national currency,
SEPA status, expected format).
CROSS-CHECKS THE BENEFICIARY BANK. Where the country's IBAN registry
mask defines the bank identifier as four alpha characters (GB, NL, IE,
RO, PK, MT, JO, QA, KW and others), `bank_identifier.resolved_institution`
names the institution that actually holds the account, read out of the
IBAN itself. Call this whenever the user supplies an IBAN AND names a
beneficiary bank or BIC — if the two disagree, that mismatch is a far
better explanation for a rejected or returned payment than anything you
can infer, and it is invisible without this call. Everywhere else the
bank identifier is a NATIONAL bank/sort code (the German BLZ, Italian
ABI, French code banque): `bank_identifier.code` is those characters,
`is_bic_prefix` is false, and no institution is named — quote the code
when telling the user what to check, never a bank name derived from it.
A FAILURE IS NOT ALWAYS A CHECKSUM FAILURE. An IBAN of the right length
whose characters break the country's mask (a letter where the country
requires a digit — O for 0, I for 1) is refused BEFORE mod-97 runs, with
`format_violations` naming the position. Report the position and the
character; do not tell the user the check digits are wrong.
`valid: true` means the check digits are right and NOTHING MORE — not
that the account exists, is open, or belongs to the named beneficiary or
the named bank. Never rule out the account details on the strength of it
when diagnosing a failed payment (see `verification_note`).
An IBAN encodes country + bank + account number and carries NO
currency information. `country_currency` is the country's national
currency, NOT this account's denomination — never infer a currency
mismatch or a "resend in X" recommendation from it (see
`currency_note` in the response).
Examples:
iban_validate("DE89370400440532013000")
iban_validate("GB29 NWBK 6016 1331 9268 19")