API Reference
Every endpoint, request shape, response, and error - organised by domain.
The Octopus Cards API is a single HTTP surface covering our product verticals on top of shared Authentication, Wallets, Webhooks, and reference Data.
If you're new here, start with the Docs tab - getting started, guides, and best practices. This reference is the lookup surface once you know what you're building.
Start here
Conventions
Base URL, response envelope, pagination headers, idempotency, currency, timestamps.
Authentication
Login, refresh tokens, logout - the JWT + IP-whitelist contract.
Products
Vouchers
Digital gift cards - synchronous code delivery for Steam, Amazon, Google Play, etc.
Topups
Mobile recharges and gaming top-ups - hybrid sync/async with player-ID lookups.
eSIM
Data plans delivered as LPA activation codes and QR - install-then-activate lifecycle.
Shared
Wallets
Balances, currencies, transactions - the spending side of every order.
Webhooks
Signature verification, retry semantics, idempotent receipt patterns.
Reference Data
Countries, currencies, categories, subcategories - cache these aggressively.
Conventions at a glance
| Topic | Default |
|---|---|
| Base URL | https://api.octopuscards.io |
| Auth | Authorization: Bearer <jwt> + IP whitelist on the issuing client |
| Response envelope | Raw entity for single resources; top-level JSON arrays for lists. (JWT API only — cookie-portal wraps in { "success": true, "data": ... }.) |
| Pagination | X-Page, X-Per-Page, X-Total-Count, X-Total-Pages, X-Has-More |
| Idempotency | Client-supplied client_reference (≤ 255 printable ASCII) on order creation. Duplicate → 400 "Duplicate client_reference". |
| Money | Amounts always paired with currency (ISO 4217); never assume USD |
| Time | RFC 3339 / ISO 8601, UTC |
See Conventions for the full contract.