Subthingy API

The Subthingy API powers brand gift cards, airtime, data, electricity, and pay-TV purchases for your customers. All routes live under a single base URL:

https://api.subthingy.io/v1

There is no separate staging host — live and test traffic share the same base URL. Which environment a request runs in is determined entirely by the X-Merchant-Key / X-Merchant-Secret pair you send: every merchant is provisioned with both a live credential and a test credential, and the API resolves environment from whichever one is presented. See Environments.

Quick start

1. Contact your account manager for your live and test API keys and onboarding.

2. Send X-Merchant-Key and X-Merchant-Secret on every request (see Authentication) — use your test key while integrating, and your live key for real customer traffic.

3. Complete production IP whitelisting before go-live.

4. Create a purchase with a sync route (recommended) — see Airtime or Bill payments.

5. If you use async, poll status with the same request_ref you submitted:

   GET /v1/transactions/status?request_ref={your_request_ref}

   See Check status.

6. Stay within the default rate limit of 30 TPS (1,800 RPM) unless a higher quota is arranged.

7. Provide reconciliation email addresses for T+1 reports.

What you can do

Networks (airtime & data)

Use lowercase network names: mtn, glo, airtel, 9mobile.