Wallet-based collection (V1)
POST
/api/v2/payments
curl -X POST "https://api.payhero.africa/api/v2/payments" \ -u "API_USERNAME:API_PASSWORD" \ -H "Content-Type: application/json" \ -d '{ "amount": 10, "phone_number": "0712345678", "provider": "sasapay", "network_code": "63902", "account_id": 63, "external_reference": "test_ext", "callback_url": "https://payd-txest.free.beeceptor.com"}'<?php$ch = curl_init("https://api.payhero.africa/api/v2/payments");$options = [ CURLOPT_RETURNTRANSFER => true, CURLOPT_CUSTOMREQUEST => "POST", CURLOPT_USERPWD => "API_USERNAME:API_PASSWORD", CURLOPT_HTTPHEADER => ["Content-Type: application/json"], CURLOPT_POSTFIELDS => json_encode([ "amount" => 10, "phone_number" => "0712345678", "provider" => "sasapay", "network_code" => "63902", "account_id" => 63, "external_reference" => "test_ext", "callback_url" => "https://payd-txest.free.beeceptor.com", ]),];curl_setopt_array($ch, $options);$response = curl_exec($ch);curl_close($ch);echo $response;import requests
response = requests.post( "https://api.payhero.africa/api/v2/payments", auth=("API_USERNAME", "API_PASSWORD"), json={ "amount": 10, "phone_number": "0712345678", "provider": "sasapay", "network_code": "63902", "account_id": 63, "external_reference": "test_ext", "callback_url": "https://payd-txest.free.beeceptor.com", },)print(response.json())const auth = Buffer.from("API_USERNAME:API_PASSWORD").toString("base64");
const response = await fetch("https://api.payhero.africa/api/v2/payments", { method: "POST", headers: { Authorization: `Basic ${auth}`, "Content-Type": "application/json", }, body: JSON.stringify({ "amount": 10, "phone_number": "0712345678", "provider": "sasapay", "network_code": "63902", "account_id": 63, "external_reference": "test_ext", "callback_url": "https://payd-txest.free.beeceptor.com" }),});
const data = await response.json();console.log(data);Legacy V1 collection endpoint. Initiates a customer collection (STK push /
offline). Use channel_id for payment-channel-based collections, or
network_code for wallet-based collections. Set is_offline: true for
offline (paybill/till) collections.
For offline collections, no STK push is sent. The customer pays via
M-Pesa Paybill 756756, using account number 553125#<CheckoutRequestID>
(the CheckoutRequestID is returned in this endpoint’s response). Confirm
the exact paybill/account template for your account on your dashboard.
Authorizations
Section titled “Authorizations”Request Bodyrequired
Section titled “Request Bodyrequired”Media typeapplication/json
object
amount
required
number
phone_number
required
Customer phone number.
string
provider
required
E.g. sasapay, m-pesa.
string
network_code
Network code for wallet-based collections.
string
channel_id
Channel ID for payment-channel-based collections.
integer
account_id
required
integer
is_offline
Set true for offline (paybill/till) collections.
boolean
external_reference
string
merchant_fee
number
callback_url
Your system’s callback URL.
string format: uri
Examples
Wallet-based collection
{ "amount": 10, "phone_number": "0712345678", "provider": "sasapay", "network_code": "63902", "account_id": 63, "external_reference": "test_ext", "callback_url": "https://payd-txest.free.beeceptor.com"}Offline collection
{ "amount": 10, "phone_number": "0712345678", "provider": "sasapay", "network_code": "63902", "account_id": 63, "is_offline": true, "external_reference": "test_ext", "merchant_fee": 10, "callback_url": "https://payd-txest.free.beeceptor.com"}Payment-channel-based collection
{ "amount": 1, "phone_number": "0712345678", "provider": "m-pesa", "channel_id": 8949, "account_id": 63, "is_offline": true, "external_reference": "test_ext", "merchant_fee": 10, "callback_url": "https://payhero-dev.free.beeceptor.com"}Responses
Section titled “Responses”Collection queued.
Media typeapplication/json
object
success
boolean
status
string
reference
string
CheckoutRequestID
string
external_reference
string
Example
{ "success": true, "status": "QUEUED", "reference": "UFD003217286.iI", "CheckoutRequestID": "29119", "external_reference": "test_ext"}The request was rejected (validation or business-rule failure).
Media typeapplication/json
object
error_code
string
error_message
string
status_code
integer
Examples
{ "error_code": "invalid_argument", "error_message": "the transaction amount is insufficient as it wont cater for cost: (4.62)", "status_code": 400}{ "error_code": "invalid_argument", "error_message": "The passed channel is not active", "status_code": 400}Missing or invalid Basic auth credentials.
Media typeapplication/json
object
error_code
string
error_message
string
status_code
integer
Example
{ "error_code": "invalid_argument", "error_message": "the transaction amount is insufficient as it wont cater for cost: (4.62)", "status_code": 400}