Skip to main content
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:
Get 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-digit pin 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.