Conventions
- Amounts are whole naira (integers).
500= ₦500. referenceon a purchase is unique per order and idempotent — if you receive the samereferencetwice (a retry), return the original result; do not charge twice.- Respond
200with JSON. Reply within a few seconds — USSD sessions are short. - Timeouts. We wait up to 2 minutes for the money/verification calls (
/vend,/validate,/status) since provider networks can be slow to settle; catalog reads (/billers,/packages) use a shorter timeout. If a/vendtimes out, we reconcile via/status(below) before telling the customer anything — a purchase that succeeded on your side is never reported as a failure. - Return errors as JSON (see Errors); we turn them into a friendly message for the customer.
service values
Every request that names a product uses one of these exact strings in the service field — on every channel (USSD, WhatsApp, Telegram):
service |
Product | Customer identifier | Notes |
|---|---|---|---|
airtime |
Airtime top-up | recipient phone (msisdn) |
|
data |
Data bundles | recipient phone (msisdn) |
you resolve the network from the number |
cable |
Cable / TV (DStv, GOtv, StarTimes) | smartcard (customer_id) |
|
power |
Electricity — prepaid/postpaid meters | meter number (customer_id) |
the value is always power, never electricity, even though customers say "electricity" |
betting |
Betting wallet funding | account/user ID (customer_id) |
Electricity is sent as
power. WhatsApp/Telegram customers naturally say "electricity", but VendStack always normalizes it topowerbefore calling you — so you only ever branch on the five values above.