Welcome
How these docs are organised, how to navigate them, and where to look first.
The Octopus Cards API is one HTTP surface for our product verticals, backed by a shared core layer (auth, wallets, webhooks, reference data). One JWT, one base URL, the same conventions across all of it.
This page is the map.
How these docs are laid out
The top of every page has four tabs. Each tab swaps the sidebar so only the current section is visible — no scrolling past 60 unrelated items to find one endpoint.
Get Started
Day-one onboarding. Pick an environment, mint credentials, place a first order, ship to production. Designed to be read in order.
Guides
Task-shaped walkthroughs for the things integrations actually do: estimating charges, handling sync-vs-async, cross-currency, webhooks. Plus the production checklist and best-practice notes.
API Reference
Lookup surface. Every endpoint, request shape, response, and error - organised by domain (auth, products, wallets, webhooks). Each page follows the same path → request → params → response → errors structure.
Changelog
Breaking changes, new endpoints, and behavioural shifts. The first place to check when something behaves differently from the last integration round.
When to use which tab
| Intent | Tab |
|---|---|
| Brand new to Octopus Cards | Get Started, top to bottom |
| Building a specific feature (e.g. cross-currency orders, webhook handlers) | Guides — find the task, follow the walkthrough |
| Mid-integration and need an endpoint's exact shape | API Reference — pick the vertical, pick the endpoint |
| Hitting a behaviour change after an upgrade | Changelog |
| About to flip the production switch | Before You Go Live (under Guides) |
The sidebar tracks the tab. Clicking "Guides" swaps the sidebar to guides + best practices. Clicking "API Reference" swaps it to the endpoint tree. Sections are independent — moving between them via the top tabs doesn't disturb the current position inside either.
What lives in API Reference
Our product verticals plus shared endpoints. Each vertical is self-contained.
| Vertical | What it does | Delivery |
|---|---|---|
| Vouchers | Digital gift cards (Steam, Amazon, Google Play, etc.) | Synchronous — codes returned on the order response |
| Topups | Mobile recharges and gaming top-ups | Hybrid sync/async — 60s deadline, then poll or wait for webhook |
| eSIM | Data plans (LPA activation code + ICCID) | Hybrid sync/async + a second lifecycle for install/activate |
Shared across all three:
- Authentication — JWT + IP whitelist, one login flow for all three verticals.
- Wallets — the spending balance per currency; every order debits a wallet.
- Webhooks — signature verification + retry semantics shared by all verticals.
- Data — countries, currencies, categories. Cache aggressively.
Conventions that apply to every endpoint
Worth skimming before the first request:
- Base URL:
https://api.octopuscards.io - Auth:
Authorization: Bearer <jwt>; tokens issued via/auth/login. - Response shape: single resources are JSON objects; list endpoints are top-level JSON arrays.
- Pagination headers:
X-Page,X-Per-Page,X-Total-Count,X-Total-Pages,X-Has-More. - Idempotency: every order creation accepts a client-supplied
client_reference(≤ 255 printable ASCII). Sameclient_referencetwice →400 "Duplicate client_reference". - Money: every amount is paired with
currency(ISO 4217). Never assume USD. - Time: RFC 3339 / ISO 8601, UTC.
Full contract on the Conventions page.
The first hour
The four Get Started pages, in order. Short reads.