eSIM
Mobile data eSIMs - plans, operators, QR/LPA delivery, activation tracking
The eSIM vertical lets clients purchase mobile data plans that activate on the customer's device via a QR code or LPA Activation Code. Plans are sourced from regional and global operators with country-specific coverage.
Unlike vouchers, eSIMs deliver an activation profile (ICCID + LPA string), not a redemption code. Unlike top-ups, there's no account or player identifier — the eSIM is bound to the customer's device after install.
For digital gift cards, see the Vouchers vertical. For gaming and mobile recharges, see the Topups vertical.
Endpoints
| Method | Path | Page |
|---|---|---|
GET | /api/v1/esim/products | Products |
GET | /api/v1/esim/products/:id | Products |
GET | /api/v1/esim/products/:id/variants | Variants |
GET | /api/v1/esim/variants/:id | Variants |
POST | /api/v1/esim/charges | Charges |
POST | /api/v1/esim/orders | Create order |
GET | /api/v1/esim/orders | Orders |
GET | /api/v1/esim/orders/:id | Orders |
PATCH | /api/v1/esim/orders/:id/notification-email | Orders |
Lifecycle & Activation
Once delivered, an eSIM has its own post-purchase lifecycle: installation, activation, validity. See Lifecycle for the ICCID/activation-code model and the one-time install security policy.
Where to start
- eSIM purchase flow — product → variants → order → render QR → poll install
- Lifecycle reference — installation, activation, refunds
Eventual delivery
Octopus Cards commits to eventually delivering every accepted order. Transient fulfilment conditions don't surface as FAILED — they keep the order in PENDING and the retry pipeline keeps working. An order only terminates as FAILED when the customer's chosen plan or input was clearly invalid, or in the rare case where automatic recovery is fully exhausted.
Status tracking
Outbound client webhooks for eSIM are not yet wired — until they ship, surface terminal transitions and install events by polling GET /esim/orders/:id. The detail endpoint refreshes installation status on every call, so a single fetch returns the freshest state. See eSIM Webhooks for the planned event catalogue.
Key differences from Vouchers and Topups
| Concept | Vouchers | Topups | eSIM |
|---|---|---|---|
| Catalogue model | product + denominations | product + variants | product + variants (1 product = 1 country/region) |
| Customer identifier | None | player_id / phone_number | None — device-bound after install |
| Delivery shape | Code + PIN or claim URL | None (top-up applies to player/MSISDN) | LPA activation code + ICCID |
| Sync vs async | Sync ≤ 5 qty, async > 5 | Almost always async | Hybrid: 60s inline deadline. Response is always 200 OK; body status is DELIVERED (in time), PENDING (deadline elapsed), or FAILED. |
| Quantity per order | 1–5,000 | 1+ | Always 1 (strictly enforced) |
| Post-delivery lifecycle | None | None | NOT_INSTALLED → ACTIVE → EXPIRED |
| Credential masking | Encrypted at rest, returned in responses | n/a | Activation code masked once is_installed: true |
| Refunds | Wallet refunded on FAILED / CANCELLED | Wallet refunded on FAILED / CANCELLED | Wallet refunded only if is_installed: false |
| Outbound webhooks | order.delivered, order.partially_delivered, order.failed, order.cancelled (plus wallet.credited / wallet.debited) | Not yet wired | Not yet wired |