Skip to Content
OpenRoam Docs

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.

EnvironmentBase URLUse it for
Sandboxhttps://api.sandbox.openroam.comBuilding and testing your integration with test funds
Productionhttps://api.openroam.comReal orders, charged to your real wallet
Developmenthttps://api.develop.openroam.comOpenRoam'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-Scenario header.

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:

ValueOutcome
success (or no header)The item is delivered
fulfillment.rejectedThe item is rejected after payment and refunded automatically
fulfillment.pendingThe item stays pending and is delivered after about 15 minutes
fulfillment.late_successThe item stays pending and is delivered after about 2 minutes
fulfillment.late_rejectedThe 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.progress with the code CONFIRMING_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 / 10001 at headers.OpenRoam-Sandbox-Scenario (INVALID_VALUE). The header on any other route, or outside Sandbox, is 400 / 10001 (NOT_ALLOWED).

Each product guide lists the Sandbox fixtures you can search for.

Going live

  1. Get a Production account and create a Production API key.
  2. Fund your Production wallet.
  3. Register your webhook endpoint in the Production dashboard; it has its own signing secret.
  4. Switch the base URL to https://api.openroam.com and use the Production key.
  5. Remove the OpenRoam-Sandbox-Scenario header from your requests.

On this page