Kenya Payouts (V1)

Kenya payouts use the V1 endpoint POST /api/v2/withdraw. You can disburse to a phone number, a Paybill, or a Till, controlled by recipient_type and short_code.

Make a payout

cURL

curl -X POST "$PH_BASE_URL/api/v2/withdraw" \
  -u "$PH_API_USERNAME:$PH_API_PASSWORD" \
  -H "Content-Type: application/json" \
  -d '{
    "external_reference": "TX1234ABCre55AH",
    "account_id": 63,
    "amount": 10,
    "phone_number": "0712345678",
    "account_number": "0712345678",
    "network_code": "63902",
    "channel": "phone",
    "recipient_type": "MSISDN",
    "callback_url": "https://your-system.com/webhooks/payhero"
  }'

PHP

<?php
$ch = curl_init("$baseUrl/api/v2/withdraw");
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_USERPWD => "$username:$password",
    CURLOPT_HTTPHEADER => ["Content-Type: application/json"],
    CURLOPT_POSTFIELDS => json_encode([
        "external_reference" => "TX1234ABCre55AH",
        "account_id" => 63,
        "amount" => 10,
        "phone_number" => "0712345678",
        "account_number" => "0712345678",
        "network_code" => "63902",
        "channel" => "phone",
        "recipient_type" => "MSISDN",
        "callback_url" => "https://your-system.com/webhooks/payhero",
    ]),
]);
$response = curl_exec($ch);
curl_close($ch);
echo $response;

Python

import requests

response = requests.post(
    f"{base_url}/api/v2/withdraw",
    auth=(username, password),
    json={
        "external_reference": "TX1234ABCre55AH",
        "account_id": 63,
        "amount": 10,
        "phone_number": "0712345678",
        "account_number": "0712345678",
        "network_code": "63902",
        "channel": "phone",
        "recipient_type": "MSISDN",
        "callback_url": "https://your-system.com/webhooks/payhero",
    },
)
print(response.json())

TypeScript

const auth = Buffer.from(`${username}:${password}`).toString("base64");

const response = await fetch(`${baseUrl}/api/v2/withdraw`, {
  method: "POST",
  headers: {
    Authorization: `Basic ${auth}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    external_reference: "TX1234ABCre55AH",
    account_id: 63,
    amount: 10,
    phone_number: "0712345678",
    account_number: "0712345678",
    network_code: "63902",
    channel: "phone",
    recipient_type: "MSISDN",
    callback_url: "https://your-system.com/webhooks/payhero",
  }),
});

console.log(await response.json());

A successful request returns 200 with a merchant_reference:

{
  "status": "QUEUED",
  "merchant_reference": "UFD003742176.eO",
  "checkout_request_id": "0aaef9ef-15a6-4ff6-ba9e-35c9d33eb560",
  "response_code": "200",
  "conversation_id": "UFD003742176.eO",
  "external_reference": "TX1234ABCre55AH"
}

Destinations

Destination	recipient_type	Extra fields
Phone	MSISDN	account_number = phone number
Paybill	PAYBILL	short_code = paybill, account_number = account
Till	PAYBILL	short_code = till number

See the API Reference → Wallet-based withdrawal (V1) for the full schema, all destination examples, and language snippets.