Environments
The Partner API hosts, and how Sandbox differs from Production.
OpenRoam runs the Partner API in separate environments. Each has its own host, its own accounts and API keys, its own catalog and its own wallet balance.
| Environment | Base URL | Use it for |
|---|---|---|
| Sandbox | https://api.sandbox.openroam.com | Building and testing your integration with test funds |
| Production | https://api.openroam.com | Real orders, charged to your real wallet |
| Development | https://api.develop.openroam.com | OpenRoam's own pre-release testing. Use it only when OpenRoam asks you to |
The base URL has no path: every route starts with /v1.
https://api.sandbox.openroam.com/v1/esims/search
https://api.openroam.com/v1/orders/{id}An API key only works on the environment that issued it. Moving from Sandbox to Production means changing the base URL and the key, and nothing else.
Sandbox
Sandbox behaves like Production: authentication, validation, pricing, idempotency, orders, refunds and webhooks follow the same contract. The differences:
- Test money. Your Sandbox wallet holds test funds. Dashboard top-ups and card payments run in test mode; no real card is charged.
- Fixture catalog. Products come from a fixed Sandbox catalog, and fulfillment uses local fixtures instead of real deliveries.
- Products. Sandbox supports eSIMs, airtime, gift cards, utility and hotels. Flights are not available in Sandbox yet.
- Chosen outcomes. You can choose how an order's fulfillment ends with the
OpenRoam-Sandbox-Scenarioheader.
Choose a fulfillment outcome
Send OpenRoam-Sandbox-Scenario on a product order route (POST /v1/esims/order, /v1/airtime/order, /v1/giftcards/order, /v1/hotels/order, /v1/utility/order) or on POST /v1/orders:
| Value | Outcome |
|---|---|
success (or no header) | The item is delivered |
fulfillment.rejected | The item is rejected after payment and refunded automatically |
fulfillment.pending | The item stays pending and is delivered after about 15 minutes |
fulfillment.late_success | The item stays pending and is delivered after about 2 minutes |
fulfillment.late_rejected | The item stays pending and is rejected after about 2 minutes |
curl -X POST https://api.sandbox.openroam.com/v1/esims/order \
-H "X-Partner-Key: $OPENROAM_API_KEY" \
-H "Idempotency-Key: $(uuidgen)" \
-H "OpenRoam-Sandbox-Scenario: fulfillment.rejected" \
-H "Content-Type: application/json" \
-d '{ "currency": "USD", "items": [{ "publicId": "esim_...", "quantity": 1 }] }'- The durations are approximate: completion is observed on the next routine check, so do not depend on the exact minute.
- An item that stays pending longer than usual shows
fulfillment.progresswith the codeCONFIRMING_OUTCOME. - The scenario is part of the idempotent request: the same key with another scenario is
409 / 12001. - An unknown, empty or repeated value is
400 / 10001atheaders.OpenRoam-Sandbox-Scenario(INVALID_VALUE). The header on any other route, or outside Sandbox, is400 / 10001(NOT_ALLOWED).
Each product guide lists the Sandbox fixtures you can search for.
Going live
- Get a Production account and create a Production API key.
- Fund your Production wallet.
- Register your webhook endpoint in the Production dashboard; it has its own signing secret.
- Switch the base URL to
https://api.openroam.comand use the Production key. - Remove the
OpenRoam-Sandbox-Scenarioheader from your requests.