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.

Requires KYC Level 4

Collecting across countries (global pay-in) 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 — never you as the platform. For a collection that is the client making the deposit, i.e. the payer being charged. (For a withdrawal it flips — see Global Payouts.)

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 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 },
    "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": "order_INV-2025-001",
      "account_number": "+254712345678",
      "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" => "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],
        "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" => "order_INV-2025-001",
            "account_number" => "+254712345678",
            "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": "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},
        "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": "order_INV-2025-001",
            "account_number": "+254712345678",
            "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: "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 },
    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: "order_INV-2025-001",
      account_number: "+254712345678",
      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 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.

For who can collect where, see KYC tiers & limits. For multi-country pay-outs, see Global Payouts.