Verify an external account

Check a bank account's holder name with the bank before you save the payee.

This page shows how to ask the bank who holds an account number before you add an external account. Show the name to your user so they can confirm it is the right person before any money moves.

Example. Your user types her brother's 10-digit Nigerian account number and picks his bank. Verify returns CHINEDU OKECHUKWU EZE with verification_source provider. She confirms it is him, and you save the payee.

Verify covers bank account numbers only. The bank looks up one pair: account_number with its institution_id. An iban gets a format (mod-97) check only. The API accepts a phone or clabe but does not check it. Gravv checks mobile wallet names when you save the payee instead.

Verify a bank account

Call POST /v1/external-accounts/verify with the account number and the bank's institution_id from Retrieve supported institutions. This endpoint needs no Idempotency-Key:

curl --request POST \
     --url https://api.gravv.xyz/v1/external-accounts/verify \
     --header 'Api-Key: <API_KEY>' \
     --header 'Content-Type: application/json' \
     --data '
{
  "account_number": "0123456789",
  "institution_id": "2ce313c8-de20-48dd-bfc6-949b8fd5ad84"
}
'

{
  "data": {
    "verified": true,
    "account_holder_name": "CHINEDU OKECHUKWU EZE",
    "verification_source": "provider"
  },
  "error": null
}

Trust the name only when verification_source is provider, which means the bank looked the account up. verified: true with verification_source local means the API checked only the format.

Check an IBAN's format

curl --request POST \
     --url https://api.gravv.xyz/v1/external-accounts/verify \
     --header 'Api-Key: <API_KEY>' \
     --header 'Content-Type: application/json' \
     --data '
{
  "iban": "DE89370400440532013000"
}
'

{
  "data": {
    "verified": true,
    "verification_source": "local"
  },
  "error": null
}

This check confirms that the IBAN is well formed. It does not confirm that the account exists or who holds it.

When an account does not verify

verified is false and message says why:

{
  "data": {
    "verified": false,
    "message": "IBAN checksum invalid (mod 97 = 28, expected 1)"
  },
  "error": null
}

A 400 means you sent no identifier (at least one account identifier required: account_number, iban, phone, or clabe) or the institution_id is not valid. Without an institution_id, the API does not limit the account number lookup to one bank.

Testing in sandbox

In sandbox, every Nigerian account number verifies, with the name SIM ACCOUNT HOLDER and verification_source provider.