API reference

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. Both require the application's Initiator Name and Initiator Password to be configured.

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.

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

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"
  }'

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.

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

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"
  }'

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.