Errors & codes

Response shapes

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

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

Create and status

Create and status use the same envelope: status, response_code, response_message, data.

Optional data fields you may see:

• external_reference, telco_message — common on sync airtime and data
• plan — plan code echoed on data and bill creates
• merchant_name, updated_at — on status and list responses
• token, units — prepaid electricity on sync bill create (and on status)
• kct1, kct2 — optional 20-digit Key Change Tokens when issued for the meter; omitted on most purchases
• payment_spent_on — optional on electricity purchase and status when the payment cleared meter debt instead of issuing a token (e.g. debt); omitted otherwise. Response-only — do not send on the request

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

Bill verify (optional)

POST /v1/transactions/verify returns status, code (HTTP-style integer 200), message, and data:

Send merchant_code, customer_msisdn, network, product, and plan_code (recommended) or legacy service_id. No client_request_id. 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. That is a customer-data problem, not a gateway failure. Verify outages are 502 with a generic message.

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).

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 Breeze 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.

eSIM

eSIM purchase and status use the same envelope as gift cards (00 / 01 / 02). Success data includes iccid, activation_code, smdp_address, and lpa. Pending orders must not be treated as delivered. See eSIM.

Transaction codes

Inside create and status responses, response_code maps to status:

Failed example (status):

{
  "status": "failed",
  "response_code": "01",
  "response_message": "Failed",
  "data": {
    "request_id": "req-20260517-003",
    "internal_reference": "019262ab-7c4d-7000-8000-000000000001"
  }
}

HTTP status codes

Health check

GET /v1/healthz

No authentication required. Use for uptime monitoring only.