Wallet-based withdrawal (V1)
POST
/api/v2/withdraw
curl -X POST "https://api.payhero.africa/api/v2/withdraw" \ -u "API_USERNAME:API_PASSWORD" \ -H "Content-Type: application/json" \ -d '{ "external_reference": "TX1234ABCre55AH", "account_id": 63, "amount": 10, "phone_number": "0712345678", "account_number": "0712345678", "network_code": "63902", "channel": "phone", "recipient_type": "MSISDN", "callback_url": "https://payhero-dev.free.beeceptor.com"}'<?php$ch = curl_init("https://api.payhero.africa/api/v2/withdraw");$options = [ CURLOPT_RETURNTRANSFER => true, CURLOPT_CUSTOMREQUEST => "POST", CURLOPT_USERPWD => "API_USERNAME:API_PASSWORD", CURLOPT_HTTPHEADER => ["Content-Type: application/json"], CURLOPT_POSTFIELDS => json_encode([ "external_reference" => "TX1234ABCre55AH", "account_id" => 63, "amount" => 10, "phone_number" => "0712345678", "account_number" => "0712345678", "network_code" => "63902", "channel" => "phone", "recipient_type" => "MSISDN", "callback_url" => "https://payhero-dev.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/withdraw", auth=("API_USERNAME", "API_PASSWORD"), json={ "external_reference": "TX1234ABCre55AH", "account_id": 63, "amount": 10, "phone_number": "0712345678", "account_number": "0712345678", "network_code": "63902", "channel": "phone", "recipient_type": "MSISDN", "callback_url": "https://payhero-dev.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/withdraw", { method: "POST", headers: { Authorization: `Basic ${auth}`, "Content-Type": "application/json", }, body: JSON.stringify({ "external_reference": "TX1234ABCre55AH", "account_id": 63, "amount": 10, "phone_number": "0712345678", "account_number": "0712345678", "network_code": "63902", "channel": "phone", "recipient_type": "MSISDN", "callback_url": "https://payhero-dev.free.beeceptor.com" }),});
const data = await response.json();console.log(data);Legacy V1 withdrawal endpoint. Disburse to a phone number, paybill, or
till. Use recipient_type (MSISDN or PAYBILL) plus short_code /
account_number to target the destination.
Authorizations
Section titled “Authorizations”Request Bodyrequired
Section titled “Request Bodyrequired”Media typeapplication/json
object
external_reference
required
string
account_id
required
integer
amount
required
number
phone_number
required
string
account_number
Destination account number.
string
network_code
string
channel
required
string
recipient_type
required
MSISDN for phone, PAYBILL for paybill/till.
string
short_code
Paybill or till number (required for PAYBILL).
string
callback_url
string format: uri
Examples
Withdraw to phone number
{ "external_reference": "TX1234ABCre55AH", "account_id": 63, "amount": 10, "phone_number": "0712345678", "account_number": "0712345678", "network_code": "63902", "channel": "phone", "recipient_type": "MSISDN", "callback_url": "https://payhero-dev.free.beeceptor.com"}Withdraw to paybill
{ "external_reference": "TX1234ABCre55AH", "account_id": 63, "amount": 10, "phone_number": "0712345678", "account_number": "0723456789", "network_code": "63902", "channel": "phone", "recipient_type": "PAYBILL", "short_code": "123456", "callback_url": "https://payhero-dev.free.beeceptor.com"}Withdraw to till
{ "external_reference": "TX1234ABCre55AH", "account_id": 63, "amount": 10, "phone_number": "0712345678", "account_number": "0734567890", "network_code": "63902", "channel": "phone", "recipient_type": "PAYBILL", "short_code": "654321", "callback_url": "https://payhero-dev.free.beeceptor.com"}Responses
Section titled “Responses”Withdrawal queued.
Media typeapplication/json
object
status
string
merchant_reference
string
checkout_request_id
string
response_code
string
conversation_id
string
external_reference
string
Example
{ "status": "QUEUED", "merchant_reference": "UFD003742176.eO", "checkout_request_id": "0aaef9ef-15a6-4ff6-ba9e-35c9d33eb560", "response_code": "200", "conversation_id": "UFD003742176.eO", "external_reference": "TX1234ABCre55AH"}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}