Resolve a payout recipient

Name enquiry: confirms the legal name behind a payout destination before you initiate
the send. Requires a SECRET API key — publishable keys are rejected, to prevent
account-name harvesting.

SDK: sdk.resolveRecipient({ methodId, accountNumber | phone }). This is the
resolver for anything you got from sdk.getBanks. The SDK's deprecated
resolveBankAccount takes a legacy bank_code and does not understand a methodId —
do not use it here.

Pass the methodId from GET /api/v1/fiat/banks?direction=outbound (in the SDK,
sdk.getBanks({ country, direction: 'outbound' }) — the SDK defaults to inbound),
plus accountNumber for a bank method or phone for mobile money. At least one of
the two is required. The methodId must belong to the same environment as your key: a
live key with a sandbox methodId (or the reverse) returns
supported: false, reason: METHOD_MODE_MISMATCH.

Under the hood the corridor's primary provider is tried first, then its fallback, so a
method listed by both is resolved by whichever answers.

Name enquiry is available for NGN bank accounts only. Every other currency —
including every mobile-money method — returns 200 with supported: false. That is a
normal response, not an error: it is the signal to collect the recipient name manually
and continue with the payout, not to block it. The same applies to any method flagged
manualInput in the /fiat/banks listing. Do not build a flow that requires a
resolved name before allowing a payout, or you will block every non-NGN corridor.

Read the two flags together:
supported: false → this corridor/method cannot be verified, collect the name manually.
supported: true, resolved: false → verification ran and the account was not found;
ask the user to check the number. resolved: true → use accountName.

Sandbox

Live and sandbox are separate methodId spaces — the same bank has a different id
in each, and the sandbox list is much smaller. The mode is taken from the business your
API key belongs to, so a sandbox key must use a methodId fetched with
GET /api/v1/fiat/banks?...&sandbox=true (in the SDK,
getBanks({ ..., sandbox: true }), or construct the client with sandbox: true).
Mixing them returns supported: false, reason: METHOD_MODE_MISMATCH — that error means
the id came from the wrong environment, not that the account is bad.

Name enquiry in sandbox is forwarded to the provider's own sandbox environment; it is
not stubbed and no fixed test account number is published for it. Treat
supported: false or reason: NOT_FOUND as an ordinary sandbox outcome and exercise
your manual-name fallback path, rather than asserting on a resolved name in tests.

Use reason to tell the cases apart:
METHOD_MODE_MISMATCH → the methodId is from the other environment.
null with supported: false → name enquiry is unavailable for this corridor.
NOT_FOUND → the lookup ran and the provider did not recognise the account.

(The 1111111111 / 0000000000 values in the provider's sandbox docs apply to the
funding source on a collection, not to name enquiry, and the gateway injects them
automatically — never send them here.)

Rate limited to 100 requests per minute per business.

application/json

Resolution result. Also returned when the corridor is unsupported or the account was not found — inspect supported and resolved.

Bodyapplication/json

curl --location '/api/v1/fiat/resolve-recipient' \ --header 'X-API-Key: <api-key>' \ --header 'Content-Type: application/json' \ --data '{ "methodId": "string", "accountNumber": "string", "phone": "string" }'

Resolve a payout recipient

Sandbox

Request

Responses

Resolve a payout recipient

Sandbox#

Request

Responses

Sandbox