> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cloudpay.africa/llms.txt
> Use this file to discover all available pages before exploring further.

# Pay out

> Send money to phones, bank accounts, tills and paybills.

`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

```bash theme={null}
curl -X POST https://api.cloudpay.africa/cloudpay/v1/merchants/$MERCHANT_ID/disbursements \
  -H "Authorization: Bearer $CLOUDPAY_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "msisdn": "0712345678",
    "amount": 500000,
    "narrative": "November commission",
    "idempotency_key": "payroll-2026-11-ag-17"
  }'
```

`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:

```json Bank account theme={null}
{ "amount": 2500000, "idempotency_key": "sup-4431",
  "payee": { "type": "bank", "bank_code": "01", "account": "1234567890" } }
```

```json Till (Buy Goods) theme={null}
{ "amount": 120000, "idempotency_key": "rent-nov",
  "payee": { "type": "till", "account": "5123456" } }
```

```json Paybill theme={null}
{ "amount": 350000, "idempotency_key": "kplc-nov",
  "payee": { "type": "paybill", "account": "888880", "account_ref": "54401234567" } }
```

```json Airtel phone theme={null}
{ "amount": 50000, "idempotency_key": "agent-22",
  "payee": { "type": "mobile", "msisdn": "0733123456", "network": "airtel" } }
```

Get `bank_code` from `GET /v1/merchants/{merchantID}/banks`.

What a payout can reach depends on your payout rail:

| Rail | Can pay |
| - | - |
| M-Pesa | M-Pesa phones only |
| SasaPay | Phones on M-Pesa, Airtel and T-Kash; bank accounts; tills; paybills |

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

| Code | Why | Fix |
| - | - | - |
| `403 live_mode_required` | Test key | Use your live key |
| `422 insufficient_funds` | Main balance is below the amount plus the fee | Top up, or move money from a till (`POST …/transfers`) |
| `400 payee_unsupported` | Your rail can't reach this kind of payee | Use a phone, or ask for a SasaPay payout rail |
| `409 bank_payouts_unavailable` | Bank payout without SasaPay | Ask Cloudpay to enable SasaPay payouts |
| `400 invalid_payee` | A payee field is missing for its type | Check the examples above |
| `409 rail_credentials_missing` | Your own provider keys are incomplete | Fix them under **Rails** |

See [Bulk payments](https://docs.cloudpay.africa/guides/bulk.md) to send up to 1,000 at once.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.