API reference

Payouts API: M-Pesa B2C payouts and reversals

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

Both endpoints move money out of your shortcode. Both endpoints are asynchronous. The HTTP call acknowledges with 202. paylod delivers the final result to your webhook. For both endpoints you must set the application's Initiator Name and Initiator Password.

On a production application you cannot reverse these two operations. Put your own authorisation in front of them. 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…`). paylod normalises it 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	Occasion label. Up to 100 chars.

Example

[!note] No paylod SDK wraps /payout yet. The SDKs cover collect and status only. Call this endpoint with the HTTP client of your language, as below.

const res = await fetch("https://paylod.dev/functions/v1/payout", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.PAYLOD_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    amount: 2500,
    phone: "254712345678",
    commandId: "BusinessPayment",
    remarks: "Payout for July",
  }),
});

const { disbursementId, conversationId } = await res.json();

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

$ch = curl_init('https://paylod.dev/functions/v1/payout');
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('PAYLOD_API_KEY'),
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'amount' => 2500,
        'phone' => '254712345678',
        'commandId' => 'BusinessPayment',
        'remarks' => 'Payout for July',
    ]),
]);

$body = json_decode(curl_exec($ch), true);
curl_close($ch);

$disbursementId = $body['disbursementId'];

import os
import httpx

res = httpx.post(
    "https://paylod.dev/functions/v1/payout",
    headers={"Authorization": f"Bearer {os.environ['PAYLOD_API_KEY']}"},
    json={
        "amount": 2500,
        "phone": "254712345678",
        "commandId": "BusinessPayment",
        "remarks": "Payout for July",
    },
)

body = res.json()
disbursement_id = body["disbursementId"]

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

String payload = """
    { "amount": 2500, "phone": "254712345678",
      "commandId": "BusinessPayment", "remarks": "Payout for July" }
    """;

HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://paylod.dev/functions/v1/payout"))
    .header("Authorization", "Bearer " + System.getenv("PAYLOD_API_KEY"))
    .header("Content-Type", "application/json")
    .POST(HttpRequest.BodyPublishers.ofString(payload))
    .build();

HttpResponse<String> response = HttpClient.newHttpClient()
    .send(request, HttpResponse.BodyHandlers.ofString());

import java.net.URI
import java.net.http.HttpClient
import java.net.http.HttpRequest
import java.net.http.HttpResponse

val payload = """
    { "amount": 2500, "phone": "254712345678",
      "commandId": "BusinessPayment", "remarks": "Payout for July" }
""".trimIndent()

val request = HttpRequest.newBuilder()
    .uri(URI.create("https://paylod.dev/functions/v1/payout"))
    .header("Authorization", "Bearer ${System.getenv("PAYLOD_API_KEY")}")
    .header("Content-Type", "application/json")
    .POST(HttpRequest.BodyPublishers.ofString(payload))
    .build()

val response = HttpClient.newHttpClient()
    .send(request, HttpResponse.BodyHandlers.ofString())

Response · 202 Accepted

{
  "disbursementId": "d3f1a2b3-…",
  "conversationId": "AG_20260707_0000c1d2e3f4",
  "status": "pending"
}

paylod sends the final result to your webhook as an HMAC-signed payout.result event. Correlate that event with disbursementId or conversationId.

POST /reversal

Reverse or refund a completed transaction to the customer.

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	Occasion label. Up to 100 chars.

Example

const res = await fetch("https://paylod.dev/functions/v1/reversal", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.PAYLOD_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    transactionId: "UG1F3A1U7J",
    amount: 2500,
    remarks: "Customer refund",
  }),
});

const { disbursementId, conversationId } = await res.json();

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

$ch = curl_init('https://paylod.dev/functions/v1/reversal');
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('PAYLOD_API_KEY'),
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'transactionId' => 'UG1F3A1U7J',
        'amount' => 2500,
        'remarks' => 'Customer refund',
    ]),
]);

$body = json_decode(curl_exec($ch), true);
curl_close($ch);

$disbursementId = $body['disbursementId'];

import os
import httpx

res = httpx.post(
    "https://paylod.dev/functions/v1/reversal",
    headers={"Authorization": f"Bearer {os.environ['PAYLOD_API_KEY']}"},
    json={
        "transactionId": "UG1F3A1U7J",
        "amount": 2500,
        "remarks": "Customer refund",
    },
)

body = res.json()
disbursement_id = body["disbursementId"]

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

String payload = """
    { "transactionId": "UG1F3A1U7J", "amount": 2500, "remarks": "Customer refund" }
    """;

HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://paylod.dev/functions/v1/reversal"))
    .header("Authorization", "Bearer " + System.getenv("PAYLOD_API_KEY"))
    .header("Content-Type", "application/json")
    .POST(HttpRequest.BodyPublishers.ofString(payload))
    .build();

HttpResponse<String> response = HttpClient.newHttpClient()
    .send(request, HttpResponse.BodyHandlers.ofString());

import java.net.URI
import java.net.http.HttpClient
import java.net.http.HttpRequest
import java.net.http.HttpResponse

val payload = """
    { "transactionId": "UG1F3A1U7J", "amount": 2500, "remarks": "Customer refund" }
""".trimIndent()

val request = HttpRequest.newBuilder()
    .uri(URI.create("https://paylod.dev/functions/v1/reversal"))
    .header("Authorization", "Bearer ${System.getenv("PAYLOD_API_KEY")}")
    .header("Content-Type", "application/json")
    .POST(HttpRequest.BodyPublishers.ofString(payload))
    .build()

val response = HttpClient.newHttpClient()
    .send(request, HttpResponse.BodyHandlers.ofString())

Response · 202 Accepted

{
  "disbursementId": "f7e6d5c4-…",
  "conversationId": "AG_20260707_0000a9b8c7d6",
  "status": "pending"
}

paylod sends the result to your webhook as an HMAC-signed refund.result event.