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 include KEN (Kenya), RWA (Rwanda), GHA (Ghana), TZA (Tanzania) and ZAF (South Africa).

accountTypeenumRequired
Kind of account being validated.
accountIdentifierstringRequired

The account locator — bank account number, mobile-money MSISDN, IBAN, or wallet identifier depending on accountType.

bankCodestringOptional

Required for bank_account; ignored for mobile_money and institution_wallet.

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).

accountHolderNamestring

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

validationTypeenum

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

expiresAtdatetime

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

failureReasonstring

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