Your first order
Pick a product type, get a working end-to-end order in under 10 minutes
The Octopus Cards API covers a handful of product flows. Each shares the same authentication and conventions, but differs in the call sequence and the delivery shape (synchronous codes vs polled fulfilment vs LPA activation codes).
Run any of them against sandbox — every order produces a mock payload that is safe to inspect but not actually redeemable.
Prerequisites
- A sandbox API key and secret — see Create your API key.
- A wallet funded in your default currency on sandbox (sandbox wallets are pre-credited).
Set up the environment:
export HOST="https://api.octopuscards.io"
export API_KEY="your_api_key"
export API_SECRET="your_api_secret"Authenticate
This step is the same for every product flow. Run it once, export TOKEN, then jump to the flow that matches the integration.
curl -s -X POST "$HOST/auth/login" \
-H "Content-Type: application/json" \
-d "{\"username\":\"$API_KEY\",\"password\":\"$API_SECRET\"}"Extract access_token from the response and export it:
export TOKEN="eyJhbGciOiJIUzI1NiIs..."The token is valid for 1 hour. For short-lived scripts that is enough; for long-running services, rotate with the refresh endpoint.
Pick a flow
Voucher
Digital gift cards (Amazon, Steam, Razer, etc.). Synchronous: codes return in the order response.
Gaming Topup
In-game currency or item packs against a player ID (PUBG UC, Free Fire diamonds, etc.). Hybrid sync/async.
Mobile Recharge
Prepaid airtime and data plans for a mobile number. Includes the lookup step that detects the operator from an MSISDN.
eSIM
Data plans delivered as an LPA activation code + ICCID. Hybrid sync/async with a 60s inline deadline.
What the flows share
| Concept | Same across every flow |
|---|---|
| Auth | POST /auth/login returns a 1h access token + 7d refresh token. |
client_reference | Optional client-supplied dedup + lookup key on every order (≤ 255 printable ASCII). Duplicate (client_id, client_reference) → 400 "Duplicate client_reference". |
| Wallet debit | Synchronous; the wallet is charged before fulfilment is attempted. |
| Failure refunds | Terminal FAILED orders auto-refund the wallet. |
is_user_fixable | Boolean on failures — when true, surface the message and let the customer retry. |
| Currency | Every amount is paired with currency (ISO 4217). Optional wallet_id enables cross-currency. |
What differs is the delivery shape for each vertical:
- Vouchers return codes inline on the order response.
- Topups stream status from
PENDING→ terminal over seconds to minutes.
- eSIM returns an LPA activation string + ICCID after a hybrid sync/async deadline.