Make Global Payments
This document contains API documentation for PH global payment
This document provides comprehensive details for integrating with the Pay Hero Global Payments API. The API allows you to initiate various types of payment transactions, including top-ups, payments, withdrawals, utility payments, and bill payments.
Payment Request
POST https://backend.payhero.co.ke/api/global/payments
The API requires authentication via an API key or token, which should be included in the request header:
Headers
Content-Type
application/json
Authorization
Bearer <token>
Body
request_typestring
Required: Specifies the type of transaction. Valid values: topup, payment, withdrawal, utility, bills
provider
string
Required: The payment provider to process the transaction. Valid values: bitlipa, intasend, sasapay, pesapal, m-pesa, bank.
amountnumber
Required: Transaction amount (e.g., 10)
currencystring
Required: Currency code (e.g., KES)
countrystring
Required: Country code (e.g., KE)
referencestring
Required: Unique external reference for the transaction
descriptionstring
Optional: Description or reason for the transaction
customerobject
{
"first_name": "string", // Required: Customer's first name
"last_name": "string", // Required: Customer's last name
"email": "string", // Required: Customer's email address
"phone": "string", // Required: Customer's phone number (e.g., +254758955781)
"id_number": "string", // Optional: Customer's ID number
"recipient_id_type": "string", // Optional: Type of recipient ID (e.g., NATIONAL_ID)
"recipient_id_number": "string", // Optional: Recipient's ID number
"address": { // Optional: Customer's address, required for card payments
"line_1": "string", // Required: Address line 1
"line_2": "string", // Optional: Address line 2
"city": "string", // Required: City
"state": "string", // Required: State or region
"postal_code": "string", // Required: Postal code
"zip_code": "string", // Optional: Zip code (if applicable)
"country": "string" // Required: Country code (e.g., KE)
}
}provider_configobject
{
"merchant_id": "string", // Optional: Merchant ID for your own account
"category": "string", // Optional: Category for M-Pesa (e.g., BusinessBuyGoods)
"recipient_category": "string", // Optional: Recipient category (e.g., consumer)
"recipient_type": "string", // Optional: Recipient type (e.g., msisdn)
"customer_id": "string", // Optional: Customer ID
"provider_id": "string" // Required: Provider ID from the discovery API
}vendor_configobject
{
"vendor_id": number, // Required: Account ID for the transaction
"channel_id": number // Required: Payment channel ID
}callback_urlstring
Optional: URL for callback notifications
ipn_idstring
Optional: Instant Payment Notification ID
Field Descriptions
request_type: Specifies the type of transaction. Valid values: topup, payment, withdrawal, utility, bills.
provider: The payment provider to process the transaction. Valid values: bitlipa, intasend, sasapay, pesapal, m-pesa, bank.
amount: The transaction amount (numeric, e.g., 10).
currency: The currency of the transaction (e.g., KES for Kenyan Shilling).
country: The country code for the transaction (e.g., KE for Kenya).
reference: A unique identifier for the transaction provided by the client.
description: A brief description of the transaction purpose (e.g., "Payment for invoice #20250917-001").
customer: Contains customer details.
first_name: Customer's first name.
last_name: Customer's last name.
email: Customer's email address.
phone: Customer's phone number in international format (e.g., +254758955781).
id_number: Customer's identification number (optional).
recipient_id_type: Type of recipient ID (e.g., NATIONAL_ID, optional).
recipient_id_number: Recipient's ID number (optional).
address: Customer's address details, required for card payments.
line_1: Primary address line.
line_2: Secondary address line (optional).
city: City of residence.
state: State or region.
postal_code: Postal code.
zip_code: Zip code (optional, often same as postal_code).
country: Country code (e.g., KE).
provider_config: Configuration specific to the payment provider.
merchant_id: Merchant ID for the provider (optional, used if processing through your own account).
category: Category for M-Pesa transactions (e.g., BusinessBuyGoods, optional).
recipient_category: Category of the recipient (e.g., consumer, optional).
recipient_type: Type of recipient (e.g., msisdn, optional).
customer_id: Customer ID for the provider (optional).
provider_id: Unique provider ID obtained from the discovery API (required).
vendor_config: Vendor-specific configuration.
vendor_id: The account ID associated with the transaction (required).
channel_id: The payment channel ID (required).
callback_url: URL to receive callback notifications (optional, e.g., https://payhero.free.beeceptor.com).
ipn_id: Instant Payment Notification ID for tracking (optional, e.g., IPN-123456).
Response
{
"status_code": "200",
"merchant_reference": "W10_ec27-4f11-a4dc-e94a2213c52e1073572",
"transaction_type": "payin",
"success": true,
"message": "OK",
"checkout_request_id": "W10_ec27-4f11-a4dc-e94a2213c52e1073572",
"gateway": "bitlipa",
"conversation_id": "KIC025140625.iI",
"provider_response": {
"confirm_type": 0,
"order_id": "KIC025140625.iI",
"provider_result": {
"code": 0,
"message": "OK"
},
"result": {
"code": 0,
"message": "OK"
},
"service_date_time": "2025-09-20 02:51:42.796328",
"service_id": 1,
"service_version": "1.03/1.14|1.0/2.0|1.0/1.0|1.01/1.0|1.01/1.0||1.02/1.27",
"status": 1,
"transaction_id": "W10_ec27-4f11-a4dc-e94a2213c52e1073572",
"transaction_ref": ""
}
}{
"error_code": "UNSUPPORTED_MEDIA_TYPE",
"error_message": "COUNTRY IS NOT ALLOWED",
"status_code": 415
}Sample Code
<?php
$curl = curl_init();
curl_setopt_array($curl, array(
CURLOPT_URL => 'https://backend.payhero.co.ke/api/global/payments',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => '',
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 0,
CURLOPT_FOLLOWLOCATION => true,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_POSTFIELDS =>'{
"request_type": "payment",
"provider": "bitlipa",
"amount": 10,
"currency": "KES",
"country": "KE",
"reference": "BeINRafdSre2",
"description": "Payment for invoice #20250917-001",
"customer": {
"first_name": "Vincent",
"last_name": "Omondi",
"email": "[email protected]",
"phone": "+254758955781",
"id_number": "11001111",
"recipient_id_type": "NATIONAL_ID",
"recipient_id_number": "11001111",
"address": {
"line_1": "123 Westlands Avenue",
"line_2": "Apt 12B",
"city": "Nairobi",
"state": "Nairobi",
"postal_code": "00100",
"zip_code": "00100",
"country": "KE"
}
},
"provider_config": {
"merchant_id": "",
"category": "BusinessBuyGoods",
"recipient_category": "consumer",
"recipient_type": "msisdn",
"customer_id": "",
"provider_id": "2031"
},
"vendor_config": {
"vendor_id": 63,
"channel_id": 1501
},
"callback_url": "https://payhero.free.beeceptor.com",
"ipn_id": "IPN-123456"
}',
CURLOPT_HTTPHEADER => array(
'Content-Type: application/json',
'Authorization: Basic amJXVU11TzB0ZqYU00TFU4TGJ2WA=='
),
));
$response = curl_exec($curl);
curl_close($curl);
echo $response;
Last updated
Was this helpful?