Banks

List banks and resolve an account number to its holder's name.

Contents

Banks and name enquiry

Two endpoints sit underneath every “where should we send this?” form: one that lists the banks you may send to, and one that turns a bank code plus an account number into the account holder’s real name. Use them in that order and a payout can never be addressed to an account that does not exist.

No scope required

Both routes accept a secret key or a dashboard session and check no scope beyond being authenticated. They read public banking-directory data and perform a lookup — neither moves money nor exposes anything about your account.

List banks

GET/v1/banks

Auth: Secret key or dashboard session

Query parameters

Field	Type	Description
country	string	Two-letter ISO country code. Defaults to `NG`, which is currently the only supported value.
environment	"test" \| "live"	Required for a dashboard session. Ignored for an API key, which carries its own.

curl

curl "https://api.radokpay.com/v1/banks?country=NG" \
  -H "Authorization: Bearer $RADOK_SECRET_KEY"

200 OK

{
  "data": [
    { "code": "058", "name": "Guaranty Trust Bank" },
    { "code": "044", "name": "Access Bank" },
    { "code": "033", "name": "United Bank for Africa" }
  ]
}

code is the CBN bank code, and it is what every other endpoint means by bankCode. Cache the list — it changes a few times a year, not a few times a minute — but key your cache on the code, never on the name. Banks rename; codes do not.

Verify an account (name enquiry)

POST/v1/banks/verify-account

Auth: Secret key or dashboard session

Body

Field	Type	Description
bankCoderequired	string	A `code` from `GET /v1/banks`.
accountNumberrequired	string	The 10-digit NUBAN.

curl

curl -X POST https://api.radokpay.com/v1/banks/verify-account \
  -H "Authorization: Bearer $RADOK_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "bankCode": "058",
    "accountNumber": "0123456789"
  }'

200 OK

{
  "data": {
    "bankCode": "058",
    "accountNumber": "0123456789",
    "accountName": "ADA LOVELACE"
  }
}

Show the name to a human before you send money

Name enquiry is the only step that catches a mistyped account number, because a typo usually lands on a real account belonging to someone else. Render the returned accountName and make a person confirm it. Do not resolve it in the background and proceed.

Where the result goes next

To pay a third party once, pass the verified values straight into POST /v1/payouts as destination.
To pay the same account repeatedly, save it as a payout account in the dashboard and use its id instead. Radok re-runs name enquiry when you save it and stores the name the bank returned.

After verifying

{
  "amount": { "value": 250000, "currency": "NGN" },
  "destination": {
    "bankCode": "058",
    "accountNumber": "0123456789",
    "accountName": "ADA LOVELACE"
  }
}

Pass back the accountName exactly as it was returned. Radok compares it to its own enquiry at payout time, and a name you invented will not match.

What can go wrong

Errors

Field	Type	Description
VALIDATION_ERROR	422	A missing `bankCode` or `accountNumber`, or a `country` that is not exactly two characters.
AUTH_REQUIRED	401	No credential, or a revoked key.
IP_NOT_ALLOWED	403	The key has an IP allowlist and this request did not come from it.
INTERNAL_ERROR	500	Today, an account number the bank cannot resolve also arrives here rather than as a typed error. See the caveat below.

An unresolvable account is currently a 500

POST /v1/banks/verify-account does not yet map name-enquiry failures onto a typed error code. A number the bank rejects surfaces as 500 INTERNAL_ERROR, indistinguishable from a genuine outage. Until that is fixed, treat a 500 from this endpoint as “could not verify” and let the user correct the number — do not retry it automatically, and never fall through to a payout with an unverified account.