Transaction Lifecycle
Every purchase is asynchronous. Your server submits the request, we queue it to the upstream carrier, and the final status arrives via webhook (or/requery). This diagram shows the complete flow:
If your webhook endpoint is unreachable, we retry up to 5 times with exponential backoff. Implement
POST /requery as a fallback for any transaction that stays pending beyond your expected SLA.1. Two-Step Verification (Mandatory for Cable & Electricity)
Never blind-recharge a Cable TV or Electricity account. You must callGET /services/verify first, display the resolved customer name to your user, and only call POST /purchase after the user confirms the name is correct.
1
User enters account number
Your UI collects the meter or smartcard number from the user.
2
Call GET /services/verify
Send the account number and service ID to our verification endpoint.
3
Display the customer name
Show
customer_name prominently. E.g. “You are recharging: JOHN DOE”4
User confirms
The user confirms the name matches their account.
5
Call POST /purchase
Only now proceed with the purchase.
2. Strict Idempotency
Never blindly retry a/purchase request on network timeout.
idempotency_key in every purchase. If the same key is sent twice, the API returns the original transaction instead of charging again.
3. Timezone Awareness
All API timestamps are returned in UTC. Convert to West Africa Time (WAT / GMT+1) before displaying to Nigerian users.4. Secure Key Storage
✅ Do this
Store your API key in environment variables (
.env file). Never commit it to source control.❌ Never do this
Hardcode the key in your source code, client-side JavaScript, or mobile app bundles.

