Payout accounts

Save and verify the bank accounts you withdraw to.

Contents

Why saved payout accounts exist

You can send a payout to a raw bank account on every request, but you probably should not. A saved payout account is verified once against the bank’s name-enquiry service, stored with the name the bank returned, and referenced by id afterwards — so a typo in an account number fails at the moment you add it, not at the moment money leaves.

Managed in the dashboard, not through the API

Adding, re-pointing, and removing a payout account are dashboard actions gated behind your password and 2FA. They are deliberately unreachable with an API key: changing where money goes is the classic account-takeover payload, and a leaked key must not be able to do it. API keys can read the list, so a programmatic integration can discover the id it needs.

Adding an account

Go to Money out → Payout accounts.
Pick the bank and enter the 10-digit NUBAN.
Press Verify account. The bank returns the account holder’s name. Read it — this is your one chance to notice you are about to save someone else’s account.
Confirm with your password and 2FA code.

The name you see is the name that gets stored. Radok never accepts an account name from the client, so the label on a payout can never disagree with where the money lands.

Accounts are per environment

A test payout account and a live one are separate records, even for the same bank account. The environment switch in the top bar decides which list you are editing.

The default account

The first account you add in an environment becomes its default automatically.
A payout created without a destination or a payoutAccountId goes to the default. This is the recommended way to integrate: your code names an amount, and where it goes is a decision made in the dashboard by someone authorised to make it.
There is at most one default per environment, enforced by the database rather than by application logic — two people changing it at once cannot both win.
You cannot remove the default while other accounts exist. Nominate a replacement first, or you would be left with several accounts and no default, and the next payout without an explicit destination would fail.

List payout accounts

GET/v1/payout-accounts

Auth: Secret key or dashboard session
Scope: payouts:read

Query

Field	Type	Description
environment	string	`test` or `live`. Required for dashboard sessions only — an API key already carries its environment.

curl

curl https://api.radokpay.com/v1/payout-accounts \
  -H "Authorization: Bearer $RADOK_SECRET_KEY"

200 OK

{
  "data": [
    {
      "id": "652f1a9c4d7b3e0812345678",
      "environment": "live",
      "bankCode": "058",
      "bankName": "Guaranty Trust Bank",
      "accountNumberMasked": "••••••4821",
      "accountNumberLast4": "4821",
      "accountName": "ACME STORES LIMITED",
      "isDefault": true,
      "status": "active",
      "verifiedAt": "2026-08-20T09:12:44.000Z",
      "createdAt": "2026-08-20T09:12:44.000Z"
    }
  ]
}

The full account number is never returned

Only a masked form and the last four digits leave the server. There is nothing in an API response, a log line, or a browser devtools panel that reveals the whole number.

Retrieve one account

GET/v1/payout-accounts/{payoutAccountId}

Auth: Secret key or dashboard session
Scope: payouts:read

curl

curl https://api.radokpay.com/v1/payout-accounts/652f1a9c4d7b3e0812345678 \
  -H "Authorization: Bearer $RADOK_SECRET_KEY"

Bank codes and name enquiry

Two endpoints back the dashboard’s add-account form, and both are available to your own integration.

GET/v1/banks?country=NG

Auth: Secret key or dashboard session

Cached for an hour, per environment. A test-mode caller is served by the stub gateway rather than the live PSP.

200 OK

{
  "data": [
    { "name": "Guaranty Trust Bank", "code": "058", "country": "NG" },
    { "name": "First Bank of Nigeria", "code": "011", "country": "NG" }
  ]
}

POST/v1/banks/verify-account

Auth: Secret key or dashboard session

Name enquiry. A test-mode caller resolves through the stub gateway and never reaches the real bank.

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": "0123454821" }'

200 OK

{
  "data": {
    "bankCode": "058",
    "accountNumber": "0123454821",
    "accountName": "ACME STORES LIMITED"
  }
}

Name enquiry hits the live bank

In live mode each call reaches the real bank and counts against the write rate limit. Call it once when a user enters an account, not on every keystroke. Radok does not charge a separate name-enquiry fee on your pricing plan for this lookup.

Removing an account

Removal is a soft delete. The account disappears from your list and can no longer receive a payout, but past payouts keep their own snapshot of where they went — so history never changes retroactively, and you can add the same account again later.

Next: sending a payout.