Environments
Sandbox vs production - different hosts, different credentials, different data
The Octopus Cards API runs in two strictly separated environments. Sandbox is for development and testing; production is for real orders against real money. They share the same API surface, but nothing crosses between them - credentials, wallets, orders, webhooks, everything is isolated.
Base URLs
| Environment | Base URL | Purpose |
|---|---|---|
| Sandbox | https://sandbox-api.octopuscards.io | Development, testing, CI |
| Production | https://api.octopuscards.io | Live orders with real settlement |
Every code example in this documentation uses https://api.octopuscards.io as a placeholder. Substitute it for whichever environment you're targeting.
What's the same
- Endpoint shapes - every request/response in the API Reference works identically in both environments.
- Authentication - same
POST /auth/loginflow, same JWT lifetime, same refresh semantics. - Error taxonomy - same error codes, same HTTP statuses, same response shape.
- Webhook contract - same signing scheme, same headers, same payload structure.
What's different
| Aspect | Sandbox | Production |
|---|---|---|
| Credentials | Issued with your sandbox account | Issued after KYC/KYB + funding |
| Wallet balances | Pre-filled with test funds you can top up on request | Real money you wire in |
| Voucher codes | Mock codes - not redeemable on the real merchant | Real codes redeemable at the merchant |
| Product catalog | Mirrors production, but some products may be simulated | Full live catalog with real inventory |
| FX rates | Representative rates, updated daily | Live market rates, updated through the day |
| Webhook deliveries | Fire to your configured sandbox URL | Fire to your configured production URL |
| Rate limits | More permissive (intended for stress-testing) | Production limits - see Rate Limits |
What sandbox does not simulate
Plan for these in your tests - they only ever happen in production:
- Transient fulfilment failures - sandbox orders always succeed if the request is valid.
- Merchant-specific denomination restrictions that only apply to real vouchers.
- Production-specific fraud signals (IP reputation, velocity checks, etc.).
- Real FX rate volatility - test with multiple currencies, but don't rely on specific spreads.
Use Handling Errors as your test matrix. Every documented error is reachable in sandbox - just craft the request that triggers it.
Switching from sandbox to production
The only code change is the host. Everything else - request shapes, header names, response fields - is identical.
# Development
HOST=https://sandbox-api.octopuscards.io
# Production
HOST=https://api.octopuscards.io
curl $HOST/api/v1/products -H "Authorization: Bearer <token>"In practice, wire the host through an environment variable from day one. It's the one knob you should never hardcode.
What you'll need for production
Before your production credentials are activated, your account manager will require:
- KYC/KYB documentation - identity verification for your business.
- Initial wallet funding - by wire transfer or approved payment rail.
- A webhook URL - publicly accessible HTTPS endpoint for order and product events.
- (Optional) IP allowlist - CIDR ranges from which you'll call the API.
Full detail: Moving to Production.
Next
- Create your API key - get credentials for sandbox.
- Your first order - end-to-end walkthrough.