eSIM API integration: how to sell eSIMs in your own app
What does an eSIM API integration involve?
An eSIM API integration lets your own app or website sell travel data plans without holding any stock. Your server lists the plans available to your account, buys one from a prepaid balance when a customer pays you, and hands the customer a QR code or install details. Around that core sit usage, top-ups, webhooks, refunds and retries, and that is where most of the work is.
We built the Partner eSIM API and the eSIM Partner Portal that issues its keys, so this guide uses them as the worked example. It describes concepts rather than endpoints: whichever provider you choose, you will need an answer for each part below.
What are the parts of an eSIM integration?
Every eSIM integration breaks down into the same pieces:
- Authentication and API keys.
- A catalogue of plans with their coverage, data and validity.
- Pricing: your cost, your customer's price and the margin between them.
- Ordering and paying from a prepaid balance.
- Delivery: the QR code, the activation details and an install link.
- Usage and top-ups.
- Webhooks for status changes.
- Failures, refunds and retries that never charge twice.
- Testing without spending money.
How does authentication work, and where do the keys live?
In the Partner eSIM API a request carries two headers: a public merchant ID and a secret key. One call confirms the keys and returns your balance and how many packages you can sell: a good first request and a useful health check.
Keys are issued from the partner portal by a manager of an approved partner account; there is no self-serve sign-up, and API access has to be switched on for the account. The rule that matters most is where the secret key lives: on your server, never inside a mobile app or a web page.
How should you handle the catalogue of plans and coverage?
The catalogue is the list of plans assigned to your account. Ours supports paging, search and country filters, shows the coverage of each plan, and can include the carrier networks a plan uses. Travellers compare plans on data, validity and coverage, so your product pages need all three.
Store the catalogue in your own database against each plan's ID and refresh it on a schedule, because plans are added, withdrawn and repriced. Our API sends a webhook when the catalogue changes, and the portal shows upcoming price changes before they land, so you can adjust your prices in time.
Where does your margin come from?
In the prepaid model the wallet is debited at your cost for each order, and what you charge your customer is your own business. The difference is your margin. With an API integration you take the customer's payment yourself, through your own payment provider, so your retail price lives in your system.
Partners who also use the portal can switch packages on or off, set retail prices inline or apply a margin in bulk, and those prices appear on the customer's receipt. Either way, work out the margin after card fees and refunds. Our eSIM reseller profit calculator does that sum for a month of sales.
How does an order get paid for from a prepaid balance?
A manager tops up a euro wallet by card or by bank transfer; bank transfers are credited by staff against the company's reference. Each purchase draws on that balance. A well-built platform reserves the cost before asking the supplier for the eSIM and releases it if the eSIM isn't issued, so two orders can't spend the same money.
You can buy one eSIM or several in one request. Units are ordered one at a time, and if a later unit fails the order is reported as partly fulfilled and you pay only for the eSIMs delivered. Your code has to handle that result: deliver what arrived, and refund or retry the rest on your side.
The API sends a low-balance webhook and the portal shows an alert. Decide in advance what checkout does when the wallet runs low: pausing sales beats taking a customer's money for an eSIM you can't buy.
How is the eSIM delivered to the customer?
Once an order succeeds, read it back for the QR code, the activation details and its install state, and show all of them. A customer buying on their phone can't scan its own screen, so they need the manual codes or a one-tap install link on phones that support one. Our own MobiSIM store offers all three.
Not every eSIM is ready at once. Some plans are issued a moment after the purchase, and a few need the customer to verify their identity first. Give that state its own screen, such as 'your eSIM is being prepared', then read the order again or wait for the webhook. Never show an error for an order that simply isn't finished.
Check how the customer gets the eSIM. In our partner portal an order emails the customer a receipt with the QR code and install steps, carrying the logo, wording, colour and sender address you set there; if your app sends its own confirmation instead, include the same activation details and install steps. If the customer loses them, the API can resend the confirmation.
How do usage and top-ups work?
After installation the customer wants to know how much data is left and how many days. Reading the order returns live usage and install state, and the eSIM lifecycle webhooks tell you when the status changes. Be honest about freshness: on some plans usage lags by hours, and on a few it isn't reported at all, so show when the figure was last updated.
A top-up adds data to an eSIM the customer already has, without a new QR code, where the plan allows it. In your code, treat a top-up like a purchase: it spends wallet money, so it needs the same retry discipline.
Which webhooks should you handle, and how?
The Partner eSIM API sends HMAC-signed events for orders, top-ups, refunds, low balance, the eSIM lifecycle and catalogue changes. In the portal you point the webhook at your server, send a test event and read a delivery log with one-click resend. Four rules make a handler safe:
- Verify the signature over the timestamp and the raw body with a constant-time comparison, and reject old timestamps. We use a five-minute tolerance.
- Answer quickly with a success status and do the work afterwards, so a slow handler isn't mistaken for a failed delivery.
- De-duplicate on the event ID. Delivery is at least once and our retries continue for about two days, so an event can arrive twice.
- Expect events out of order. Treat each webhook as a prompt to read the order again, and let the order be the source of truth.
What happens when an order fails or needs a refund?
Design for these cases from the first day:
- The purchase is refused, for example because the plan was withdrawn or the balance is too low. If you have already taken the customer's payment, refund it straight away.
- The eSIM is issued late or needs an identity check. That is a pending order, not a failure.
- The request times out and you don't know whether the order exists. That is what the client reference below is for. On the platform side, our MobiSIM API holds an order whose outcome is unclear and reconciles it with a read-only lookup instead of retrying blindly, so nothing is bought twice.
- The customer wants a refund. Rules differ between plans: some are refundable, some aren't, and some carry a fee. Find out which before launch, decide what you will cover from your margin, and listen for the refund webhook so your records match the wallet ledger.
How do you make sure a retry never charges twice?
Send a client reference with every purchase. Generate it before the first attempt, save it with your own order record, and reuse it on every retry. If the first request did go through, repeating the purchase with the same reference returns the original order instead of creating a second one.
The common bug is generating a fresh reference inside the retry loop, which turns every retry into a new order. The same thinking applies to your own checkout, where a customer taps Pay twice. We cover the server side in building an order API that never charges twice.
How do you test an eSIM integration before going live?
Build the whole flow against test mode first. A test purchase returns the real response shape with a placeholder eSIM; nothing is bought and the wallet is not charged, so the code you test is the code you ship. Then test the unhappy paths on purpose:
- Drop the connection mid-purchase and retry with the same client reference.
- Deliver the same webhook twice, and two webhooks in the wrong order.
- Send a webhook with a bad signature and one with an old timestamp, and check both are rejected.
- Run the low-balance path and see what your checkout does.
A step-by-step eSIM API integration plan
This is the order we would build it in:
- Get keys. A manager on the approved partner account generates a merchant ID and key pair in the portal. Store the key as a server secret.
- Confirm the account with the account check: keys, balance and package count.
- Import the catalogue, store plans by ID with coverage, data and validity, and set your retail prices.
- Build checkout: take the customer's payment, create your order record with a client reference, then buy.
- Build delivery: QR code, manual codes, an install link, and a pending state for late or ID-checked plans.
- Add webhooks: verify signatures, de-duplicate on the event ID, read the order again on every event.
- Add usage and top-ups, with a last-updated time on the usage figure.
- Write down what happens on partial orders, refusals, refunds and low balance.
- Rehearse in test mode, then go live with a few real orders and a modest balance, and follow the API's dated changelog.
Should you build the integration yourself?
If you have developers, the API, its docs site and test mode are there so you can do it yourself. If you don't, or the eSIM sale is one feature inside a bigger product, that is the kind of custom software we take on: we built the API and the portal, and our own MobiSIM store and app sell eSIMs to travellers. Still deciding whether to resell at all? Start with how to start an eSIM reselling business.
Can I test an eSIM API without paying for eSIMs?
Yes, if the provider has a test mode. In the Partner eSIM API a test purchase returns the same response shape with a placeholder eSIM, buys nothing and doesn't charge the wallet.
What happens if an eSIM purchase request times out?
Retry with the same client reference you sent the first time. If the original request went through, you get that order back instead of a second one. Never generate a new reference for a retry.
Can customers add data to an eSIM they already installed?
Yes, where the plan allows it. A top-up adds data to the existing eSIM without a new QR code, through the API or in the partner portal.
How do I get access to the Partner eSIM API?
A company applies for a partner account, and staff review it before switching it on. Once API access is enabled, a manager generates the keys in the portal. If you want a walkthrough or help with the integration, tell us about your project.