API reference

Both rails are live. This is a sandbox: it never touches real money, never contacts a real rail, and holds only synthetic test data.

Two pieces of configuration, and nothing else:

Authentication

Authorization: Bearer <API_KEY>

Required on every call except GET /health and GET /api/v1/reference, which are open so you can confirm you're wired up before the key is necessarily right. A wrong or missing key returns 401 — if every call 401s, it's almost always the key value rather than an access problem.

First call to make

curl {BASE_URL}/health
→ {"status":"ok"}

This checks the gateway and its database, returning 503 if the database is unreachable. It won't report healthy while broken, so it's safe to trust in a startup self-test.

• Money is an integer in the smallest currency unit. 29900 is ৳299.00. Never a float, anywhere.
• Timestamps are UTC ISO 8601 — 2026-08-09T03:36:02.197213+00:00.
• IDs are prefixed: tok_ tokens, ch_ charges, re_ refunds, conf_ confirmations.
• Ignore response fields you don't recognise rather than failing on them. Existing field names won't change without being flagged in the gateway's changelog.

Reusing an Idempotency-Key returns the original charge, unchanged, with status 200 instead of 201/402. The body is byte-identical to the first response.

POST /api/v1/card/charges   Idempotency-Key: abc  →  201  ch_8e09…
POST /api/v1/card/charges   Idempotency-Key: abc  →  200  ch_8e09…   (same charge, no second record)

The outcome engine is not re-run on a replay. That matters: for a card outside the deterministic set, re-running would roll a fresh random outcome, so the same request could return SUCCESS on one attempt and HARD_FAIL on the next.

Concurrent requests with the same key are safe. A unique database constraint decides the winner and the loser returns the winner's charge, so correctness doesn't depend on winning a lookup race.

This rail does not resolve on the first call. It's a two-step flow mirroring a real WAP confirmation: initiating a charge bills nobody until the subscriber confirms.

POST /api/v1/telecom/charges       →  202  pending_confirmation · returns confirmation_id
POST /api/v1/telecom/confirm/{id}  →  200  the subscriber confirms; only now does it resolve
GET  /api/v1/telecom/charges/{id}  →  200  current state

{ "msisdn": "+8801700000002", "amount": 29900, "currency": "BDT" }

{
  "id": "ch_251750f9fb4347a6bda60c37",
  "msisdn": "+8801700000002",
  "amount": 29900,
  "currency": "BDT",
  "status": "pending_confirmation",
  "outcome": "PENDING",
  "decline_code": null,
  "decline_message": null,
  "confirmation_id": "conf_f49fba3d236c41478cd3e38d",
  "confirmation_url": "{BASE_URL}/sandbox-wap/conf_f49fba3d236c41478cd3e38d",
  "grace_deadline": "2026-08-09T07:14:09.081+00:00",
  "next_retry_at": null,
  "created_at": "2026-08-09T07:14:05.193800+00:00",
  "confirmed_at": null,
  "resolved_at": null
}

{
  "id": "ch_3405119500f441dd923cadf7",
  "msisdn": "+8801700000001",
  "status": "succeeded",
  "outcome": "SUCCESS",
  "decline_code": null,
  "decline_message": null,
  "confirmed_at": "2026-08-09T07:14:06.714+00:00",
  "resolved_at": "2026-08-09T07:14:06.714+00:00"
}

{
  "id": "ch_251750f9fb4347a6bda60c37",
  "status": "pending_retry",
  "outcome": "RETRY",
  "decline_code": "insufficient_balance",
  "decline_message": "The subscriber's prepaid balance is too low.",
  "next_retry_at": "2026-08-09T07:14:07.688+00:00",
  "confirmed_at": "2026-08-09T07:14:05.688+00:00",
  "resolved_at": null
}

{
  "id": "ch_8e4ecdacfa7e4793a5d40734",
  "msisdn": "+8801700000004",
  "status": "expired",
  "outcome": "EXPIRED",
  "decline_code": null,
  "decline_message": null,
  "confirmed_at": null,
  "resolved_at": "2026-08-09T07:14:13.539+00:00"
}

Statuses, and which are final

The simulated clock

The grace period and retry shift run on an accelerated clock, not real days — one simulated “day” defaults to 30 seconds, so an unconfirmed charge expires about half a minute after it's initiated. Read grace_deadline off the charge rather than assuming the interval, since a gateway configured for fast tests uses a much shorter one. Expiry is evaluated when the charge is read, so a GET after the deadline returns expired — no confirm call needed, and no background job to wait on.

Carrier billing decline codes

These are per-rail. Card's insufficient_funds is deliberately not reused here — it describes an issuer declining, not a prepaid balance running out.

These always produce the same result, so you can trigger any path on demand. Rendered from the outcome engine's own tables, so this page cannot disagree with what a charge actually does.

Test cards

Test phone numbers

Any other number behaves like +8801700000001 — deliberately, so ad hoc testing never lands on the never-confirms case by accident.

Every error has the same shape:

{ "error": { "code": "snake_case_code", "message": "human readable sentence" } }

The one exception: 504 has no body at all. Don't try to parse it.

120 requests per rolling 60 seconds by default, shared across both rails — it models one API credential's budget, not a per-endpoint limit. Exceeding it returns 429 with a Retry-After header.

It exists so your rate-limit handling can be exercised against a real 429 rather than assumed to work. Two caveats: the counter is checked after the API key, so a wrong-key retry loop 401s rather than eating the budget; and it's counted per server instance, so on a multi-instance deployment the effective ceiling is higher than the configured number.

1. Branch on outcome, not HTTP status. 402 is a normal decline, not a failure.
2. Send a fresh Idempotency-Key per charge attempt, and reuse it on retries of that same attempt.
3. Handle 504 with an empty body as its own case, distinct from a decline. Nothing reached the rail's ledger and no charge record exists.
4. A 202 is not a result. Nothing is charged until the confirmation step completes, so don't mark a subscription active off the initiate call.
5. pending_retry is not terminal. resolved_at is null and the confirmation stays usable.
6. Don't treat /api/v1/reset as part of the rail contract. It has no analogue on a real rail.
7. Nothing here should require adapter code specific to this sandbox. If you find yourself writing a special case for it, that's a gap in the contract worth reporting back rather than working around.