Customer receipts (optional)
Everything above is VendStack calling you. This endpoint goes the other way: when a customer funds their wallet on your platform — a bank transfer lands, a card payment clears, or your support team credits them — tell VendStack and we send the customer a branded wallet-funding receipt in their chat with you, on WhatsApp and Telegram. It's the same receipt card customers already get after a purchase, so the experience is consistent.
- Receipts go out on each chat channel you hold an active subscription to. No subscription on a channel, or the channel not connected → that channel is skipped, the rest still go.
- Receipts are free: they don't count against your monthly transaction allotment.
- We only message customers a channel can reach: a WhatsApp number that has chatted with your business, or a Telegram chat that has shared its phone number. Anyone else is skipped (
unknown_customer) rather than cold-messaged. - WhatsApp can only deliver inside Meta's 24-hour customer-service window. A customer who last messaged you more than a day ago won't receive the WhatsApp copy (
outside_24h_windowon the dashboard); Telegram has no such limit. - Idempotent on
reference: send the same funding twice and the customer still gets one receipt per channel.
POST https://vendstack.com.ng/api/v1/merchant/receipts/wallet-funding
Headers — your API key plus a signature made with your signing secret (both on the Merchant API card):
| Header | Value |
|---|---|
X-VendStack-Key |
your API key (vsk_live_…) |
X-VendStack-Timestamp |
unix seconds, now |
X-VendStack-Signature |
hex HMAC-SHA256 of {timestamp}.{rawBody} using your signing secret |
Content-Type |
application/json |
This is the same scheme you already use to verify our webhooks, with the roles reversed. Timestamps older than 5 minutes are refused.
Request
{
"reference": "PSK-7F3A91C2",
"customer_msisdn": "2348030000000",
"amount": 5000,
"amount_paid": 5050,
"balance": 16250,
"method": "Bank transfer",
"paid_at": "2026-10-29T10:12:00+01:00"
}
| Field | Meaning | |
|---|---|---|
reference |
required | your unique reference for this funding (idempotency key) |
customer_msisdn |
required | the customer's phone — the same number you key their wallet on. 2348030000000 or 08030000000 |
amount |
required | whole naira credited to the wallet |
amount_paid |
optional | what the customer actually paid, when a fee was withheld; the receipt itemises the difference |
balance |
optional | wallet balance after the credit, shown on the receipt |
method |
optional | short label shown as "Method", e.g. Bank transfer, Card payment, Credited by support |
paid_at |
optional | ISO-8601 time of the payment; defaults to now |
Response — 202 Accepted when at least one channel will carry it:
{ "accepted": true, "reference": "PSK-7F3A91C2", "channels": { "whatsapp": "queued", "telegram": "no_subscription" } }
200 with "accepted": false when no channel can reach this customer — nothing is sent, and channels says why per channel (not_connected, no_subscription, unknown_customer, merchant_suspended). 401 on a bad key or signature; 422 on a malformed body.
Delivery happens in the background. The Merchant API card on your dashboard shows how many receipts landed in the last 30 days and the most recent reason one didn't.
PHP
$body = json_encode([
'reference' => $funding->reference,
'customer_msisdn' => $user->phone,
'amount' => (int) $funding->amount,
'balance' => (int) $wallet->balance,
'method' => 'Bank transfer',
]);
$timestamp = (string) time();
$signature = hash_hmac('sha256', $timestamp.'.'.$body, $yourSigningSecret);
Http::withHeaders([
'X-VendStack-Key' => $yourApiKey,
'X-VendStack-Timestamp' => $timestamp,
'X-VendStack-Signature' => $signature,
])->withBody($body, 'application/json')->post('https://vendstack.com.ng/api/v1/merchant/receipts/wallet-funding');
Node
const body = JSON.stringify({ reference, customer_msisdn, amount, balance, method: 'Bank transfer' });
const timestamp = String(Math.floor(Date.now() / 1000));
const signature = crypto.createHmac('sha256', signingSecret).update(`${timestamp}.${body}`).digest('hex');
await fetch('https://vendstack.com.ng/api/v1/merchant/receipts/wallet-funding', {
method: 'POST',
headers: { 'Content-Type': 'application/json', 'X-VendStack-Key': apiKey, 'X-VendStack-Timestamp': timestamp, 'X-VendStack-Signature': signature },
body,
});
Sign the exact bytes you send — serialise once, sign that string, and post that same string.