Going live checklist

Work through this list in the sandbox before you switch to your live key. The test plan gives you a check for most of these.

Your integration

• The API is called from your server only. No key is inside a mobile app or a web page.
• Keys are kept in environment variables or a secrets manager.
• Every POST sends an Idempotency-Key taken from your own booking or order number.
• A timeout, a 429 or a 5xx response is retried with the same key.
• Your HTTP client waits at least 30 seconds for POST /v1/orders before it gives up.
• A 402 response stops the sale cleanly and alerts your team.
• An order that comes back as processing is handled, by webhook or by fetching it again.
• An order that ends as failed or partially_completed is handled. On order.completed you read status and count esims.
• A new attempt after a failed order or top-up uses a new Idempotency-Key.
• A top-up response is checked for status failed before the customer is told the data was added.
• Your code uses the error code, not the message.
• The catalogue is cached and refreshed at least once a day. A stored package id that answers package_not_found is handled.
• You read data_mb and validity_days from the package, not from its name.
• You stay under 120 requests a minute, and 30 POST requests a minute, for each key.

Delivery

• The customer gets the one-tap link from install_links on the phone and the QR code from qr_code_url elsewhere.
• Manual entry details from activation are available as a fallback.
• Your confirmation email or screen tells the customer to install before travelling and to turn on data roaming.
• The customer can find the eSIM again later in your app or by email.

Webhooks

• Your webhook address checks the X-Esimify-Signature header against the raw body.
• It rejects a request whose timestamp is more than 5 minutes old.
• It answers 2xx within 10 seconds and does slow work afterwards.
• Repeated events are ignored using the event id.
• Events are put in order with sequence, not by arrival time or created.
• A scheduled job reads GET /v1/events and catches anything you missed.
• You keep at least one live endpoint enabled. Live eSIM events are produced only while you have one.

Operations

• A low-balance threshold is set in the portal under Settings, and someone on your team is alerted on a balance.low event. The sandbox sends it too, when a test order takes the virtual balance below the same threshold, so you can test your handler there.
• Your support team can look up an order by your own reference, using customer_ref.
• You log the X-Request-Id of every response.
• Someone watches the delivery log and the request log in the portal during the first days.

Switching over

1. Check in the Business portal, under Developers, that live keys are available for your account.
2. Create your live key. You are asked for your portal password. Add your servers’ addresses to its IP allowlist.
3. Add your live webhook address and put its signing secret into production. A test-mode address does not receive live events.
4. Make sure your live balance covers your first orders. Add funds in the Business portal under Wallet.
5. Replace the test key with the live key in production.
6. Place one real order for yourself and install it on a phone.