Verify an external account

Before you add an external account, you can verify the recipient's account with their institution. Verification confirms the account holder's name and that the account is reachable, so you can show the resolved name to your user and avoid failed transfers.

Use the Verify an external account endpoint with at least one account identifier: account_number, iban, phone, or clabe. Pass institution_id (from Get external account institutions) to speed up and disambiguate the lookup.

Verification is supported for bank accounts and mobile money today. Other types return is_verified: false.

Verify a bank account

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": "1776218486",
  "institution_id": "c0cb83fa-8116-4744-8bc8-0c1cba405400",
  "country_code": "NG"
}
'

When the account resolves, is_verified is true and account_name holds the confirmed holder name:

{
  "data": {
    "is_verified": true,
    "account_name": "Amina Bello",
    "account_number": "1776218486",
    "account_status": "active",
    "account_type": "bank_account",
    "bank_name": "Access Bank",
    "bank_code": null,
    "address": null,
    "institutions": null
  },
  "error": null
}

When an account does not resolve

If the account cannot be resolved, is_verified is false. Any institutions that matched the identifier come back in institutions so the user can pick the right one and retry:

{
  "data": {
    "is_verified": false,
    "account_name": null,
    "account_number": "1776218486",
    "institutions": [
      {
        "id": "c0cb83fa-8116-4744-8bc8-0c1cba405400",
        "name": "Access Bank",
        "country_iso_code": "NG",
        "currency": "NGN"
      }
    ]
  },
  "error": null
}

A 400 means no identifier was supplied, or the one you sent failed format validation. Fix the input and retry.