Loading…
arrow_backMerchant API Reference

Endpoints

POST /billers

When we need your list of providers for a service (cable/power/betting).

Request

{ "service": "cable" }

Response

{ "billers": [
  { "id": "dstv", "label": "DSTV" },
  { "id": "gotv", "label": "GOTV" }
] }

On USSD the customer picks a provider from this list, so we send you its id. On WhatsApp/Telegram they say the provider ("AEDC", "Ikeja Electric", "DStv") — we match that against this list (by label/id) and send you the matching id in /validate and /vend, just the same. So keep your labels recognizable (include the common name/acronym), and /billers is what makes chat channels resolve to your ids. If we can't match one, we fall back to sending the raw name.

POST /packages

Fixed-price items — data bundles (by phone number) or cable bouquets (by biller). You resolve the network for data from the number.

Request (data)

{ "service": "data", "msisdn": "08012345678" }

Request (cable)

{ "service": "cable", "biller": "dstv" }

Response

{ "network": "MTN", "packages": [
  { "id": "d1gb", "label": "1GB / 30 days", "amount": 300 },
  { "id": "d2gb", "label": "2GB / 30 days", "amount": 500 }
] }

network is optional (used for data). Each package amount is the price the customer pays.

POST /validate

Confirm a customer identifier (smartcard / meter / betting-ID) so we can show the account holder before charging.

Request

{ "service": "power", "biller": "ekedc", "customer_id": "45700012345" }

Response

{ "valid": true, "name": "ADA OKAFOR", "address": "12 Adeniyi Jones Ave, Ikeja, Lagos", "min_amount": 1000, "max_amount": 500000 }

Return { "valid": false } if the identifier is unknown. If you can't return a name, send { "valid": true, "name": "" } and we'll confirm using the raw identifier. address is optional — when you return it (e.g. the metered premises), it appears on the customer's receipt.

min_amount / max_amount (optional, whole naira) — per-meter vend limits (e.g. a prepaid disco floor/ceiling). When you return them, VendStack shows them to the customer at confirmation and rejects any amount outside the range before /vend. If you omit them, prepaid electricity falls back to a configurable ₦1,000 minimum. (These map straight from BuyPower's minVendAmount/maxVendAmount if you proxy that.)

POST /vend

Complete the purchase. Validate the PIN against customer_msisdn and debit that wallet here. Only the fields relevant to the service are present.

Request (data example)

{
  "reference": "VS-20260727-1A2B3C4D",
  "service": "data",
  "amount": 300,
  "convenience_fee": 0,
  "total": 300,
  "pin": "1234",
  "customer_msisdn": "2348030000000",
  "msisdn": "08012345678",
  "network": "MTN",
  "package_id": "d1gb"
}

customer_msisdn is the payer — the phone number of the wallet owner making the purchase (their WhatsApp number, or the USSD caller). It is always present, and the PIN and wallet debit apply to this account. msisdn (when present) is the recipient of airtime/data, which may differ from the payer.

amount, convenience_fee and total — which one do I debit?

Every /vend carries all three, and they mean different things:

Field What it is What to do with it
amount The product cost Vend this. ₦500 airtime, the ₦2,500 bundle, the ₦1,000 of power.
convenience_fee Your flat surcharge on this channel Yours to keep — it stays in your wallet as revenue.
total amount + convenience_fee Debit this from the customer's wallet.

Debit total, vend amount. With no convenience fee configured, convenience_fee is 0 and total equals amount, so a backend that only reads amount behaves exactly as it always has.

The fee is set by you, per channel, on that channel's setup page in the dashboard (₦0 = off). VendStack shows it to the customer, itemised, at the confirmation step — before they enter a PIN — so nobody is surprised by the charge:

Airtime ₦500 to 08031112222
Fee: ₦20
Total: ₦520
Enter PIN to confirm:

⚠️ If your /vend debits amount and ignores total, you will never actually collect the fee — the customer is told they paid ₦520 while your wallet only takes ₦500. Set a fee only once your backend reads total.

Scheduled and recurring runs carry the fee too, at whatever rate you have configured at run time — so turning the fee off stops charging existing schedules on their next cycle.

Field guide by service:

Field Airtime Data Cable Power Betting
customer_msisdn (payer / wallet owner) ✅ ✅ ✅ ✅ ✅
msisdn (recipient phone) ✅ ✅ – – –
network – ✅ – – –
biller – – ✅ ✅ ✅
customer_id (smartcard/meter/account) – – ✅ ✅ ✅
meter_type (prepaid/postpaid) – – – ✅ –
package_id – ✅ ✅ – –
product (optional) ✅ ✅ ✅ ✅ ✅
amount (product cost — vend this) ✅ ✅ ✅ ✅ ✅
convenience_fee (your surcharge, 0 when off) ✅ ✅ ✅ ✅ ✅
total (amount + fee — debit this) ✅ ✅ ✅ ✅ ✅
pin ✅ ✅ ✅ ✅ ✅

biller is your own id from /billers (e.g. "ekedc", "dstv") on every channel — we resolve chat-typed provider names to it for you (see /billers above).

product is an optional free-text label (e.g. "5GB") sent when a customer names a bundle over WhatsApp without picking from /packages. Use it to resolve the item when there's no package_id.

Sample /vend request for each product

Real payloads you can copy for testing — one per service:

Airtime — recharge a phone (may differ from the payer):

{
  "reference": "VS-20260814-A1B2C3D4",
  "service": "airtime",
  "amount": 200,
  "convenience_fee": 20,
  "total": 220,
  "pin": "1234",
  "customer_msisdn": "2348030000000",
  "msisdn": "08031112222",
  "product": "Airtime"
}

Data — a bundle for a phone; network and package_id come from /packages:

{
  "reference": "VS-20260814-B2C3D4E5",
  "service": "data",
  "amount": 2500,
  "pin": "1234",
  "customer_msisdn": "2348030000000",
  "msisdn": "08031112222",
  "network": "MTN",
  "package_id": "d5gb",
  "product": "5GB / 30 days"
}

Cable — a bouquet on a smartcard; biller/package_id are your ids:

{
  "reference": "VS-20260814-C3D4E5F6",
  "service": "cable",
  "amount": 10500,
  "pin": "1234",
  "customer_msisdn": "2348030000000",
  "biller": "dstv",
  "customer_id": "4567890123",
  "package_id": "compact",
  "product": "DStv Compact"
}

Power (electricity) — a meter recharge; note meter_type and that service is power:

{
  "reference": "VS-20260814-D4E5F6A7",
  "service": "power",
  "amount": 5000,
  "pin": "1234",
  "customer_msisdn": "2348030000000",
  "biller": "ekedc",
  "customer_id": "45700012345",
  "meter_type": "prepaid",
  "product": "Eko Electric"
}

Betting — fund a betting account:

{
  "reference": "VS-20260814-E5F6A7B8",
  "service": "betting",
  "amount": 3000,
  "pin": "1234",
  "customer_msisdn": "2348030000000",
  "biller": "bet9ja",
  "customer_id": "8899776",
  "product": "Bet9ja"
}

Scheduled & recurring runs (PIN-less)

Customers can schedule a purchase for later or make it recurring. When VendStack runs one of these on schedule, the customer isn't present to enter a PIN — so the call arrives with no pin and an extra field:

{
  "reference": "VS-20260805-9F8E7D6C",
  "service": "data",
  "amount": 2500,
  "customer_msisdn": "2348030000000",
  "msisdn": "08012345678",
  "network": "MTN",
  "package_id": "d5gb",
  "authorization": "scheduled"
}
  • authorization: "scheduled" marks a purchase the customer pre-authorised at setup. For these, debit the customer_msisdn wallet without a PIN — the request's HMAC signature is your proof it's genuinely from VendStack. Everything else (idempotency on reference, the response shape) is identical to a normal vend.
  • To support scheduling, your /vend must accept a signed request with no pin when authorization is present. If your backend rejects PIN-less vends, scheduled and recurring orders will fail. If you never want unattended debits, simply reject any request carrying authorization and the feature stays off.
  • VendStack never stores a customer's PIN — not even for recurring orders (CLAUDE.md safety model).

Response

{ "success": true, "message": "Delivered", "reference": "VS-20260727-1A2B3C4D", "balance": 16250, "token": "1234-5678-9012", "units": "238.1 kWh" }
  • success — did it go through?
  • message — shown to the customer on failure (e.g. "Incorrect PIN", "Insufficient balance").
  • balance (optional) — wallet balance after, shown to the customer.
  • token (optional) — prepaid electricity token, shown to the customer and printed on the PDF receipt.
  • units (optional) — units credited (e.g. "238.1 kWh"), shown beside the token on the receipt.
  • error_code (optional) — a machine-readable failure reason. Return "invalid_pin" on a wrong PIN so WhatsApp lets the customer retry instead of ending the chat. Other values (e.g. "insufficient_funds") end the transaction with your message.

POST /status (optional, recommended)

Reconcile a purchase after a timeout. If our /vend call doesn't return in time (a slow network), the purchase may still have completed on your side — so before telling the customer anything, we call /status with the same reference to learn what really happened.

Request

{ "reference": "VS-20260727-1A2B3C4D" }

Response

{ "status": "completed", "balance": 16250, "token": "1234-5678-9012", "units": "238.1 kWh" }

status is one of:

  • "completed" — it went through. We tell the customer it succeeded and show the token/units/balance if present, exactly like /vend.
  • "failed" (also "not_found", "reversed") — it definitively did not go through. We tell the customer it failed.
  • "pending" / anything else — still processing or unknown. We tell the customer we couldn't confirm and ask them to check before retrying.

Look the transaction up by reference (the same idempotency key from /vend). Skip this endpoint and a timed-out vend is simply reported to the customer as unconfirmed ("please check before trying again") — never a false failure, but also no positive confirmation. Implementing /status makes timeouts resolve cleanly.

POST /balance (optional)

Return a customer's wallet balance for a phone number. Implement it and:

  • customers can ask for it on every channel — Check Balance on the USSD, WhatsApp and Telegram menus, or just "how much do I have in my wallets?" to the WhatsApp/Telegram assistant or by SMS;
  • the assistant shows their balance before they confirm a purchase.

Skip it and those simply don't appear. Never required for a purchase.

Request

{ "msisdn": "2348030000000" }

Response — one wallet

{ "balance": 18750 }

Response — several wallets (main, commission, bonus…)

{
  "balance": 18750,
  "wallets": [
    { "name": "Main wallet", "balance": 18750 },
    { "name": "Commission wallet", "balance": 2300.50 }
  ]
}
  • balance is the spendable balance, in whole naira. It's what we compare against a purchase before asking for the PIN, so it must be the wallet /vend debits.
  • wallets (optional) lists everything the customer holds, in the order to show them. Each needs a name (shown as-is) and a balance in naira — kobo allowed, e.g. 2300.50. When a customer checks their balance, each wallet is shown on its own line. We never add them up, since a commission or bonus wallet usually can't be spent directly.
  • Send only balance and the customer sees that one figure. Send only wallets and the first one counts as spendable.

Return 4xx (or omit both) if you don't support it — we treat that as "not available" and move on.

POST /wallet-transfer (optional)

Move money between two of the customer's own wallets — e.g. "Move 7k from my commission wallet to my main wallet" to the WhatsApp or Telegram assistant. It's money movement, so it follows the same rules as a purchase:

  1. We match the wallet names the customer used to the ones your /balance returns in wallets (so this needs at least two wallets there), and check the source wallet can cover the amount.
  2. The customer sees a summary — "You want to move ₦7,000 from your Commission wallet to your Main wallet" — and replies YES.
  3. They enter their PIN, and only then do we call you. You validate the PIN and move the money.

Request

{
  "reference": "VS-20261029-48213",
  "customer_msisdn": "2348030000000",
  "from_wallet": "Commission wallet",
  "to_wallet": "Main wallet",
  "amount": 7000,
  "pin": "1234"
}

from_wallet and to_wallet are always exactly the names you returned from /balance. amount is whole naira.

Response

{
  "success": true,
  "message": "Transfer successful",
  "wallets": [
    { "name": "Main wallet", "balance": 25750 },
    { "name": "Commission wallet", "balance": 2000 }
  ]
}

wallets (optional) are the balances after the move; we show them to the customer. Leave them out and we call /balance instead.

  • Idempotent on reference. If you see a reference twice, move the money once and return the same result. A wrong-PIN retry reuses the reference.
  • Failures use the /vend shape: { "success": false, "message": "…", "error_code": "invalid_pin" }. invalid_pin lets the customer try again; insufficient_funds or anything else ends it with your message.
  • Timeouts. If you don't answer in time, we tell the customer the move is unconfirmed and to check their balance before trying again. We never claim it failed.
  • Not built? Return 404 and the customer is told moving money between wallets isn't available.
  • Transfers are not purchases. They don't count toward your plan's transactions, sales figures or webhooks.

POST /accounts (optional)

Return the bank account(s) a customer can transfer to in order to fund their wallet on your platform. This powers the Fund Wallet menu option (and the WhatsApp "fund my wallet" request): VendStack calls this with the customer's phone number, then displays the account(s) so they can transfer. VendStack never moves the money — you credit the customer's wallet when the transfer lands (via your own bank/virtual-account webhook).

Request

{ "customer_msisdn": "2348030000000" }

Response

{
  "accounts": [
    { "bank": "Wema Bank", "account_number": "7020001111", "account_name": "BuyVTU / Ada Okafor" }
  ]
}

Return one or more accounts (e.g. a dedicated virtual account per customer). Return an empty accounts array (or a 4xx) if the customer has no funding account yet — the customer is told to contact support. Skip this endpoint entirely and the Fund Wallet option simply reports that funding isn't available.

POST /authenticate (optional, recommended)

Tell VendStack up front whether a phone number already has an account. When you implement this, a customer whose number isn't recognized is sent straight to sign-up at the start of the conversation — before they pick a product, confirm, and enter a PIN — instead of hitting a dead-end at purchase time. Skip it and VendStack falls back to discovering "no account" from the /vend response (error_code: "account_not_found"), exactly as before.

Request

{ "phone": "2348030000000" }

Response

{ "exists": true }

Return { "exists": true } if the number has an account, { "exists": false } if it doesn't. Be precise: VendStack only diverts a customer to sign-up on an explicit "exists": false from an HTTP 200. Anything else — a 4xx/5xx, an unreachable endpoint, or a body without an exists field — is treated as "unknown", and the conversation proceeds normally (the post-vend fallback still catches an unregistered payer). Pair this with /register so the sign-up you route customers into can actually complete.

POST /register (optional)

Create an account for a new customer. When a number has no account — detected up front via /authenticate, or from the /vend response (error_code: "account_not_found") — VendStack offers a short sign-up on WhatsApp/Telegram — it collects the customer's name and a transaction PIN (the phone number is already known) — and posts them here.

Request

{ "phone": "2348030000000", "name": "Ada Okafor", "pin": "1234" }

Response

{ "success": true }

Create the account with phone as the identity and pin as their transaction PIN, then return { "success": true }. On failure return { "success": false, "message": "…" } (shown to the customer), or a 4xx. Skip this endpoint entirely and sign-up isn't offered — an unregistered customer is simply told no account was found.