POST /v1/merchants/{merchantID}/disbursements needs the disburse scope. Payouts are available with live keys only. A test key gets 403 live_mode_required.
To an M-Pesa phone
202 Accepted means the payout started. 200 with replayed: true means you already sent this key, and you’re getting the original payout back.
To anything else: payee
Use payee instead of msisdn to send to a bank account, a till or a paybill:
bank_code from GET /v1/merchants/{merchantID}/banks.
What a payout can reach depends on your payout rail:
Sending a payee your rail can’t reach returns
400 payee_unsupported.
Where the money comes from
If Cloudpay holds your money (custody: platform), the amount and the fee are held on your main balance when you create the payout. If that balance can’t cover both, the request returns 422 insufficient_funds, and nothing is sent. The hold is kept if the payout completes and released if it fails.
If you use your own provider keys (custody: byok), the provider pays from your own float, and Cloudpay records the payout.
People need their PIN
An API key never needs a PIN. A person signed in to the dashboard, or an app using their session, must send their 4-digitpin with every payout:
- With no PIN, the request returns
403 pin_required. - With a wrong PIN, it returns
401 invalid_pin. - Five wrong PINs lock the account for 30 minutes (
423 pin_locked).
Common errors
See Bulk payments to send up to 1,000 at once.