🏛️ Dynamic Virtual Accounts
Deploy isolated, dynamic ledger targets on demand. A Dynamic Virtual Account enables merchants to map specific payment requests directly to a unique bank account number, ensuring clean, instant attribution for checkout flows.
Use the headers table below for all API requests on this page.
Required Request Headers
You must pass your HeedPay Public Key inside the authorization header field.
| Header Key | Value Example |
|---|---|
| Authorization | publickey9g4efbt45hg0d553f297b703fb510dd46e3e5cc |
| Content-Type | application/json |
| Accept | application/json |
1
1. Provision Dynamic Account
Generates a dedicated bank routing allocation reserved exclusively for the transaction.
POST
https://heedpay.com.ng.heedtech.com.ng/api/checkout-get-account/get_account.php
JSON Request Body
CONTENT-TYPE: APPLICATION/JSON
{
"refId": "2026327372bGDYE3GD7YHDRESERVED", // Must start with YYYYMMDD and be 12-30 characters (Required)
"email": "Heedpay@gmail.com", // Customer email identifier (Required)
"phone": "08160070009", // Customer contact hook (Required)
"amount": "10000" // Required settlement target amount (Required)
}
JSON Response Body
HTTP STATUS: 200 OK
{
"status": "success",
"message": "Customer account created successfully. Bank account(s) processed and ready for use.",
"event_type": "CHECKOUT_VIRTUAL_ACCOUNT",
"datetime": "20260623",
"refId": "2026327372bGDYE3GD7YHDRESERVED",
"virtualName": "Heedtech sahe(HeedPay)",
"virtualNumber": "36332838449",
"customer": {
"name": "Heedtech Universal",
"email": "customer@gmail.com",
"phone": "07018209812"
},
"errors": []
}
2
2. Verify Account Payment Settlement
Validate that the funds assigned to the generated dynamic virtual account have hit our clearing desk successfully using the tracking refId.
POST
https://heedpay.com.ng.heedtech.com.ng/api/checkout-get-account/verify_payment.php
JSON Request Body
CONTENT-TYPE: APPLICATION/JSON
{
"amount": "10000", // The amount expected on the dynamic account generated above (Required)
"refId": "2026327372bGDYE3GD7YHDRESERVED" // The tracking ID used to instantiate the allocation layer (Required)
}
Response Structures
SUCCESS RESPONSE
{
"status": "success",
"message": "Palmpay Virtual Payment Account Number was successfully credited"
}
PROCESSING RESPONSE (PENDING)
{
"status": "process",
"message": "Payment check initiated. Bank terminal clearing verification is pending."
}
FAILED / EXPIRED RESPONSE
{
"status": "fail",
"message": "Payment not received. The dynamic account routing layer has been terminated."
}
Checkout Widget SDK
Embed our drop-in javascript client framework inside your web checkout views to launch a beautiful, ready-to-use overlay modal with robust dynamic transaction feedback handlers. And once payment is made, you can hit the I've Sent the Money button to confirm the payment status.
Widget Preview (Isolated View)
HeedPay Checkout
heedpay@gmail.com
₦63,500.00
Transfer exactly the amount above to:
8768653524
PALMPAY Bank Heedpay
Waiting for transfer...
Secured by HeedPay
Integration Code
JAVASCRIPT INTEGRATION FRAMEWORK
<script src="https://heedpay.com.ng/checkout/js/widget.js"></script>
<script>
function generateRefId() {
const now = new Date();
const year = now.getFullYear();
const month = String(now.getMonth() + 1).padStart(2, '0');
const day = String(now.getDate()).padStart(2, '0');
const datePrefix = `${year}${month}${day}`;
const chars = 'ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789';
let randomPart = '';
for (let i = 0; i < 12; i++) {
randomPart += chars.charAt(Math.floor(Math.random() * chars.length));
}
return datePrefix + randomPart;
}
$("#checkout").click(function(e){
e.preventDefault();
heedPay.open({
authkey: 'public_79e916e78ea6b65e53a0020aa7b019b1f2c9b06f3b05194935005b4c8626',
amount: 100,
refId: generateRefId(),
phone: '09020971597',
email: 'customer@gmail.com'
});
});
let isRedirecting = false;
let processTimeout = null;
function showHeedPayStatus(type, title, message) {
const existingAlert = document.getElementById('heedpay-custom-status');
if (existingAlert) existingAlert.remove();
if (processTimeout) clearTimeout(processTimeout);
let config = {
bgColor: 'bg-white',
textColor: 'text-dark',
icon: '<div class="spinner-border text-primary" role="status"></div>',
shadow: 'shadow-lg',
footerButton: ''
};
if (type === 'success') {
config.icon = '<i class="bi bi-check-circle-fill text-success fs-1"></i>';
} else if (type === 'process') {
config.icon = '<div class="spinner-border text-primary" style="width: 3rem; height: 3rem;" role="status"></div>';
config.footerButton = `
<div class="mt-4 pt-2 border-top">
<button type="button" class="btn btn-light btn-sm text-muted w-100 fw-semibold" style="border-radius: 10px;" onclick="document.getElementById('heedpay-custom-status').remove()">
<i class="bi bi-eye-slash me-1"></i> Hide & Check Account
</button>
</div>
`;
} else if (type === 'closed') {
config.icon = '<i class="bi bi-exclamation-circle-fill text-secondary fs-1"></i>';
}
const statusDiv = document.createElement('div');
statusDiv.id = 'heedpay-custom-status';
Object.assign(statusDiv.style, {
position: 'fixed', top: '0', left: '0', width: '100%', height: '100%',
backgroundColor: 'rgba(15, 23, 42, 0.65)', zIndex: '20000', display: 'flex',
alignItems: 'center', justifyContent: 'center', backdropFilter: 'blur(4px)'
});
statusDiv.innerHTML = `
<div class="card p-4 text-center border-0 \${config.bgColor} \${config.textColor} \${config.shadow}" style="width: 360px; border-radius: 20px;">
<div class="card-body py-3">
<div class="mb-4">\${config.icon}</div>
<h5 class="fw-bold mb-2">\${title}</h5>
<p class="text-muted small mb-0 px-2">\${message}</p>
\${config.footerButton}
</div>
</div>
`;
document.body.appendChild(statusDiv);
if (type === 'process') {
processTimeout = setTimeout(() => {
const processingCard = document.getElementById('heedpay-custom-status');
if (processingCard) {
processingCard.remove();
}
}, 55000);
}
}
window.addEventListener("message", function(event) {
if (isRedirecting) return;
if (event.data === "HEEDPAY_SUCCESS" || (event.data && event.data.status === "success")) {
isRedirecting = true;
if (processTimeout) clearTimeout(processTimeout);
showHeedPayStatus('success', 'Payment Confirmed!', 'Your transaction was completed successfully. Redirecting to dashboard...');
setTimeout(function(){
window.location.href = "https://yourdomain/dashboard/transactions";
}, 2500);
return;
}
if (event.data && event.data.status === "process") {
showHeedPayStatus('process', 'Verifying Settlement...', 'Checking confirmation with the bank terminal. You can safely minimize this.');
}
if (event.data === "HEEDPAY_CLOSED") {
if (processTimeout) clearTimeout(processTimeout);
const overlay = document.getElementById('heedpay-modal-overlay');
if (overlay) document.body.removeChild(overlay);
showHeedPayStatus('closed', 'Window Closed', 'Payment frame closed. Outbound transactions process background settlement checks automatically.');
setTimeout(() => {
const statusCard = document.getElementById('heedpay-custom-status');
if(statusCard) statusCard.remove();
}, 3500);
}
});
</script>