Global Payouts (Pay-out)

A global payout sends money using the same POST /api/global/payments endpoint with request_type: withdrawal. The request shape is identical across countries — change currency, country, provider and the routing details.

Who is the customer?

customer is the owner of the funds being moved, not the person receiving them. On a withdrawal that is the owner of the wallet being debited — normally you, the initiating merchant. The destination is set in payment_config.account_number.

(On a collection it flips: the customer is the client making the deposit.)

For global payments, provider_config and payment_config are required in full. vendor_config.channel_id is not required — it only applies to Kenya-based collections that settle to an external channel (bank, paybill or till).

Create a payout

cURL

curl -X POST "$PH_BASE_URL/api/global/payments" \
  -u "$PH_API_USERNAME:$PH_API_PASSWORD" \
  -H "Content-Type: application/json" \
  -d '{
    "request_type": "withdrawal",
    "transaction_channel": "momo",
    "provider": "sasapay",
    "amount": 10,
    "currency": "KES",
    "country": "KE",
    "reason": "Withdrawal to account +254758955781",
    "source": "api",
    "customer": {
      "first_name": "Mary",
      "last_name": "Wanjiku",
      "email": "mary@acme.co.ke",
      "phone": "+254700111222",
      "country": "KE"
    },
    "vendor_config": { "vendor_id": 231 },
    "provider_config": {
      "network_id": "7ea6df5c-6bba-46b2-a7e6-f511959e7edb",
      "provider_id": "c2b2eeda-d4ca-49fd-ba21-0781ffa7714b",
      "network_name": "M PESA",
      "network_code": "7ea6df5c-6bba-46b2-a7e6-f511959e7edb",
      "account_type": "momo"
    },
    "payment_config": {
      "reference": "test_withdrawal",
      "account_number": "+254758955781",
      "remark": "bill payments",
      "payment_category": "bill payment",
      "callback_url": "https://your-system.com/webhooks/payhero",
      "redirect_url": "https://your-system.com/payments/return"
    }
  }'

PHP

<?php
$ch = curl_init("$baseUrl/api/global/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([
        "request_type" => "withdrawal",
        "transaction_channel" => "momo",
        "provider" => "sasapay",
        "amount" => 10,
        "currency" => "KES",
        "country" => "KE",
        "reason" => "Withdrawal to account +254758955781",
        "source" => "api",
        "customer" => [
            "first_name" => "Mary",
            "last_name" => "Wanjiku",
            "email" => "mary@acme.co.ke",
            "phone" => "+254700111222",
            "country" => "KE",
        ],
        "vendor_config" => ["vendor_id" => 231],
        "provider_config" => [
            "network_id" => "7ea6df5c-6bba-46b2-a7e6-f511959e7edb",
            "provider_id" => "c2b2eeda-d4ca-49fd-ba21-0781ffa7714b",
            "network_name" => "M PESA",
            "network_code" => "7ea6df5c-6bba-46b2-a7e6-f511959e7edb",
            "account_type" => "momo",
        ],
        "payment_config" => [
            "reference" => "test_withdrawal",
            "account_number" => "+254758955781",
            "remark" => "bill payments",
            "payment_category" => "bill payment",
            "callback_url" => "https://your-system.com/webhooks/payhero",
            "redirect_url" => "https://your-system.com/payments/return",
        ],
    ]),
]);
$response = curl_exec($ch);
curl_close($ch);
echo $response;

Python

import requests

response = requests.post(
    f"{base_url}/api/global/payments",
    auth=(username, password),
    json={
        "request_type": "withdrawal",
        "transaction_channel": "momo",
        "provider": "sasapay",
        "amount": 10,
        "currency": "KES",
        "country": "KE",
        "reason": "Withdrawal to account +254758955781",
        "source": "api",
        "customer": {
            "first_name": "Mary",
            "last_name": "Wanjiku",
            "email": "mary@acme.co.ke",
            "phone": "+254700111222",
            "country": "KE",
        },
        "vendor_config": {"vendor_id": 231},
        "provider_config": {
            "network_id": "7ea6df5c-6bba-46b2-a7e6-f511959e7edb",
            "provider_id": "c2b2eeda-d4ca-49fd-ba21-0781ffa7714b",
            "network_name": "M PESA",
            "network_code": "7ea6df5c-6bba-46b2-a7e6-f511959e7edb",
            "account_type": "momo",
        },
        "payment_config": {
            "reference": "test_withdrawal",
            "account_number": "+254758955781",
            "remark": "bill payments",
            "payment_category": "bill payment",
            "callback_url": "https://your-system.com/webhooks/payhero",
            "redirect_url": "https://your-system.com/payments/return",
        },
    },
)
print(response.json())

TypeScript

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

const response = await fetch(`${baseUrl}/api/global/payments`, {
  method: "POST",
  headers: {
    Authorization: `Basic ${auth}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    request_type: "withdrawal",
    transaction_channel: "momo",
    provider: "sasapay",
    amount: 10,
    currency: "KES",
    country: "KE",
    reason: "Withdrawal to account +254758955781",
    source: "api",
    customer: {
      first_name: "Mary",
      last_name: "Wanjiku",
      email: "mary@acme.co.ke",
      phone: "+254700111222",
      country: "KE",
    },
    vendor_config: { vendor_id: 231 },
    provider_config: {
      network_id: "7ea6df5c-6bba-46b2-a7e6-f511959e7edb",
      provider_id: "c2b2eeda-d4ca-49fd-ba21-0781ffa7714b",
      network_name: "M PESA",
      network_code: "7ea6df5c-6bba-46b2-a7e6-f511959e7edb",
      account_type: "momo",
    },
    payment_config: {
      reference: "test_withdrawal",
      account_number: "+254758955781",
      remark: "bill payments",
      payment_category: "bill payment",
      callback_url: "https://your-system.com/webhooks/payhero",
      redirect_url: "https://your-system.com/payments/return",
    },
  }),
});

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

Multi-country & KYC

For some corridors (TZ, ZM, NG, …) identity fields are required for the funds owner — add them to customer:

"customer": {
  "first_name": "John",
  "last_name": "Doe",
  "phone": "+255712345678",
  "country": "TZ",
  "id_type": "national_id",
  "id_number": "12345678"
}

The API Reference includes ready-made examples for Kenya (KES), Tanzania (TZS), and Zambia (ZMW).

Payment split

Route part of a payout to savings with payment_split.amount_to_save:

"payment_split": { "amount_to_save": 100 }

To discover the right provider and routing details per country, see How routing works.