eSIM API Checklist (2026): 12 Features a Travel eSIM API Must Have — and How to Test Each One

Connecting an eSIM API to your app, travel platform or booking engine is not hard. What is hard is finding out, after launch, that the API double-charges on a timeout, cannot tell you when a customer runs out of data, or gives you no way to test failures.

This checklist covers the 12 features that matter in production, and for each one, how to test it before you sign up. We use the TripoSIM Partner API as the worked example, but you can use the same checklist to compare any provider.

1. Secure token authentication

What to look for: OAuth 2.0 client credentials: you exchange a client ID and secret for a short-lived access token. Secrets never travel with every request.

How to test: request a token, then check it expires. In the TripoSIM API, POST /auth/token returns an access token valid for 15 minutes. Make sure your code refreshes it automatically before it expires.

2. Idempotency keys (no double charges)

What to look for: an Idempotency-Key header on every order and top-up. If your request times out and you retry with the same key, the API must return the original result instead of creating a second paid eSIM.

How to test: send the same order twice with the same key and confirm you get one order. Then send the same key with a different body — a good API rejects it. TripoSIM requires the key on production orders and top-ups and returns 409 IDEMPOTENCY_KEY_REUSED if a key is reused with a different request.

3. Price quotes that lock the price

What to look for: a way to fetch a price and keep it for a short time, so your customer pays exactly what you showed them.

How to test: create a quote, wait, then order with it. TripoSIM quotes are valid for 10 minutes; an expired quote returns 409 QUOTE_EXPIRED so you can re-quote instead of charging a surprise price.

4. A clean catalog feed

What to look for: one endpoint that lists every plan with price, data, validity, coverage countries, 5G, top-up support — and for unlimited plans, the daily full-speed limit.

How to test: pull the catalog for one country and compare it with the provider's own website. The TripoSIM /catalog endpoint returns JSON or CSV, includes regional plans covering the country, and adds the fair-use fields (fup_daily_mb, fup_throttle_kbps) for unlimited plans. See [how unlimited daily limits work](/blog/unlimited-esim-daily-limit-by-country-2026).

5. Instant order and QR delivery

What to look for: the order response (or a webhook seconds later) should include the activation code in the standard LPA format, for example LPA:1$smdp.example.com$ACTIVATION_CODE, so you can show a QR code or a one-tap install link.

How to test: place a sandbox order, generate the QR from the LPA string, and scan it with a phone camera to check the format is valid.

6. Signed webhooks for every event

What to look for: push notifications for the whole eSIM life cycle, signed so attackers cannot fake them.

TripoSIM sends eight event types: order.completed, order.failed, esim.activated, esim.usage_80, esim.suspended, esim.resumed, esim.depleted and esim.expired. Each request carries an X-TripoSIM-Signature header — an HMAC-SHA256 of the timestamp and raw body using your signing secret:

<pre><code>// reject requests older than 5 minutes (replay protection) if (Math.floor(Date.now() / 1000) - parseInt(timestamp) &gt; 300) throw new Error('Webhook too old'); const expected = crypto .createHmac('sha256', signingSecret) .update(timestamp + '.' + rawBody) .digest('hex'); if (!crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected))) { throw new Error('Invalid webhook signature'); }</code></pre>

How to test: register a webhook, trigger an order, and verify the signature in your code. Then change one byte of the body and make sure your check rejects it.

7. A sandbox that simulates the whole eSIM life

What to look for: real eSIMs take days to activate and use data. A good sandbox lets you fast-forward.

How to test: in the TripoSIM sandbox, POST /sandbox/esims/{iccid}/simulate with an action of activate, usage, deplete, expire or reset. Each step fires the matching webhook, so you can test your "your data is almost gone" email in minutes instead of days.

8. Failure simulation

What to look for: a way to force errors on purpose, so you know your app handles them.

How to test: send the X-Sandbox-Simulate header with modes like insufficient_balance, price_changed, rate_limit, provider_unavailable or timeout, and check your app shows a clear message and retries only when it should.

9. Top-ups on the same eSIM

What to look for: customers who run out of data should be able to add more without installing a new eSIM.

How to test: call POST /esims/{iccid}/topup in the sandbox (with an idempotency key), then check the new data balance. Also check which plans support top-ups — the catalog should tell you.

10. Usage and status data

What to look for: an endpoint for data used, data left and expiry, so your support team and app can answer "how much data do I have left?"

How to test: call GET /esims/{iccid}/usage after a simulated usage event. TripoSIM caches usage for 5 minutes, so use webhooks (esim.usage_80, esim.depleted) for real-time alerts.

11. Suspend and resume

What to look for: a way to pause an eSIM — for example when a payment is disputed or a customer reports a lost phone — and resume it later.

How to test: suspend a sandbox eSIM, confirm the esim.suspended webhook arrives, then resume it and confirm esim.resumed.

12. Clear rate limits, error codes and a changelog

What to look for: documented limits, error codes that tell you whether to retry, and a public changelog so updates never surprise you.

How to test: read the error list and map each code to "retry" or "do not retry" in your code. TripoSIM allows 120 requests per minute per partner account (you can set lower limits on individual API keys), returns a Retry-After header on 429 responses, marks every error code as retryable or not, and publishes a changelog endpoint.

A simple launch plan

1. Day 1: get sandbox keys, authenticate, pull the catalog.
2. Day 2: place sandbox orders with idempotency keys and show QR codes.
3. Day 3: add webhooks, run the lifecycle and failure simulators.
4. Day 4: add top-ups and usage, then test on a real phone with one live eSIM.
5. Day 5: go live.

Most teams connect in under a week. Read the full [API documentation](https://docs.triposim.com) or see our step-by-step [eSIM API integration guide](/blog/esim-reseller-api-how-to-integrate-travel-esim-sales-into-your-platform).

Frequently asked questions

What should a travel eSIM API include?

At minimum: token authentication, idempotency keys, price quotes, a catalog feed, instant QR/activation codes, signed webhooks, a sandbox with lifecycle and failure simulators, top-ups, usage data, suspend/resume, and documented rate limits and error codes.

Why are idempotency keys important for an eSIM API?

Every eSIM order costs real money. If a request times out and your system retries, an idempotency key makes sure the retry returns the first result instead of buying a second eSIM.

How do I test an eSIM API without buying eSIMs?

Use the sandbox. A good sandbox simulates orders, activation, data usage, depletion and expiry — and lets you force errors — without charging your wallet.

How long does an eSIM API integration take?

With a well-documented API and a full sandbox, most teams go live in 3–5 working days.

Does the TripoSIM API support white-label delivery?

Yes. You receive the activation code and QR data, so you can deliver the eSIM inside your own app or emails under your brand. See the [API program](/api-program).

The bottom line

Price matters, but for an eSIM API the real difference shows up after launch: retries that never double-charge, webhooks you can trust, and a sandbox that lets you test everything first. Run this checklist on any provider before you commit — and [start with our sandbox](/api-program) to see how the TripoSIM Partner API scores.