Global Payouts (Pay-out)

A global payout sends money through the same POST /api/global/payments endpoint with request_type: withdrawal. Discover the routing for the destination country first, then pay out through a withdraw network.

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 payment_config.account_number.

Skip the customer block entirely

Save the counterparty once as a beneficiary and send "customer": { "customer_uuid": "…" } instead of repeating their details.

Create a payout

This example pays out to a bank account in Kenya.

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": "bank",
    "provider": "yc",
    "amount": 500,
    "currency": "KES",
    "country": "KE",
    "reason": "Supplier payment",
    "customer": {
      "customer_uuid": "a2e0434e-17ae-41b1-a1cf-1694ad63ee99"
    },
    "vendor_config": { "vendor_id": 63 },
    "provider_config": {
      "network_id": "c215e56e-fd08-4d25-a87f-41714ab854e6",
      "network_name": "NCBA Bank",
      "network_code": "41125",
      "account_type": "bank"
    },
    "payment_config": {
      "reference": "supplier_payout_001",
      "account_number": "440200014001",
      "account_holder_name": "Vincent Omondi Ogunde",
      "remark": "bill payments",
      "payment_category": "bill payment",
      "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" => "bank",
        "provider" => "yc",
        "amount" => 500,
        "currency" => "KES",
        "country" => "KE",
        "reason" => "Supplier payment",
        "customer" => ["customer_uuid" => "a2e0434e-17ae-41b1-a1cf-1694ad63ee99"],
        "vendor_config" => ["vendor_id" => 63],
        "provider_config" => [
            "network_id" => "c215e56e-fd08-4d25-a87f-41714ab854e6",
            "network_name" => "NCBA Bank",
            "network_code" => "41125",
            "account_type" => "bank",
        ],
        "payment_config" => [
            "reference" => "supplier_payout_001",
            "account_number" => "440200014001",
            "account_holder_name" => "Vincent Omondi Ogunde",
            "remark" => "bill payments",
            "payment_category" => "bill payment",
            "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": "bank",
        "provider": "yc",
        "amount": 500,
        "currency": "KES",
        "country": "KE",
        "reason": "Supplier payment",
        "customer": {"customer_uuid": "a2e0434e-17ae-41b1-a1cf-1694ad63ee99"},
        "vendor_config": {"vendor_id": 63},
        "provider_config": {
            "network_id": "c215e56e-fd08-4d25-a87f-41714ab854e6",
            "network_name": "NCBA Bank",
            "network_code": "41125",
            "account_type": "bank",
        },
        "payment_config": {
            "reference": "supplier_payout_001",
            "account_number": "440200014001",
            "account_holder_name": "Vincent Omondi Ogunde",
            "remark": "bill payments",
            "payment_category": "bill payment",
            "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: "bank",
    provider: "yc",
    amount: 500,
    currency: "KES",
    country: "KE",
    reason: "Supplier payment",
    customer: { customer_uuid: "a2e0434e-17ae-41b1-a1cf-1694ad63ee99" },
    vendor_config: { vendor_id: 63 },
    provider_config: {
      network_id: "c215e56e-fd08-4d25-a87f-41714ab854e6",
      network_name: "NCBA Bank",
      network_code: "41125",
      account_type: "bank",
    },
    payment_config: {
      reference: "supplier_payout_001",
      account_number: "440200014001",
      account_holder_name: "Vincent Omondi Ogunde",
      remark: "bill payments",
      payment_category: "bill payment",
      callback_url: "https://your-system.com/webhooks/payhero",
    },
  }),
});

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

Add every field that discovery’s required_fields[provider] lists — for example, if it lists channel_id, copy the channel_id of the withdraw network.

The account holder name

payment_config.account_holder_name is the name on the destination bank account. Send it for bank payouts. If you leave it out, the customer’s first and last name are used instead.

Paying out to mobile money

Pick a momo network with ramp_type: withdraw, set transaction_channel and provider_config.account_type to momo, and put the recipient’s phone number, in international format, in payment_config.account_number:

"transaction_channel": "momo",
"provider_config": {
  "network_id": "04a3083a-567c-4a2b-aa39-fa8f19e64341",
  "network_name": "Airtel Mobile Money",
  "network_code": "AIRTEL_UGANDA",
  "channel_id": "e573694c-d9d2-4511-8dec-aa633baf19f3",
  "account_type": "momo"
},
"payment_config": {
  "reference": "payout_002",
  "account_number": "+256769759910",
  "callback_url": "https://your-system.com/webhooks/payhero"
}

Multi-country & KYC

Some corridors require identity fields for the owner of the funds. Add them to customer, or reference a beneficiary that already holds them:

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

Payment split

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

"payment_split": { "amount_to_save": 100 }

To find the right provider and network for each country, see How routing works.