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 recipient’s KYC.

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 +254712345678",
    "source": "api",
    "customer": {
      "first_name": "John",
      "last_name": "Doe",
      "email": "john.doe@example.com",
      "phone": "+254712345678",
      "country": "KE"
    },
    "vendor_config": { "vendor_id": 231, "channel_id": 1501 },
    "payment_config": {
      "account_number": "+254712345678",
      "callback_url": "https://your-system.com/webhooks/payhero"
    }
  }'

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 +254712345678",
        "source" => "api",
        "customer" => [
            "first_name" => "John",
            "last_name" => "Doe",
            "email" => "john.doe@example.com",
            "phone" => "+254712345678",
            "country" => "KE",
        ],
        "vendor_config" => ["vendor_id" => 231, "channel_id" => 1501],
        "payment_config" => [
            "account_number" => "+254712345678",
            "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/global/payments",
    auth=(username, password),
    json={
        "request_type": "withdrawal",
        "transaction_channel": "momo",
        "provider": "sasapay",
        "amount": 10,
        "currency": "KES",
        "country": "KE",
        "reason": "Withdrawal to account +254712345678",
        "source": "api",
        "customer": {
            "first_name": "John",
            "last_name": "Doe",
            "email": "john.doe@example.com",
            "phone": "+254712345678",
            "country": "KE",
        },
        "vendor_config": {"vendor_id": 231, "channel_id": 1501},
        "payment_config": {
            "account_number": "+254712345678",
            "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/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 +254712345678",
    source: "api",
    customer: {
      first_name: "John",
      last_name: "Doe",
      email: "john.doe@example.com",
      phone: "+254712345678",
      country: "KE",
    },
    vendor_config: { vendor_id: 231, channel_id: 1501 },
    payment_config: {
      account_number: "+254712345678",
      callback_url: "https://your-system.com/webhooks/payhero",
    },
  }),
});

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

Multi-country & KYC

For some corridors (TZ, ZM, NG, …) the recipient’s identity fields are required — 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 }

See the API Reference → Create a payment for the full schema and per-country examples.