💸 Transfers & Payouts
HeedPay allows merchants to programmatically send funds out of their wallet balances to any commercial bank or financial institution in Nigeria via Interbank Clearings.
To complete a safe interbank payout sequence, your implementation should strictly mirror the 3-step workflow lifecycle below.
1
Fetch Supported Banks List
Queries the core directory to return a dictionary of active bank targets along with their assigned routing configurations.
POST
https://heedpay.com.ng/api/bankslist/
JSON Request Body
CONTENT-TYPE: APPLICATION/JSON
{
"refId": "20260710xyz789" // Must start with YYYYMMDD (12-30 characters) (Required)
}
JSON Response Body
HTTP STATUS: 200 OK
{
"status": "success",
"message": "Bank List Approved Or Completed Successfully",
"data": {
"bankCode": "100033",
"bankName": "PalmPay",
"bankUrl": "https://transsnet-android-upload-image-prod.s3.amazonaws.com/activity/164672483950420-icon.png",
"bgUrl": "https://transsnet-android-upload-image-prod.s3.amazonaws.com/activity/164672484363613-bank%20card%20list_AFRIBANK%20NIGERIA%20PLC%20Copy%209.png"
}
}
2
Lookup Recipient Identity Naming
Performs an instant dynamic ledger KYC query to return the authenticated legal registration profile name before committing any outward assets.
POST
https://heedpay.com.ng/api/transfer/validateName/
JSON Request Body
CONTENT-TYPE: APPLICATION/JSON
{
"bankCode": "011", // The target institution code fetched from the Bank List matrix (Required)
"accountNumber": "3012345678" // 10-digit Nuban target routing directory string (Required)
}
JSON Response Body
HTTP STATUS: 200 OK
{
"status": "success",
"message": "Approved Or Completed Successfully"
"accountName": "Heedtech Sahee(HeedPay)"
"accountNumber": "97204473210"
'bankCode": "12345"
}
3
Execute Actual Payout
Fires a real-time clearing event to securely debit your business balance wrapper and immediately settle the beneficiary clearing account layer.
POST
https://heedpay.com.ng/api/transfer/
JSON Request Body
CONTENT-TYPE: APPLICATION/JSON
{
"bankName": "First Bank of Nigeria", // Text string representation of destination clearing institution
"bankCode": "011", // The destination bank routing designator code (Required)
"refId": "20260710transfer889", // Idempotence tracker. Must start with YYYYMMDD (12-30 characters)
"accountNumber": "3012345678", // 10-digit recipient destination account wrapper (Required)
"amount": "5000.00", // Actual base absolute transaction amount allocation value
"recepientName": "John Doe", // Matching target name returned during Stage 2 identity validation
"narration": "Invoice payment #455" // Description string context appended alongside processing logs
}
JSON Response Body
HTTP STATUS: 200 OK
{
"status": "success",
"bankName": "First Bank of Nigeria", // Text string representation of destination clearing institution
"bankCode": "00211", // The destination bank routing designator code (Required)
"accountNumber": "3012345678", // 10-digit recipient destination account wrapper (Required)
"recepientName": "Heedtech Universal", // Matching target name returned during Stage 2 identity validation
"amount": "5000.00", // Actual base absolute transaction amount allocation value
"oldbal": "50,000.00", // Actual base value before transaction initiate
"newbal": "44,980.00", // Actual base value after transaction initiate
"refId": "20260710transfer889", // Idempotence tracker. Must start with YYYYMMDD (12-30 characters)
"fee/charge": "20.00", // This charge fee helps us to run the service successfully
"stampDuty": "50.00", // This fee is mandatory by authorities for trnx above 10,000 upwards, heedpay doesn't benefit from it.
"sessionId": "100000023657489293047563524364", // Idempotence tracker. Must start with YYYYMMDD (12-30 characters)
"date": "2026-07-10", // date YYYYMMDD
"message": "Your transfer has been processed successfully.",
"narration": "Invoice payment #455" // Description string context appended alongside processing logs
}
}
Documentation last updated 1 year ago