Testing payouts

In the sandbox, the recipient account number selects the outcome. Bank codes and account names can be any value.

Successful payouts

{
  "payoutMethod": {
    "accountName": "Test User",
    "accountNumber": "1234567890",
    "code": "07"
  }
}

{
  "payoutMethod": {
    "accountName": "Test User",
    "accountNumber": "254712345678"
  }
}

Destination	Account number	Bank code	Account name
Bank Account	`1234567890`	Any code	Any name
MoMo	`254712345678`	—	Any name

Failed payouts

{
  "payoutMethod": {
    "accountName": "Test User",
    "accountNumber": "0987654321",
    "code": "07"
  }
}

{
  "payoutMethod": {
    "accountName": "Test User",
    "accountNumber": "254787654321"
  }
}

Destination	Account number	Bank code
Bank Account	`0987654321`	Any code
MoMo	`254787654321`	—

Scenario reference

Scenario	Destination	Account number	Bank code	Expected result
Successful bank transfer	`Bank Account`	`1234567890`	any	Success
Successful mobile money	`MoMo`	`254712345678`	—	Success
Failed bank account	`Bank Account`	`0987654321`	any	Failed
Failed mobile money	`MoMo`	`254787654321`	—	Failed

A complete sandbox payout

curl --request POST \
  --url https://api.zerocash.tech/api/b2b/fiat/payout \
  --header 'Authorization: Bearer YOUR_SANDBOX_BEARER_TOKEN' \
  --header 'content-type: application/json' \
  --data '{
    "amount": 100,
    "currency": "KES",
    "country": "KE",
    "externalReference": "sandbox-payout-001",
    "destination": "MoMo",
    "payoutMethod": {
      "accountName": "Test User",
      "accountNumber": "254712345678"
    }
  }'

Use a new externalReference for every attempt. Reusing one returns 409 DUPLICATE_EXTERNAL_REFERENCE rather than creating a second payout — correct behaviour, but it will look like a failure if you are not expecting it.

Confirm the outcome

The initiation response is an acknowledgement, not a result. Confirm through a payout_updated webhook or by polling Get Transaction.

Test the failure fixture as deliberately as the success one. Payout failures are where most production incidents start — make sure your reconciliation handles a failed status and its failureReason before you go live.

Get Started

Before You Build

Charges

Payouts

Webhooks

Testing

Errors

Successful payouts

Failed payouts

Scenario reference

A complete sandbox payout

Confirm the outcome

​Successful payouts

​Failed payouts

​Scenario reference

​A complete sandbox payout

​Confirm the outcome

Successful payouts

Failed payouts

Scenario reference

A complete sandbox payout

Confirm the outcome