post
https://api.idwise.com/journey/iban-verifications
Checks that a bank account (IBAN) belongs to the expected person or business. The result is returned synchronously in the same response. Use it to confirm account ownership before a payout, withdrawal or account-linking step, and to reduce fraud from mule or third-party accounts.
Authentication
This API uses HTTP Basic Authentication. Send your API key and secret as a base64-encoded ey:secret pair in the Authorization header.
Authorization: Basic <base64(api_key:api_secret)>
Content-Type: application/jsonSandbox and Live environments use separate credentials. Sandbox requests do not count towards your verification quota but run against mock test data.
Request body
| Field | Type | Required | Description |
|---|---|---|---|
customer_type | string (enum) | Yes | Type of account holder. Possible values areindividual or business. |
country_code | string (2 chars) | Yes | Country where the account is held, in ISO 3166-1 alpha-2 format. Supported: AE. |
iban | string | Yes | The IBAN to verify, without spaces. |
identifiers | array of objects | Yes | Details of the expected account holder. Minimum 1, maximum 2 items. See below for further details. |
identifiers[] object
identifiers[] object| Field | Type | Required | Description |
|---|---|---|---|
type | string (enum) | Yes | Type of identifier. See the allowed values in the table below. |
value | string | Yes | Identifier value. |
Allowed identifier types
customer_type | type | Description | Example |
|---|---|---|---|
individual | emirates_id | Emirates ID number, 15 digits, no dashes | 784198012345678 |
individual | full_name | Full name as registered with the bank | Ahmed Ali Hassan |
business | trade_licence | Trade licence number | CN-1234567 |
business | business_name | Registered business name | Example Trading LLC |
Rules
- Send the ID identifier (
emirates_idortrade_licence), the name identifier (full_nameorbusiness_name), or both. - Sending both gives the most reliable result.
- Identifier types must match the
customer_type. For example,trade_licenceis rejected forindividual.
Testing in Sandbox
Use the test data below with your Sandbox credentials to try each scenario. Send country_code: "AE", the IBAN from the row, and the identifier shown. Sandbox requests do not count towards your quota.
Individuals (customer_type: "individual")
customer_type: "individual")| Scenario | full_name | emirates_id | iban |
|---|---|---|---|
| Full match | ADAM AHMED | — | AE420260001015819612801 |
| No match | ADAM STARK | — | AE420260001015819612801 |
| Partial match | ADAM SOMETHING | — | AE420260001015819612801 |
| Full match | LYNNA GRAIG TOY | — | AE970424090886582129014 |
| Full match | IMA ELINORE SPINKA | — | AE340176545036785802838 |
| Full match | — | 784196710121542 | AE620030012285049920001 |
| Full match | — | 784-1967-1012154-2 | AE620030012285049920001 |
| Blocked account | BLOCKED USER | — | AE810030012459313920001 |
| Bank unavailable | BANK ERROR TEST | — | AE160030011522789920001 |
| Not supported by bank | UNSUPPORTED TEST | — | AE420500000000028645064 |
| Disabled by provider | DISABLED TEST | — | AE100500000000028538649 |
Businesses (customer_type: "business")
customer_type: "business")| Scenario | business_name | trade_licence | iban |
|---|---|---|---|
| Full match | ABC LIMITED | — | AE620030012285049920001 |
| No match | ABC SOMETHING | — | AE620030012285049920001 |
| Partial match | ABC LIMIT | — | AE620030012285049920001 |
| Full match | — | TLCL4206 | AE620030012285049920001 |
| Full match | — | TL000004778 | AE620030012285049920001 |
Response
The response returned in case of an accepted request contains the following fields:
| Field | Type | Description |
|---|---|---|
id | string (UUID) | Unique ID of this IBAN verification transaction. Use it for support and reconciliation. |
tenant_id | string (UUID) | ID of your IDWise tenant account. |
environment_type | string (enum) | Environment the verification ran in: sandbox or live. |
customer_type | string | Customer type sent in the request. |
country_code | string | Country code sent in the request. |
iban | string | IBAN sent in the request. |
identifiers | array of objects | Identifiers sent in the request. |
status | string | Processing status. completed means the bank returned a result. |
created_at | string | Time the verification was created (UTC). |
result | string | Overall outcome of the verification, e.g. verified. |
ownership_verified | boolean | true when the account holder matches the identifiers provided. |
matching_type | string (enum) | null | How closely the identifiers match the account holder: FULL, PARTIAL or NONE. See Matching types.This value is null when ownership is verified directly by the bank. |
matching_score | number (0–1) | null | Confidence of the match, from 0 (no match) to 1 (exact match). Returned with matching_type. |
account_holder_name | string | null | Account holder name as held by the bank, where the bank returns it. |
account_status | string (enum) | Status of the bank account: ACTIVE or INACTIVE. |
account_currency | string | null | Account currency (ISO 4217, e.g. AED), where the bank returns it. |
bank_name | string | null | Name of the bank holding the account. |
bank_identifiers | array of objects | Identifiers of the bank holding the account. |
bank_identifiers[].type | string (enum) | Type of bank identifier: BIC, SWIFT_CODE, BANK_CODE, CLEARING_ID or ACCOUNT_ID. |
bank_identifiers[].value | string | Identifier value, e.g. EBILAEADXXX. |
results_id | string (UUID) | Reference ID of the bank verification result. Share it with IDWise support when you require support on this transaction. |
created_by | string | Who created the verification, e.g. server API Key for API calls. |
request_id | string (UUID) | ID of the API request. Useful for tracing and support. |
Matching types
matching_type | ownership_verified | Meaning | Suggested action |
|---|---|---|---|
null | true | The bank confirmed the account belongs to the person or business provided. | Proceed. |
FULL | true | The identifiers fully match the account holder. | Proceed. |
PARTIAL | false | Close but not exact, e.g. a missing middle name or a spelling difference. matching_score shows how close. | Review manually, or ask the customer to confirm their details. |
NONE | false | The account does not belong to the person or business provided. | Do not proceed. Treat as high risk. |