Kenya Collections (V1)

Kenya collections use the V1 endpoint POST /api/v2/payments. You can collect over a wallet (network_code) or a payment channel (channel_id), online (STK push) or offline (Paybill).

Make a collection

cURL

curl -X POST "$PH_BASE_URL/api/v2/payments" \
  -u "$PH_API_USERNAME:$PH_API_PASSWORD" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 10,
    "phone_number": "0712345678",
    "provider": "sasapay",
    "network_code": "63902",
    "account_id": 63,
    "external_reference": "test_ext",
    "callback_url": "https://your-system.com/webhooks/payhero"
  }'

PHP

<?php
$ch = curl_init("$baseUrl/api/v2/payments");
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_USERPWD => "$username:$password",
    CURLOPT_HTTPHEADER => ["Content-Type: application/json"],
    CURLOPT_POSTFIELDS => json_encode([
        "amount" => 10,
        "phone_number" => "0712345678",
        "provider" => "sasapay",
        "network_code" => "63902",
        "account_id" => 63,
        "external_reference" => "test_ext",
        "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/payments",
    auth=(username, password),
    json={
        "amount": 10,
        "phone_number": "0712345678",
        "provider": "sasapay",
        "network_code": "63902",
        "account_id": 63,
        "external_reference": "test_ext",
        "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/payments`, {
  method: "POST",
  headers: {
    Authorization: `Basic ${auth}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    amount: 10,
    phone_number: "0712345678",
    provider: "sasapay",
    network_code: "63902",
    account_id: 63,
    external_reference: "test_ext",
    callback_url: "https://your-system.com/webhooks/payhero",
  }),
});

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

A successful request returns 201 with a CheckoutRequestID:

{
  "success": true,
  "status": "QUEUED",
  "reference": "UFD003217286.iI",
  "CheckoutRequestID": "29119",
  "external_reference": "test_ext"
}

Collection types

Type	Key fields
Wallet-based	provider, network_code
Payment-channel	provider, channel_id
Offline	add is_offline: true (+ merchant_fee)

Offline collections

For an offline collection (is_offline: true), no STK push is sent. The customer completes payment manually via M-Pesa Paybill, using the CheckoutRequestID from the response as the account reference.

1. Make the request with is_offline: true and read the CheckoutRequestID from the response (e.g. 29119).
2. The customer pays on M-Pesa:
   • Paybill number: 756756
   • Account number: 553125#<CheckoutRequestID> — e.g. 553125#29119
3. The final result is delivered to your callback URL.

Note

756756 and the 553125# prefix are the offline Paybill / account template — confirm the exact values for your account on your dashboard.

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