Transactions

Sync vs async

Sync (recommended): the API runs vending before responding. You get the final outcome (response_code 00 or 01) in the create response. Use:

Route	Notes
`POST /ext/breeze/v1/transactions/airtime/sync`	Airtime only
`POST /ext/breeze/v1/transactions/data/sync`	Data only (`plan_code` required)

Async: the API stores the transaction, enqueues it, and returns immediately with HTTP 200 and response_code 02 (pending). Poll status until final.

Route	Notes
`POST /ext/breeze/v1/transactions`	`product` in body: `airtime`, `data`, `ELECTRICITY`, `CABLE`, or `BETTING`
`POST /ext/breeze/v1/transactions/airtime/async`	Forces `product: airtime`
`POST /ext/breeze/v1/transactions/data/async`	Forces `product: data`

Bill products require plan_code — see Electricity, Cable TV, or Betting.

Request body

Field	Required	Description
`merchant_code`	Yes	Your merchant profile
`customer_msisdn`	Yes	Subscriber number (`234…` or `080…`)
`network`	Yes	`mtn`, `glo`, `airtel`, `9mobile`
`product`	Yes	`airtime`, `data`, `ELECTRICITY`, `CABLE`, or `BETTING`
`amount`	Yes	Amount in Naira (string)
`client_request_id`	Yes	Your unique idempotency key
`plan_code`	Data & bills	Data: prefixed code from Data plans (e.g. `MTN-8`). Bills: catalog id from Electricity, Cable TV, or Betting. Legacy tariff/product ids still work for existing clients.

Create and status responses use status, response_code, response_message, and data.

Buy airtime (sync)


curl -X POST "https://staging-intelligent-70287b6a3284.herokuapp.com/ext/breeze/v1/transactions/airtime/sync" \
  -H "Content-Type: application/json" \
  -H "X-Merchant-Key: mk_live_your_key_id" \
  -H "X-Merchant-Secret: sk_live_your_secret" \
  -d '{
    "merchant_code": "YOUR_MERCHANT",
    "customer_msisdn": "2348012345678",
    "network": "glo",
    "product": "airtime",
    "amount": "200",
    "client_request_id": "req-20260517-001"
  }'

HTTP 200 — successful:


{
  "status": "success",
  "response_code": "00",
  "response_message": "Successful",
  "data": {
    "internal_reference": "019262ab-7c4d-7000-8000-000000000002",
    "msisdn": "2348012345678",
    "product": "airtime",
    "request_id": "req-20260517-001",
    "network": "glo",
    "amount": "200",
    "merchant_id": 10,
    "created_at": "2026-05-17 10:30:00"
  }
}

Buy data (sync)


curl -X POST "https://staging-intelligent-70287b6a3284.herokuapp.com/ext/breeze/v1/transactions/data/sync" \
  -H "Content-Type: application/json" \
  -H "X-Merchant-Key: mk_live_your_key_id" \
  -H "X-Merchant-Secret: sk_live_your_secret" \
  -d '{
    "merchant_code": "YOUR_MERCHANT",
    "customer_msisdn": "2348012345678",
    "network": "mtn",
    "product": "data",
    "amount": "500",
    "client_request_id": "req-20260517-002",
    "plan_code": "MTN-8"
  }'

Buy airtime (async)


curl -X POST "https://staging-intelligent-70287b6a3284.herokuapp.com/ext/breeze/v1/transactions" \
  -H "Content-Type: application/json" \
  -H "X-Merchant-Key: mk_live_your_key_id" \
  -H "X-Merchant-Secret: sk_live_your_secret" \
  -d '{
    "merchant_code": "YOUR_MERCHANT",
    "customer_msisdn": "2348012345678",
    "network": "mtn",
    "product": "airtime",
    "amount": "100",
    "client_request_id": "req-20260517-003"
  }'

HTTP 200 — pending (poll status):


{
  "status": "pending",
  "response_code": "02",
  "response_message": "Pending",
  "data": {
    "internal_reference": "019262ab-7c4d-7000-8000-000000000001",
    "msisdn": "2348012345678",
    "product": "airtime",
    "request_id": "req-20260517-003",
    "network": "mtn",
    "amount": "100",
    "plan": "",
    "merchant_id": 10
  }
}

Check status

Use after async creates, or to re-fetch an outcome.


GET /ext/breeze/v1/transactions/status/{request_id}

Use the same value you sent as client_request_id.


curl "https://staging-intelligent-70287b6a3284.herokuapp.com/ext/breeze/v1/transactions/status/req-20260517-003" \
  -H "X-Merchant-Key: mk_live_your_key_id" \
  -H "X-Merchant-Secret: sk_live_your_secret"

HTTP 200 — same envelope as create:


{
  "status": "success",
  "response_code": "00",
  "response_message": "Successful",
  "data": {
    "internal_reference": "019262ab-7c4d-7000-8000-000000000001",
    "msisdn": "2348012345678",
    "product": "airtime",
    "request_id": "req-20260517-003",
    "network": "mtn",
    "amount": "100",
    "merchant_id": 10,
    "merchant_name": "YOUR_MERCHANT",
    "created_at": "2026-05-17 10:30:00"
  }
}

`response_code`	`status`	Meaning
`00`	`success`	Completed successfully
`01`	`failed`	Failed
`02`	`pending`	Still processing

List transactions


GET /ext/breeze/v1/transactions

Query	Default	Description
`page`	`1`	Page number
`limit`	`10`	Page size
`msisdn`	—	Filter by subscriber
`network`	—	Filter by network name
`status`	—	Filter by status code (integer)


curl "https://staging-intelligent-70287b6a3284.herokuapp.com/ext/breeze/v1/transactions?page=1&limit=20" \
  -H "X-Merchant-Key: mk_live_your_key_id" \
  -H "X-Merchant-Secret: sk_live_your_secret"

HTTP 200:


{
  "status": "success",
  "data": [],
  "pagination": {
    "total": 0,
    "page": 1,
    "size": 20,
    "total_pages": 0
  }
}

Idempotency

Reusing the same client_request_id for a merchant returns 422. Query status instead of resubmitting.