Skip to main content
These are not optional suggestions. Not following these patterns — especially Two-Step Verification — can result in funds sent to the wrong account with no possibility of reversal.

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 call GET /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.
Why? Electricity and Cable TV transactions are processed instantly and are irreversible. Verifying the account name is the only way to protect your users from paying for someone else’s account.

2. Strict Idempotency

Never blindly retry a /purchase request on network timeout.
Always include a unique 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.
If a key is ever exposed, revoke it immediately from the Developer Dashboard and generate a new one.