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

Name	Value
Content-Type	application/json
Authorization	Bearer <token>

Body

Name	Type	Description
request_type	string	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.
amount	number	Required: Transaction amount (e.g., 10)
currency	string	Required: Currency code (e.g., KES)
country	string	Required: Country code (e.g., KE)
reference	string	Required: Unique external reference for the transaction
description	string	Optional: Description or reason for the transaction
customer	object	{ "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., [phone]) "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_config	object	{ "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_config	object	{ "vendor_id": number, // Required: Account ID for the transaction "channel_id": number // Required: Payment channel ID }
callback_url	string	Optional: URL for callback notifications
ipn_id	string	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., [phone]).

  • 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

200

{
    "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": ""
    }
}

415

{
    "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": "[phone]",
    "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;