API reference

Create a checkout session

Creates a payment page and returns its URL. Use this when you do NOT have the customer's number — a payment link in a chat, a "Pay now" button, an invoice email. If you already know the number, call `POST /v1/collections` and skip checkout.

The amount is fixed here, by you. The returned token authorises paying this one bill and nothing else, so a leaked link risks someone paying a bill that was already owed — not minting a new charge.

You learn the outcome the same way as any other payment: the webhook for the resulting collection, or by polling it. The page is not your notification channel.

Requires an `Idempotency-Key` header.

Read a checkout session

Called by the payment page to render itself, and polled to watch the outcome. Authorised by the token in the path — no key, which is why this route is anonymous.

Returns only what the page must display: merchant display name, amount, currency, description, return URL and status. Never the merchant id, never anything about other transactions.

An unknown, malformed or expired token all answer 404 identically. This URL is guessable by anyone on the internet, so it must not reveal whether a session ever existed.

Pay a checkout session

Submits the customer's number and starts the charge. Anonymous — the token in the path is the entire authorisation.

Returns **202 Accepted**, not 200: the operator has prompted the customer and they have not approved yet. Poll `GET /v1/checkout/{token}` for the outcome.

One session yields at most one successful payment. Concurrent attempts are serialised, so a double-tap cannot produce two charges — but a FAILED attempt may be retried on the same link, which is what lets a customer who mistyped their number try again.

No `Idempotency-Key`: a browser has no secret and no stable identity, so the session itself is the idempotency scope.

Create a collection

Charges a customer's mobile wallet. Returns immediately with status `accepted` — the customer still has to approve on their phone, so this is not a completed payment. Poll the collection or wait for the webhook.

Requires an `Idempotency-Key` header (a UUID you generate). Retrying with the same key replays the original response instead of charging twice.

Retrieve a collection

The authoritative status. Webhooks are a convenience; this is the source of truth, and a client that only listens for callbacks will eventually miss one.

Another merchant's collection returns 404, identical to an id that does not exist — a 403 would confirm it exists.

Create a payout

Sends money to a mobile wallet. Two different balances can refuse it: your own spendable balance, checked here (`payout_exceeds_balance` — the amount plus its fee must fit); and our operator float, checked at submission, which FAILS the payout with `insufficient_float` rather than rejecting the call.

A payout you requested seconds ago already holds its amount, even though your posted balance has not moved — the ledger only posts on completion.

Requires an `Idempotency-Key` header.

Retrieve a payout

`completed` means the recipient has the money. Another merchant's payout returns 404, identical to an id that does not exist.

Refund a collection

A refund is its own transaction with its own `ref_` id — never a state change on the original collection, which stays `completed` forever.

Only `completed` collections are refundable. Omit `amount` to refund everything still refundable; partial refunds are allowed and accumulate, and a refund still in flight holds its amount, so `refund_exceeds_refundable` can appear even when the arithmetic looks fine.

An unknown collection, or one belonging to another merchant, returns 404.

Retrieve a refund

Another merchant's refund returns 404, identical to a missing id.