IBAN Lookup

Validates an International Bank Account Number and returns its formats and country banking information.

Overview#

lookup/iban checks an IBAN passed in the iban parameter. It confirms the country code, length and check digits, then returns isValid, the IBAN in three presentations under formats (machine, human and obfuscated), and a country object with the name, ISO and IANA codes, currency, central bank, whether the country is in the EU or the SEPA area, the expected IBAN length and its SWIFT status.

When to use it#

• Catch typos in a payout or refund form before the transfer fails.
• Confirm that the bank country matches the customer's declared country.
• Store a clean, normalized IBAN, or display the obfuscated format in your interface instead of the full number.

Reading the result#

• isValid is the verdict. A false value means a wrong length for the country, an unknown country or a failed checksum, so ask the user to re-enter it.
• formats.machine is the compact string for your database and for bank APIs; formats.human groups it in blocks of four for display.
• country.isSEPA and country.isEU help you decide which transfer rails and fees apply.
• bank identifies the bank behind the IBAN's national bank code: code, name, nameAr and swift (plus mergedInto when the bank has since merged into another, for example Samba into SNB). It covers Saudi Arabia, the UAE, Kuwait, Bahrain, Qatar and Jordan, and is null for other countries, for an unrecognised code, and for an invalid IBAN.
• Validation means three things: the structure and length are right for the country, the checksum passes, and (where we have a table) the bank code is recognised. It cannot confirm that the account exists or belongs to the person: no public system can, because that needs the bank's own account-verification service. Keep your usual payout verification.

Notes#

• Counts as one request. Test mode returns fake data, is free and raises no events.
• Not part of the Standard plan; available on trial, Premium and pay-as-you-go. Without access you get error 117 (feature_not_available).
• Custom rules for the IBAN group can test the IBAN itself, its country and validity, and can mark it valid or invalid. The result is listed in custom_rules_applied.
• An invalid_iban event is raised for invalid IBANs and is sent to your webhooks.
• A missing or invalid value returns error 122 (invalid_iban) with HTTP 200.

Request#

• Authenticate with the key parameter or an Authorization: Bearer header.
• Counts as 1 request.
• Available on: Free trial Premium Pay-as-you-go

Parameters#

Every method also accepts format, lang, mode, userID, callback. See Options.

Code samples#

curl -G "https://gurdx.cretip.com/api/lookup/iban" \
  --data-urlencode "key=YOUR_API_KEY" \
  --data-urlencode "iban=SA0380000000608010167519"

<?php

$response = file_get_contents('https://gurdx.cretip.com/api/lookup/iban?'.http_build_query(['key' => 'YOUR_API_KEY', 'iban' => 'SA0380000000608010167519']));
$result = json_decode($response, true);

if ($result['status'] === 'success') {
    print_r($result['data']);
} else {
    echo $result['code'].': '.$result['description'];
}

const params = new URLSearchParams({"key":"YOUR_API_KEY","iban":"SA0380000000608010167519"});
const res = await fetch(`https://gurdx.cretip.com/api/lookup/iban?${params}`);
const result = await res.json();

if (result.status === 'success') {
  console.log(result.data);
} else {
  console.error(result.code, result.description);
}

import requests

res = requests.get("https://gurdx.cretip.com/api/lookup/iban", params={"key": "YOUR_API_KEY", "iban": "SA0380000000608010167519"})
result = res.json()

if result["status"] == "success":
    print(result["data"])
else:
    print(result["code"], result["description"])

Response#

Success#

{
    "data": {
        "isValid": true,
        "formats": {
            "machine": "BE71096123456769",
            "human": "BE71 0961 2345 6769",
            "obfuscated": "BE** **** **** 6769"
        },
        "country": {
            "name": "Belgium",
            "IANA": "be",
            "ISO3166": "BE",
            "currency": "EUR",
            "centralBank": {
                "url": "http://www.nbb.be/",
                "name": "National Bank of Belgium"
            },
            "membership": "eu_member",
            "isEU": true,
            "length": "16",
            "isSEPA": true,
            "swiftOfficial": true
        },
        "custom_rules_applied": {
            "total": 0,
            "rules": []
        },
        "bank": null
    },
    "status": "success",
    "executionTime": 1
}

Error#

Errors are delivered with HTTP 200 — always check the status field.

{
    "status": "error",
    "code": 101,
    "type": "invalid_key",
    "description": "The API Key is missing or invalid."
}

Response fields#