Testing Payouts

Before You Test

Use sandbox credentials with POST /api/sandbox/b2b/fiat/payout. Use the same request fields as production, with a currency, country, and payout method supported by your sandbox account. Test account numbers do not bypass required fields, amount limits, or account restrictions. No real payout is sent. You can run these simulations without funding a wallet or completing production onboarding.

For inline recipients, include amount, currency, country, destination, payoutMethod, and a new externalReference for your account. Use a supported currency-country combination. Keep account numbers as strings to preserve leading zeroes.

For MoMo, payoutMethod.code is the operator ID. It can be inferred for recognized phone prefixes; if the API returns MOMO_CODE_REQUIRED, supply it explicitly. Use the Mobile Money Operators guide for the selected currency. Bank payouts require payoutMethod.code; obtain the bank code from the Get Banks endpoint.

Successful Mobile Money Payout

Use the payout country's calling code followed by 712345678 for success or 787654321 for failure. Keep the calling code, currency, country, and operator in payoutMethod.code consistent with the payout market you are testing. Test numbers do not enable an unavailable payout route.

In this template, replace <CURRENCY> with the payout currency, <COUNTRY> with its two-letter country code, <CALLING_CODE> with its numeric international calling code, and <OPERATOR_ID> with an operator enabled for that payout. Send payoutMethod.accountNumber as a string of digits without +, spaces, or a local leading zero. Replace the illustrative amount with one within your account's limits, and use a new externalReference. Do not send the placeholders literally.

{
  "amount": 300,
  "currency": "<CURRENCY>",
  "country": "<COUNTRY>",
  "destination": "MoMo",
  "externalReference": "sandbox-momo-success-001",
  "payoutMethod": {
    "accountName": "Test User",
    "accountNumber": "<CALLING_CODE>712345678",
    "code": "<OPERATOR_ID>"
  }
}

Successful Bank Account Payout

Use the following account number with a bank code for your selected country. Replace the illustrative 07 code below with the code returned by Get Banks for the bank you are testing.

{
  "amount": 300,
  "currency": "KES",
  "country": "KE",
  "destination": "Bank Account",
  "externalReference": "sandbox-bank-success-001",
  "payoutMethod": {
    "accountName": "Test User",
    "accountNumber": "1234567890",
    "code": "07"
  }
}

Test Scenarios

Replace <CALLING_CODE> with the payout country's numeric calling code. For a failure test, replace the account number in the matching request and use a new externalReference. An accepted request whose account number does not match a configured success or failure fixture remains pending.

Till and Paybill requests must meet the documented payout requirements. Automatic success/failure test cases are available for bank and MoMo only. An accepted Till or Paybill test request remains pending; the bank test numbers do not apply to those destinations.

Saved Recipients

Use a payout external account belonging to the same sandbox user. When externalAccountId is present, omit currency, country, destination, and payoutMethod; the saved recipient supplies those details. To trigger a fixture outcome, save the corresponding test recipient number in that account.

{
  "amount": 300,
  "externalReference": "sandbox-saved-recipient-001",
  "externalAccountId": "your-sandbox-payout-account-id"
}

Debit Currency and Country

debitCurrency selects the wallet currency used to calculate the sender amount and fees. debitCountry is required whenever debitCurrency is XOF, including when the payout currency is also XOF. It is optional for other debit currencies, including USD, and must be omitted when debitCurrency is absent. Supply the appropriate country when selecting a particular country-scoped wallet.

For example, add "debitCurrency": "XOF" and "debitCountry": "SN" to a supported payout request to calculate the debit in the Senegal XOF wallet. NGN cannot be used as a separate debit currency for a non-NGN payout. A failed currency conversion returns FX_RATE_UNAVAILABLE without creating a payout.

Rejections and Final Status

A successful initiation response means the request was accepted. Confirm chargeStatus through a transaction webhook or the get transaction endpoint; only successful is final success.