Global Collections (Pay-in)

A global collection charges a payer through POST /api/global/payments with request_type: payment. First discover the routing for the payer’s country, then create the payment with a deposit network.

Requires KYC Level 4

Collecting across countries requires KYC Level 4. Lower tiers are limited to first-party or Kenya-only collections — see KYC tiers & limits.

Who is the customer?

customer is the owner of the funds being moved — for a collection, the payer. Collections are first-party: the account paying must be in the payer’s own name.

Skip the customer block entirely

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

Create a collection

This example collects over mobile money in Uganda, using the deposit Airtel network from discovery.

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": "payment",
    "transaction_channel": "momo",
    "provider": "yc",
    "amount": 20000,
    "currency": "UGX",
    "country": "UG",
    "reason": "Order payment for INV-2026-001",
    "customer": {
      "first_name": "Jane",
      "last_name": "Mukasa",
      "email": "jane@example.com",
      "phone": "+256769759910",
      "country": "UG"
    },
    "vendor_config": { "vendor_id": 63 },
    "provider_config": {
      "network_id": "04a3083a-567c-4a2b-aa39-fa8f19e64341",
      "network_name": "Airtel Mobile Money",
      "network_code": "AIRTEL_UGANDA",
      "channel_id": "e167def0-c4f0-46e2-aaa9-50046f13b0a7",
      "account_type": "momo"
    },
    "payment_config": {
      "reference": "order_INV-2026-001",
      "account_number": "+256769759910",
      "remark": "order payment",
      "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" => "payment",
        "transaction_channel" => "momo",
        "provider" => "yc",
        "amount" => 20000,
        "currency" => "UGX",
        "country" => "UG",
        "reason" => "Order payment for INV-2026-001",
        "customer" => [
            "first_name" => "Jane",
            "last_name" => "Mukasa",
            "email" => "jane@example.com",
            "phone" => "+256769759910",
            "country" => "UG",
        ],
        "vendor_config" => ["vendor_id" => 63],
        "provider_config" => [
            "network_id" => "04a3083a-567c-4a2b-aa39-fa8f19e64341",
            "network_name" => "Airtel Mobile Money",
            "network_code" => "AIRTEL_UGANDA",
            "channel_id" => "e167def0-c4f0-46e2-aaa9-50046f13b0a7",
            "account_type" => "momo",
        ],
        "payment_config" => [
            "reference" => "order_INV-2026-001",
            "account_number" => "+256769759910",
            "remark" => "order payment",
            "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": "payment",
        "transaction_channel": "momo",
        "provider": "yc",
        "amount": 20000,
        "currency": "UGX",
        "country": "UG",
        "reason": "Order payment for INV-2026-001",
        "customer": {
            "first_name": "Jane",
            "last_name": "Mukasa",
            "email": "jane@example.com",
            "phone": "+256769759910",
            "country": "UG",
        },
        "vendor_config": {"vendor_id": 63},
        "provider_config": {
            "network_id": "04a3083a-567c-4a2b-aa39-fa8f19e64341",
            "network_name": "Airtel Mobile Money",
            "network_code": "AIRTEL_UGANDA",
            "channel_id": "e167def0-c4f0-46e2-aaa9-50046f13b0a7",
            "account_type": "momo",
        },
        "payment_config": {
            "reference": "order_INV-2026-001",
            "account_number": "+256769759910",
            "remark": "order payment",
            "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: "payment",
    transaction_channel: "momo",
    provider: "yc",
    amount: 20000,
    currency: "UGX",
    country: "UG",
    reason: "Order payment for INV-2026-001",
    customer: {
      first_name: "Jane",
      last_name: "Mukasa",
      email: "jane@example.com",
      phone: "+256769759910",
      country: "UG",
    },
    vendor_config: { vendor_id: 63 },
    provider_config: {
      network_id: "04a3083a-567c-4a2b-aa39-fa8f19e64341",
      network_name: "Airtel Mobile Money",
      network_code: "AIRTEL_UGANDA",
      channel_id: "e167def0-c4f0-46e2-aaa9-50046f13b0a7",
      account_type: "momo",
    },
    payment_config: {
      reference: "order_INV-2026-001",
      account_number: "+256769759910",
      remark: "order payment",
      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());

A 200 means the provider accepted the request:

{
  "status_code": "200",
  "merchant_reference": "9FD194041588.iI",
  "transaction_type": "payin",
  "success": true,
  "message": "request sent",
  "checkout_request_id": "a8e1c979-3592-5abd-b1cd-dc1dbd34e708"
}

Keep merchant_reference — it is what you look the payment up by. The final result arrives on your callback URL.

success: false here is not a failure

If the response carries a merchant_reference, the payment has started. success only reports whether it has settled, which it has not yet. A rejection comes back as an HTTP error instead — see Errors.

What each rail needs from the payer

The create call starts the payment; the payer finishes it in a way that depends on the rail you chose.

Mobile money

The payer approves a prompt on their phone. Show them a “check your phone” state and wait for the callback. payment_config.account_number is the phone number, in international format.

Bank

The payer sends a bank deposit. The response carries where to send it:

{
  "status_code": "200",
  "merchant_reference": "9FD194041590.iI",
  "success": true,
  "manual_payment": "Deposit the exact amount using the reference below.",
  "bank_info": {
    "name": "NCBA Bank",
    "account_name": "PayHero Collections",
    "account_number": "1234567890",
    "branch_code": "07",
    "payment_link": ""
  }
}

Show manual_payment and every field of bank_info to the payer. Some providers add their own details in provider_extra — show those too.

Card

The payer enters card details on the provider’s hosted page. A card payment requires payment_config.redirect_url — where the payer is sent back once the page is done — and is refused without one.

curl -X POST "$PH_BASE_URL/api/global/payments" \
  -u "$PH_API_USERNAME:$PH_API_PASSWORD" \
  -H "Content-Type: application/json" \
  -d '{
    "request_type": "payment",
    "transaction_channel": "card",
    "provider": "vabupay",
    "amount": 20000,
    "currency": "UGX",
    "country": "UG",
    "customer": {
      "first_name": "Jane",
      "last_name": "Mukasa",
      "email": "jane@example.com",
      "phone": "+256769759910",
      "country": "UG"
    },
    "vendor_config": { "vendor_id": 63 },
    "provider_config": {
      "network_id": "10001-PD",
      "network_name": "Card Payment",
      "network_code": "CARD-PD",
      "channel_id": "10001-PD",
      "account_type": "card"
    },
    "payment_config": {
      "reference": "order_INV-2026-002",
      "account_number": "+256769759910",
      "callback_url": "https://your-system.com/webhooks/payhero",
      "redirect_url": "https://your-system.com/payments/return?order=INV-2026-002"
    }
  }'

The response carries a checkout_url:

{
  "status_code": "200",
  "merchant_reference": "8ID074925587.iI",
  "success": true,
  "message": "Payment request sent successfully",
  "checkout_url": "https://pay.example.com/checkout/8dac1e03-e461-41c8-9b48-d9ed8235059f"
}

1. Send the payer to checkout_url — a full redirect, or an iframe on your page.
2. The payer completes the card form and returns to your redirect_url.
3. Your return page confirms the outcome from the callback, or with POST /api/global/transaction-status.

Don’t poll while the payer is on the card page

Until the payer finishes, there is no result to find. Start checking when they return to your redirect_url. Put your own order reference in the redirect_url query string so the return page knows which payment it is about.

Embedding in an iframe

Hosted card pages can be framed, but the payer’s bank may show its 3-D Secure step on a page that refuses to be framed. Always give the payer a way to open checkout_url in a new tab.

Amounts

Send the amount in the country’s currency, with at most two decimal places, within the network’s min_amount and max_amount. If you price in another currency, convert and round before sending.

For multi-country payouts, see Global Payouts.