PayoutsVerification

Validate an account

Validates a recipient account — a bank account or a mobile-money number — against the appropriate upstream provider for the requested `country` and `accountType`, before initiating a payout. This is the unified replacement for the deprecated `/verification/mobile` and `/verification/bank-account` endpoints. The call resolves **synchronously** for cache hits and short-lived upstream lookups (≤2s). Longer-running validations return status `pending` together with an `id`; poll `GET /accounts/validate/{id}` until the status is terminal. When `accountHolderName` is supplied, the response reports `name_mismatch` if the provider returns a different name.

Authentication

AuthorizationBearer
OAuth 2.0 access token

Request

This endpoint expects an object.
merchantIdstringRequiredformat: "uuid"
Merchant ID issuing the validation request
countrystringRequired

3-letter ISO country code identifying the market the account belongs to. Supported markets depend on accountType:

  • bank_account — ZAF (South Africa), NGA (Nigeria), EGY (Egypt), GHA (Ghana) and KEN (Kenya).
  • mobile_money — KEN (Kenya) and GHA (Ghana).
  • institution_wallet — ZWE (Zimbabwe).
accountTypeenumRequired
Kind of account being validated.
accountIdentifierstringRequired

The account locator, interpreted according to accountType:

  • bank_account — the bank account number. For Egypt (EGY) supply the full IBAN instead (it encodes the bank, so bankCode is not needed).
  • mobile_money — the MSISDN (phone number, including country-code prefix).
  • institution_wallet — the wallet identifier.
bankCodestringOptional

Identifies the destination bank. Required for bank_account in every market except Egypt (EGY), where the IBAN in accountIdentifier carries the bank; ignored for mobile_money and institution_wallet. The format is market-specific:

  • ZAF — 6-digit universal (any-branch) bank code, e.g. 632005 (Absa), 051001 (Standard Bank), 250655 (FNB), 470010 (Capitec). See the South Africa payout guide.
  • NGA — 3-digit (commercial bank) or 6-digit (OFI) CBN bank code.
  • GHA — 3-digit Bank of Ghana institution code.
  • KEN — the destination bank’s code on the domestic rails.
accountHolderNamestringOptional

When supplied, the response status will be name_mismatch if the provider returns a different name.

Response

Validation result (resolved or pending)

idstringformat: "uuid"

Validation ID — use with GET /accounts/validate/{id} to poll a pending validation.

statusenum

Validation outcome. pending means the upstream provider is still resolving; poll GET /accounts/validate/{id} until terminal.

providerstring

Which connector produced the result (e.g. flutterwave, sandbox).

accountHolderNamestringOptional

Name returned by the provider, populated for verified / name_mismatch.

validationTypeenumOptional

Where the result came from — internal_rules = format check (e.g. NUBAN check digit), external = upstream provider lookup.

expiresAtdatetimeOptional

ISO-8601 timestamp at which the cached result becomes stale.

failureReasonstringOptional

Free-form provider reason; populated for not_found / name_mismatch / error.

Errors

400
Bad Request Error
401
Unauthorized Error
422
Unprocessable Entity Error
500
Internal Server Error