Topups
Gaming top-ups and mobile recharges - players, operators, variants, async fulfillment
The topups vertical covers two product families that share an API surface:
- Gaming top-ups - in-game currency, item bundles, season passes. Identified by a player/account ID (sometimes plus a server/region).
- Mobile recharges - prepaid airtime and data plans. Identified by an MSISDN (mobile number). Many countries require operator detection before pricing.
Unlike vouchers, top-ups have variants (SKU-level pricing within a product) and are mostly fulfilled asynchronously - fulfilment is confirmed via callback or status polling, not in the original request.
For digital gift cards (codes/PINs/URLs delivered immediately), see the Vouchers vertical. For eSIMs, see the eSIM vertical.
Endpoints
| Method | Path | Page |
|---|---|---|
GET | /api/v1/topups/products | Products |
GET | /api/v1/topups/products/:id | Products |
GET | /api/v1/topups/products/:id/variants | Variants |
GET | /api/v1/topups/variants/:id | Variants |
POST | /api/v1/topups/lookup | Mobile Lookup |
POST | /api/v1/topups/charges | Charges |
POST | /api/v1/topups/orders | Create order |
GET | /api/v1/topups/orders | Orders |
GET | /api/v1/topups/orders/:id | Orders |
PATCH | /api/v1/topups/orders/:id/notification-email | Orders |
Where to start
- Gaming top-up flow — player ID → variant → charges → order → poll
- Mobile recharge flow — lookup → variant → charges → order → poll
- Sync vs async delivery — top-ups are async-by-default
Eventual delivery
Octopus Cards commits to eventually delivering every accepted order. Transient fulfilment conditions — timeouts, rate limits, intermittent declines — keep the order in PENDING and the retry pipeline keeps working. An order only terminates as FAILED when the input was clearly customer-actionable (wrong recipient, plan unavailable, amount out of range). See Create Order for the full failure-code enum.
Status tracking
Outbound client webhooks for top-ups are not yet wired — until they ship, surface terminal transitions by polling GET /topups/orders/:id or by registering a notification email with PATCH /topups/orders/:id/notification-email. See Topup Webhooks for the planned event catalogue.
Key differences from Vouchers
| Concept | Vouchers | Topups |
|---|---|---|
| Catalogue model | product + denomination ranges | product + variant (SKU-level) |
| Customer identifier | None — pure gift card | player_id / phone_number / account_id via input_data |
| Pre-order discovery | None | POST /topups/lookup for mobile operator detection |
| Fulfilment | Sync for qty ≤ 5, async for larger | Almost always async |
| Cross-currency FX | Supported on POST /api/v1/orders | Not supported — use a matching-currency wallet |
| Outbound webhooks | order.delivered, order.partially_delivered, order.failed, order.cancelled (plus wallet.credited / wallet.debited) | Not yet wired (planned: topup.delivered, topup.failed, topup.cancelled) |
| Cancellation | Wallet refunded on CANCELLED / FAILED | Wallet refunded on FAILED / CANCELLED |