# Payouts

POST /payout to send money out (B2C) and POST /reversal to refund a completed transaction.

Both endpoints move money **out** of your shortcode. Both are asynchronous: the HTTP call acknowledges with `202`, and the terminal result is delivered to your [webhook](/docs/api/webhooks). Both require the application's **Initiator Name** and **Initiator Password** to be configured.

> [!warn] On a production application these are irreversible. Guard them behind your own authorisation, and never expose them to a client.

## POST /payout

B2C payout — send money from your shortcode to a customer.

```text title="Endpoint"
POST https://paylod.dev/functions/v1/payout
```

### Body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `amount` | integer | Required | Whole KES to send, 1–150000. |
| `phone` | string | Required | Recipient MSISDN (`0712…`, `254712…`, `+254712…`). Normalised for you. |
| `commandId` | string | Optional | `SalaryPayment`, `BusinessPayment`, or `PromotionPayment`. Defaults to `BusinessPayment`. |
| `remarks` | string | Optional | Free-text remarks. Up to 100 chars. |
| `occasion` | string | Optional | Optional occasion label. Up to 100 chars. |

### Example

```bash title="Request"
curl -X POST https://paylod.dev/functions/v1/payout \
  -H "Authorization: Bearer mp_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 2500,
    "phone": "254712345678",
    "commandId": "BusinessPayment",
    "remarks": "Payout for July"
  }'
```

```json title="Response · 202 Accepted"
{
  "disbursementId": "d3f1a2b3-…",
  "conversationId": "AG_20260707_0000c1d2e3f4",
  "status": "pending"
}
```

The terminal result is pushed to your webhook as an HMAC-signed `payout.result` event. Correlate it via `disbursementId` or `conversationId`.

## POST /reversal

Reverse or refund a completed transaction back to the payer.

```text title="Endpoint"
POST https://paylod.dev/functions/v1/reversal
```

### Body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `transactionId` | string | Required | The M-Pesa receipt to reverse. |
| `amount` | integer | Required | Whole KES, 1–150000. Must match the original transaction amount. |
| `remarks` | string | Optional | Free-text remarks. Up to 100 chars. |
| `occasion` | string | Optional | Optional occasion label. Up to 100 chars. |

### Example

```bash title="Request"
curl -X POST https://paylod.dev/functions/v1/reversal \
  -H "Authorization: Bearer mp_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "transactionId": "UG1F3A1U7J",
    "amount": 2500,
    "remarks": "Customer refund"
  }'
```

```json title="Response · 202 Accepted"
{
  "disbursementId": "f7e6d5c4-…",
  "conversationId": "AG_20260707_0000a9b8c7d6",
  "status": "pending"
}
```

The result is pushed to your webhook as an HMAC-signed `refund.result` event.