Test & live modes
Every record carries a mode, derived from the authenticating credential — test and live data are fully isolated.
Every record in the system — payments, invoices, refunds, ledger entries,
webhooks — carries a mode of either TEST or LIVE.
| Mode | Behaviour |
|---|---|
TEST | Routes to the gateway sandbox. No real money moves. Excluded from financial reporting and reconciliation. |
LIVE | Routes to the production gateway. Real money moves. Included in all reporting and reconciliation. |
Mode comes from the credential, never the request
The mode of a request is derived from the credential that
authenticated it. A oi_test_… key always operates in TEST; a oi_live_… key
always in LIVE. There is no mode field you can set in a request body.
A test credential can never create, read, or affect live data, and vice versa. This isolation is enforced server-side on every query — it is not advisory.
This means you can integrate and test end to end against the sandbox with your test credentials, then switch to live purely by swapping the credential — no code path changes.
Webhooks are separated by mode too
Webhook endpoints are configured per mode: up to five test endpoints and up to five live ones, each with its own URL and its own signing secret. Nothing links them, so pointing a test endpoint at your laptop cannot disturb where live events go — and a test consumer's signing secret cannot verify live traffic.
Delivered envelopes still include a mode field, and branching on it before you fulfil
anything remains worthwhile even when the two modes reach different services: separate
endpoints make a test event reaching a fulfilment path unlikely, while checking mode
makes it impossible.