Discover Global Payments
This document provides comprehensive details for integrating with the PayHero Discovery API.
The API allows you to retrieve information about available payment providers, supported payment methods, and configuration details for initiating transactions in a specific country.
Get Payment Providers
GET
https://backend.payhero.co.ke/api/global/discovery/payment-world/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>
Query Params
country
string
Required. The country code (e.g., KE for Kenya) to filter available payment providers and configurations.
Response
{
"rails": {
"bank": false,
"card": true,
"momo": true
},
"merchant_id": "",
"has_networks": true,
"country": "KE",
"currency": "KES",
"available_providers": {
"card": [
"instasend",
"pesapal"
],
"momo": [
"bitlipa"
]
},
"provider_networks": {
"bitlipa": {
"m-pesa": {
"channels": [
"c2b",
"b2c"
],
"code": "2031",
"description": "M-PESA mobile money service via Bitlipa",
"max_amount": 150000,
"min_amount": 1,
"name": "M-PESA",
"provider": "bitlipa"
}
},
"instasend": {
"card": {
"channels": [
"card"
],
"code": "CARD-INSTASEND",
"countries": [
"ALL"
],
"currencies": [
"USD",
"KES"
],
"description": "Global card payment processing via Instasend (USD & KES)",
"global": true,
"max_amount": 1000000,
"min_amount": 1,
"name": "Instasend Card Payment",
"provider": "instasend"
},
"cashapp": {
"channels": [
"cashapp"
],
"code": "CASHAPP-INSTASEND",
"countries": [
"ALL"
],
"currencies": [
"USD",
"KES"
],
"description": "CashApp payment processing via Instasend",
"global": true,
"max_amount": 1000000,
"min_amount": 1,
"name": "CashApp via Instasend",
"provider": "instasend"
},
"m-pesa": {
"channels": [
"momo"
],
"code": "MPESA-INSTASEND",
"country": "KE",
"description": "M-PESA mobile money service via Instasend (Kenya only)",
"max_amount": 150000,
"min_amount": 1,
"name": "M-PESA via Instasend",
"provider": "instasend"
}
},
"pesapal": {
"airtel-money": {
"channels": [
"momo"
],
"code": "AIRTEL-PESAPAL",
"country": "KE",
"description": "Airtel Money mobile money service via Pesapal (Kenya only)",
"max_amount": 150000,
"min_amount": 1,
"name": "Airtel Money via Pesapal",
"provider": "pesapal"
},
"card": {
"channels": [
"card"
],
"code": "CARD-PESAPAL",
"countries": [
"ALL"
],
"currencies": [
"KES"
],
"description": "Global card payment processing via Pesapal (KES only)",
"global": true,
"max_amount": 1000000,
"min_amount": 10,
"name": "Pesapal Card Payment",
"provider": "pesapal"
},
"m-pesa": {
"channels": [
"momo"
],
"code": "MPESA-PESAPAL",
"country": "KE",
"description": "M-PESA mobile money service via Pesapal (Kenya only)",
"max_amount": 150000,
"min_amount": 1,
"name": "M-PESA via Pesapal",
"provider": "pesapal"
}
}
},
"required_fields": {
"amount": true,
"bitlipa": {
"customer": {
"phone": true
},
"provider_config": {
"merchant_id": true,
"provider_id": true
}
},
"callback_url": false,
"country": true,
"currency": true,
"customer": {
"address": {
"city": true,
"country": true,
"line_1": true,
"line_2": false,
"postal_code": false,
"state": true,
"zip_code": false
},
"email": true,
"extra_id_number": false,
"first_name": true,
"id_number": false,
"last_name": true,
"phone": true,
"recipient_id_number": false,
"recipient_id_type": false
},
"description": false,
"instasend": {
"provider_config": {
"public_key": true
},
"redirect_url": true
},
"ipn_id": false,
"operation_type": true,
"pesapal": {
"customer": {
"address": {
"city": true,
"country": true,
"line_1": true,
"state": true
}
},
"redirect_url": true
},
"provider": true,
"provider_config": {
"category": false,
"customer_id": false,
"merchant_id": false,
"provider_id": false,
"public_key": false,
"recipient_category": false,
"recipient_type": false
},
"redirect_url": false,
"reference": true
},
"provider_operations": {
"bitlipa": {
"b2c": true,
"c2b": true
},
"instasend": {
"b2c": false,
"c2b": true
},
"pesapal": {
"b2c": false,
"c2b": true
}
},
"payment_limits": {
"global": {
"min_amount": 1,
"max_amount": 1500000,
"currency": "KES"
},
"per_rail": {
"card": {
"min_amount": 10,
"max_amount": 1000000,
"currency": "KES"
},
"momo": {
"min_amount": 1,
"max_amount": 1500000,
"currency": "KES"
}
},
"per_provider": {
"bitlipa": {
"min_amount": 1,
"max_amount": 150000,
"currency": "KES"
},
"instasend": {
"min_amount": 1,
"max_amount": 1000000,
"currency": "KES"
},
"pesapal": {
"min_amount": 10,
"max_amount": 1000000,
"currency": "KES"
}
}
},
"processing_times": {
"instant": [
"quikk",
"bitlipa"
],
"same_day": [
"pesapal",
"instasend"
]
},
"fees": {
"structure": "percentage_plus_fixed",
"percentage": 1.5,
"fixed_amount": 0,
"currency": "KES",
"provider_specific": {
"bitlipa": {
"percentage": 1.5,
"fixed_amount": 0
},
"instasend": {
"percentage": 3.6,
"fixed_amount": 0
},
"pesapal": {
"percentage": 3.6,
"fixed_amount": 0
},
"quikk": {
"percentage": 1,
"fixed_amount": 0
}
}
},
"supported_currencies": [
"KES",
"USD",
"EUR"
],
"webhook_support": true,
"refund_policy": {
"supported": true,
"time_limit_hours": 24,
"partial_refunds": true
},
"compliance": {
"kyc_required": true,
"aml_compliant": true,
"pci_compliant": false
},
"user_experience": {
"supports_guest_checkout": true,
"requires_account": false,
"supports_saved_payment_methods": false
},
"api_endpoints": {
"create_payment": "/api/v1/payments",
"check_status": "/api/v1/payments/{id}/status",
"webhook_url": "/api/v1/webhooks"
},
"metadata": {
"version": "1.0.0",
"last_updated": "2025-09-20T10:22:59.753476+03:00",
"cache_ttl_seconds": 300
}
}Response Field Descriptions
rails: Indicates supported payment methods.
bank: Whether bank payments are supported (true/false).
card: Whether card payments are supported (true/false).
momo: Whether mobile money payments are supported (true/false).
merchant_id: Merchant ID for the account (empty if not applicable).
has_networks: Indicates if payment networks are available (true/false).
country: Country code for the query (e.g., KE).
currency: Default currency for the country (e.g., KES).
available_providers: Lists providers per payment rail (e.g., card: ["instasend", "pesapal"], momo: ["bitlipa"]).
provider_networks: Detailed configuration for each provider and network.
channels: Supported transaction types (e.g., c2b, b2c, card).
code: Unique identifier for the network (e.g., 2031).
description: Description of the network (e.g., "M-PESA mobile money service via Bitlipa").
max_amount: Maximum transaction amount.
min_amount: Minimum transaction amount.
name: Name of the network (e.g., "M-PESA").
provider: Provider name (e.g., bitlipa).
countries: Supported countries (optional, e.g., ["ALL"] for global).
currencies: Supported currencies (optional, e.g., ["USD", "KES"]).
country: Specific country for the network (optional, e.g., KE).
global: Indicates if the network is globally available (true/false).
required_fields: Specifies required fields for transactions.
amount, country, currency, provider, reference: Required for all transactions.
customer: Customer details (e.g., first_name, last_name, email, phone required; address required for card payments).
bitlipa, instasend, pesapal: Provider-specific requirements (e.g., merchant_id, public_key, redirect_url).
provider_operations: Supported operations per provider (e.g., b2c, c2b).
payment_limits: Transaction limits.
global: Overall limits for the country.
per_rail: Limits per payment rail (e.g., card, momo).
per_provider: Limits per provider (e.g., bitlipa, instasend, pesapal).
processing_times: Providers with instant or same-day processing.
fees: Fee structure for transactions.
structure: Fee calculation method (e.g., percentage_plus_fixed).
percentage: Percentage fee.
fixed_amount: Fixed fee.
currency: Fee currency.
provider_specific: Provider-specific fees.
supported_currencies: List of supported currencies (e.g., ["KES", "USD", "EUR"]).
webhook_support: Indicates webhook support (true/false).
refund_policy: Refund details.
supported: Whether refunds are supported.
time_limit_hours: Refund window in hours.
partial_refunds: Whether partial refunds are allowed.
compliance: Compliance requirements.
kyc_required: Whether KYC is required.
aml_compliant: Whether AML compliance is enforced.
pci_compliant: Whether PCI compliance is required.
user_experience: User experience details.
supports_guest_checkout: Whether guest checkout is allowed.
requires_account: Whether an account is required.
supports_saved_payment_methods: Whether saving payment methods is supported.
api_endpoints: Related API endpoints.
create_payment: Endpoint for creating payments.
check_status: Endpoint for checking transaction status.
webhook_url: Endpoint for webhook notifications.
metadata: API metadata.
version: API version.
last_updated: Timestamp of last update.
cache_ttl_seconds: Cache validity in seconds.
Sample Code
<?php
$curl = curl_init();
curl_setopt_array($curl, array(
CURLOPT_URL => 'https://backend.payhero.co.ke/api/global/discovery/payment-world/?country=KE',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => '',
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 0,
CURLOPT_FOLLOWLOCATION => true,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => 'GET',
CURLOPT_HTTPHEADER => array(
'Authorization: Basic amJXVU11TzB4M3JJjS0ZqYU00TFU4TGJ2WA=='
),
));
$response = curl_exec($curl);
curl_close($curl);
echo $response;
Last updated
Was this helpful?