Global Collections (Pay-in)

A global collection charges a customer using POST /api/global/payments with request_type: payment. First discover the routing details for the customer’s country, then create the payment.

Create a collection

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": "yellowcard",
    "amount": 5500,
    "currency": "KES",
    "country": "KE",
    "reason": "Order payment for invoice INV-2025-001",
    "source": "api",
    "customer": {
      "first_name": "John",
      "last_name": "Doe",
      "email": "john.doe@example.com",
      "phone": "+254712345678",
      "country": "KE"
    },
    "vendor_config": { "vendor_id": 63 },
    "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" => "payment",
        "transaction_channel" => "momo",
        "provider" => "yellowcard",
        "amount" => 5500,
        "currency" => "KES",
        "country" => "KE",
        "reason" => "Order payment for invoice INV-2025-001",
        "source" => "api",
        "customer" => [
            "first_name" => "John",
            "last_name" => "Doe",
            "email" => "john.doe@example.com",
            "phone" => "+254712345678",
            "country" => "KE",
        ],
        "vendor_config" => ["vendor_id" => 63],
        "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": "payment",
        "transaction_channel": "momo",
        "provider": "yellowcard",
        "amount": 5500,
        "currency": "KES",
        "country": "KE",
        "reason": "Order payment for invoice INV-2025-001",
        "source": "api",
        "customer": {
            "first_name": "John",
            "last_name": "Doe",
            "email": "john.doe@example.com",
            "phone": "+254712345678",
            "country": "KE",
        },
        "vendor_config": {"vendor_id": 63},
        "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: "payment",
    transaction_channel: "momo",
    provider: "yellowcard",
    amount: 5500,
    currency: "KES",
    country: "KE",
    reason: "Order payment for invoice INV-2025-001",
    source: "api",
    customer: {
      first_name: "John",
      last_name: "Doe",
      email: "john.doe@example.com",
      phone: "+254712345678",
      country: "KE",
    },
    vendor_config: { vendor_id: 63 },
    payment_config: {
      account_number: "+254712345678",
      callback_url: "https://your-system.com/webhooks/payhero",
    },
  }),
});

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

A 200 means the request was accepted and queued:

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

Tip

Use the Discovery API to fill provider and provider_config correctly for each country. The final result arrives on your callback URL.

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