Common Integration Patterns

This page covers the patterns most integrations need.

1. Authenticate Once, Refresh Automatically

Obtain a token at startup and refresh it 5 minutes before expiry. On any 401, refresh once and retry.

See Bearer Token Management and Authentication.

2. Discover Before You Purchase

Before the first purchase of a session, list the catalog scoped to your account so your UI shows only what you can vend:

GET /merchants/{merchantId}/products       -> products active for a merchant account
GET /sub-merchants/{subMerchantId}/products -> products active for a sub-merchant account
GET /products/categories                    -> all categories
GET /products/categories/{id}/fields        -> input fields the user must supply for a category

This avoids 1009 ("This product is not available for your account") errors at purchase time. See Product Availability.

3. Lookup Before Purchase (When Applicable)

For electricity, bill payments, and money transfer products, validate the customer's account first:

POST /lookup/electricity
POST /lookup/bill-payment
POST /lookup/money-transfer

This surfaces customer name, outstanding amount, and meter validity before you commit to a charge.

4. Purchase With An Idempotent Reference

Generate a merchantReference per logical purchase. Reuse the same reference on any retry. See Idempotency & Retries.

5. Poll For Final Status

Any non-terminal /purchase response (or any timeout) is resolved by polling POST /transactions. See the polling strategy in Webhooks.

6. Render The Receipt

Use the receipt object returned by /purchase (or the same object via /transactions). The shape varies by product category — fetch field metadata for the category to know which keys to render. See Receipt Configuration.

7. Classify Errors For Retry

Class	Examples	Action
Auth	401	Refresh token, retry once.
Authorization	403	Stop. Check role / product activation.
Validation	1001, 1004, 1005, 1008	Stop. Fix the input.
Account	1009, 1103, 1100–1107	Stop. Surface to user / ops.
Provider transient	1200, 1201, 1202, 1204	Retry with backoff or poll status.
Rate limit	429	Backoff and retry.
Server error	5xx	Backoff, retry, then poll.

See Error Handling and the Error Code Reference.

8. Reconcile End-Of-Day

Query POST /transactions with a date filter to download the day's transactions for your accounting reconciliation. Page through results using the pagination conventions.

---

Last updated: April 2026