Loading…
arrow_backMerchant API Reference

Conventions

  • Amounts are whole naira (integers). 500 = ₦500.
  • reference on a purchase is unique per order and idempotent — if you receive the same reference twice (a retry), return the original result; do not charge twice.
  • Respond 200 with 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 /vend times 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 to power before calling you — so you only ever branch on the five values above.