Skip to content

How Global routing works

Global Payments cover the rest of the world (outside the Kenya V1 flow) through a single unified endpoint: POST /api/global/payments. The same request shape handles both collections (request_type: payment) and payouts (request_type: withdrawal) across countries — KE, TZ, ZM, BW, NG, and more.

The routing flow

Global payments are discovery-driven. Before creating a payment, you call the Discovery API to learn how to route it for the customer’s country. The discovery response tells you which provider, network, and channel to use, and you copy those values into your payment request.

Discover available rails, providers, and networks for the country.
Pick a provider and the matching network/channel details.
Create the payment, passing those details in provider, provider_config, and vendor_config.
Receive the final result on your callback URL.

1. Discover routing details

curl "$PH_BASE_URL/api/global/discovery/payment-world/country?country=KE" \
  -u "$PH_API_USERNAME:$PH_API_PASSWORD"

<?php
$ch = curl_init("$baseUrl/api/global/discovery/payment-world/country?country=KE");
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_USERPWD => "$username:$password",
]);
$response = curl_exec($ch);
curl_close($ch);
echo $response;

import requests

response = requests.get(
    f"{base_url}/api/global/discovery/payment-world/country",
    auth=(username, password),
    params={"country": "KE"},
)
print(response.json())

const auth = Buffer.from(`${username}:${password}`).toString("base64");

const response = await fetch(
  `${baseUrl}/api/global/discovery/payment-world/country?country=KE`,
  { headers: { Authorization: `Basic ${auth}` } },
);

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

The response describes the routing options:

{
  "rails": { "bank": true, "card": false, "momo": true },
  "country": "KE",
  "currency": "KES",
  "available_providers": {
    "bank": ["i&m", "absa", "equity", "dtb", "standard_chartered", "stanbic", "kcb"],
    "momo": ["bitlipa", "yellowcard", "m-pesa", "mpesa_dc", "sasapay"]
  },
  "provider_networks": {
    "m-pesa": [
      {
        "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",
        "min_amount": 1,
        "max_amount": 150000
      }
    ]
  }
}

2. Map the response to your request

Discovery field	Payment request field
`available_providers.*`	`provider`
`rails` key (`momo`/`bank`/`card`)	`transaction_channel`
`provider_networks[provider].network_id`	`provider_config.network_id`
`provider_networks[provider].provider_id`	`provider_config.provider_id`
`provider_networks[provider].network_name`	`provider_config.network_name`
`provider_networks[provider].network_code`	`provider_config.network_code`
account type of the network (`momo`/`bank`)	`provider_config.account_type`

All five provider_config fields above are required for global payments. provider_config.channel_id is optional and can be ignored, and vendor_config.channel_id is only used for Kenya-based collections that settle to an external channel (bank, paybill or till).

Next