Errors & codes

Response shapes

Field conventions (airtime, data, electricity, cable, betting)

These rules apply to every transaction product on the external API.

Create (sync or async)

Optional data fields you may see:

• telco_message — common on sync airtime and data. On a failed bill, telco_message is the biller reason when one was returned (for example a meter that cannot be paid online, or an amount below the minimum)
• plan — plan code echoed on data and bill creates
• token, units — prepaid electricity on sync bill create (and on status payload)
• kct1, kct2 — optional 20-digit Key Change Tokens on prepaid electricity when issued for the meter; omitted on most purchases
• payment_spent_on — optional on electricity purchase data and status payload when the payment cleared meter debt instead of issuing a token (e.g. debt); omitted otherwise. Response-only — do not send on the request
• merchant_name — on some status payloads

Bill products (ELECTRICITY, CABLE, BETTING) are always sync on create — expect response_code 00 or 01, not pending 02. Airtime and data on POST /v1/transactions without a /sync route are async (02 pending until polled).

Telco data.network in responses is typically uppercase (MTN, GLO, …) even when the request used lowercase.

Status poll (Subthingy envelope)

Status uses a different JSON shape from create — state, code, message, payload:

payload.created_at and payload.updated_at use YYYY-MM-DD HH:MM:SS.

Bill extras on success: prepaid electricity may include payload.token, payload.units, and optionally payload.kct1 / payload.kct2 (Key Change Tokens — load on the meter before the recharge token when present). When payment cleared meter debt instead of issuing a token, payload.payment_spent_on may be present (e.g. debt) with no token.

Request field aliases

Transaction create and bill verify accept either naming style:

Bill verify (optional)

POST /v1/transactions/verify uses the Subthingy envelope — state, code, message, result:

No request_ref on verify. See Bill payments — Verify customer.

On rejected meters, smartcards, or betting IDs, HTTP is 400 with status error, integer code 400, and message set to the rejection reason (for example that the meter is not a valid Ibadan Electric prepaid meter). That is a customer-data problem, not a gateway failure — do not treat it as 502. Verify outages are 502 with a generic message.

On dedicated sync routes (/transactions/airtime/sync, /transactions/data/sync), product is set by the route.

Gift cards

Gift card routes use the same authentication and response envelopes as the rest of the Subthingy API.

Catalog, quote, availability

Uses status, code (HTTP-style integer, e.g. 200), message, and data.

Purchase and order status

Uses the same envelope as transaction create: status, response_code, response_message, and data.

GET /giftcards/orders/{request_id} returns the same envelope as purchase — poll until response_code is 00 or 01.

Transaction codes

On status, outcomes map to code / state:

Failed example (status):

{
  "state": "failed",
  "code": "01",
  "message": "Failed",
  "payload": {
    "request_id": "subthingy-req-20260517-001",
    "internal_reference": "019262ab-7c4d-7000-8000-000000000001"
  }
}

On async create, pending is returned immediately with HTTP 200 (not 202):

{
  "status": "pending",
  "response_code": "02",
  "response_message": "Pending",
  "data": { }
}

HTTP status codes

Health check

GET /v1/healthz

No authentication required.