oneapi
Sign in
Financiar v1 / Validare

IBAN validation

Checks an IBAN against ISO 13616 (structure, per-country length, mod-97 check digits) and, for Romanian IBANs, identifies the issuing bank.

A wrong IBAN is NOT a request error: the response is 200 with valid: false and a code in motiv saying what is wrong — form, length or check digits.

POST
https://oneapi.ro/api/financiar/v1/validare/iban

Request body

Sent as JSON in the request body (Content-Type: application/json) — not in the query string.

NameTypeDescriptionAccepted values
ibanrequired string Required, in the request body. With or without spaces/hyphens, upper or lower case. max 42 car.
Romanian IBAN Request body 
{
    "iban": "RO49AAAA1B31007593840000"
}
A German IBAN Request body 
{
    "iban": "DE89370400440532013000"
}
Written with spaces and lowercase Request body 
{
    "iban": "ro49 aaaa 1b31 0075 9384 0000"
}
Wrong check digits Request body 
{
    "iban": "RO49AAAA1B31007593840001"
}

Query parameters

This route accepts no query parameters.

How it behaves

  • Validates an IBAN against ISO 13616: structure, per-country length and the mod-97 check digits. For Romanian IBANs it also identifies the issuing bank.
  • Any usual formatting is accepted: grouping spaces, hyphens, lowercase. The response returns the canonical form in iban.
  • A wrong IBAN is not a bad request. The response is 200 with valid: false and a code in motiv saying what is wrong: forma_invalida, lungime_gresita (with lungime_asteptata) or control_invalid. An unexplained "invalid" helps nobody who transposed two digits.
  • The method is POST, not GET, because an IBAN identifies someone's account and a query string ends up in access logs, in telemetry and in browser history.
  • The bank is only reported when the code belongs to a confirmed credit institution. The BIC register we start from holds 76 Romanian entities, 50 of which are not banks: a brewery, the Stock Exchange, brokerage houses. An IBAN built on such a code cannot exist, so the answer is motiv_banca: "nu_e_institutie_de_credit" rather than the entity name. The name appears separately, in entitate_cu_acest_cod, as a debugging aid.
  • Bank identification works for Romania only: complete BIC/SWIFT directories are licensed and we do not use them. For foreign IBANs motiv_banca is doar_pentru_romania — a declared limit, not an unexplained null.
  • Coverage: 26 confirmed credit institutions, including branches of foreign banks (ING, Citibank, Revolut, BNP Paribas). Those have no LEI of their own, only the parent company's, so they are confirmed by name matching against the NBR register.

What it is for

  • Validating an IBAN in a form before storing it.
  • Identifying the bank for display or payment routing.
  • Debugging a mistyped IBAN.

Response structure

FieldTypeDescription
data[] object[]
meta.temei string The legal basis for the values or for the way they are computed.
meta.sursa_banci string
meta.nota string A note on how to read the response — a pitfall, a convention or a limit of the source.
data.iban string Canonical form: uppercase, no spaces.
data.valid boolean The ISO 13616 verification result.
data.motiv null The defect code when valid is false; null otherwise.
data.lungime_asteptata integer The official length for that country. null for countries outside the table, where only the mod-97 check remains.
data.cod_banca string The four letters after the check digits, for Romanian IBANs.
data.banca null The credit institution: name from the NBR register, BIC, tax code, LEI and status. null when it cannot be identified.
data[].banca.tip institutie_credit or trezoreria_statului — the TREZ code of State Treasury accounts, where cui, lei and stare are null.
data.motiv_banca string Why the bank is missing: doar_pentru_romania, cod_necunoscut, nu_e_institutie_de_credit.
data[].entitate_cu_acest_cod Present only with nu_e_institutie_de_credit: which entity holds the code, as a debugging aid.

Response examples

body: {"iban": "RO49AAAA1B31007593840000"}

POSThttps://oneapi.ro/api/financiar/v1/validare/iban
{
    "data": {
        "iban": "RO49AAAA1B31007593840000",
        "valid": true,
        "tara": "RO",
        "lungime": 24,
        "lungime_asteptata": 24,
        "motiv": null,
        "cod_banca": "AAAA",
        "banca": null,
        "motiv_banca": "cod_necunoscut"
    },
    "meta": {
        "temei": "ISO 13616; control mod-97 calculat pe bucăţi.",
        "sursa_banci": "GLEIF (mapare BIC↔LEI, licenţă CC0) + registrul BNR al instituţiilor de credit; codul `TREZ` al Trezoreriei Statului e ţinut local.",
        "nota": "IBAN valid ca structură, dar codul de bancă nu apare în registru. Verifică transcrierea: cifrele de control nu prind o literă greşită în codul băncii dacă rezultatul rămâne divizibil."
    }
}

Error codes

CodeSlugWhen it occurs
401neautentificatToken missing, invalid, expired or revoked.
403feature_indisponibilThe current plan does not include the feature the route depends on.
422validareiban missing or of an impossible length. An IBAN that is present but wrong returns 200 with valid: false.
429cota_depasitaThe plan's monthly quota has been exceeded (see Retry-After).

All errors share the same shape. eroare.cod is stable and is the value you should branch on in code — not the text in mesaj, which may change.

{
    "eroare": {
        "cod": "validare",
        "mesaj": "iban missing or of an impossible length. An IBAN that is present but wrong returns 200 with valid: false."
    }
}