DEV Community: Daniel

When the eSIM Doesn't Connect: Designing the Activation-Failure Support Path in Your App

Daniel — Sun, 01 Nov 2026 08:10:39 +0000

Most eSIM integrations are designed around the happy path: the user picks a plan, pays, scans a QR code or taps "Install", and lands abroad with data. Then the first support ticket arrives: "I installed the eSIM but it doesn't work." If your app has nothing to say at that moment, the user blames your brand, not the connectivity supplier behind it.
This post is about designing that failure path on purpose: what you can check before purchase, which signals tell you where a profile actually is, the usual causes of "installed but no data", what to show in-app, what to log, and when to refund or re-issue automatically.

1. Prevent the cheapest failures before checkout

A surprising share of activation problems are really compatibility problems that were sold anyway. Before the user pays:

Check eSIM support on the device. In a native app you have better options than on the web. Where you can read the device's EID (the eUICC identifier), store it with the order: it proves the device has an eUICC and helps support later. On the web you mostly can't detect eSIM support reliably, so fall back to a device allow-list plus a clear "How to check if my phone supports eSIM" step.- Warn about carrier locks. A locked phone may have an eUICC and still refuse a third-party profile. You usually can't detect this, so say it plainly in the checkout copy.- Set expectations on timing. Tell the user to install before travelling (on Wi-Fi), and to switch data to the eSIM line only on arrival.## 2. Track profile state from real signals, not from "the user clicked Install" Your backend sees an order. The SM-DP+ (the server that prepares and delivers the eSIM profile) sees a download. The phone sees a profile that is installed, enabled or deleted. These are different states, and support needs all of them. Under the GSMA consumer eSIM spec, the device sends notifications back to the SM-DP+ for events like install, enable, disable and delete. Whether you get those events depends on your connectivity supplier's API: many expose them as webhooks or as a profile-status endpoint. Model them explicitly:
ORDERED - paid, profile reserved, activation code issued- DOWNLOADED / INSTALLED - the device fetched and installed the profile- ENABLED - the profile is active on the device- ATTACHED / IN_USE - the network has seen the line, or data usage has started (from usage records, if your supplier exposes them)- DELETED - removed from the device (important: many profiles can't be reinstalled after deletion)The gap that generates tickets is between INSTALLED and IN_USE. If a profile was installed hours ago, the user's trip start date has passed, and no usage has appeared, that's your trigger to reach out proactively instead of waiting for an angry email. ## 3. Know the usual causes of "installed but no data" In practice, most cases fall into a short list, and almost all are device settings rather than network faults:
Data roaming is off on the eSIM line. Travel eSIMs usually connect as roaming, so this is the number-one cause.- The wrong line is selected for mobile data. The profile is enabled, but the phone still uses the home SIM for data.- APN not set or wrong. Most profiles set it automatically; some devices or plans need it entered manually.- Network selection. Automatic selection picked a network the plan doesn't support; manual selection fixes it.- Not yet in the destination, or the plan's validity window hasn't started.- Profile deleted while "troubleshooting", which often turns a settings issue into a re-issue.Only after these does it make sense to escalate a genuine network or provisioning problem. ## 4. Put the troubleshooting inside the app A help-center article is a fallback. A better pattern is a guided checklist inside the order screen, ordered by likelihood and specific to the platform:
"Is data roaming turned on for this eSIM?" with the exact settings path for iOS and Android- "Is this eSIM selected for mobile data?"- "Are you in [destination] now?" with the plan's validity dates- A big "Don't delete the eSIM" warning, because that step is often irreversible- Only then: "Still not working? Contact support", with the order context pre-attachedBanks adding travel eSIM inside their apps follow the same idea: BBVA's announcement for its Italian app lists usage tracking, usage alerts, buying more data and contacting technical support side by side in the app (BBVA's announcement). Support isn't a separate channel; it's part of the product screen. ## 5. Log what support will actually need When a ticket reaches a human, they should not have to ask the user for screenshots of settings. Attach to every order:
ICCID of the profile and EID of the device (if captured)- Device model and OS version- Timestamps for order, profile download, install/enable notifications, and first usage- Last network or country seen, if your supplier exposes it- Which checklist steps the user already confirmed in-appTreat ICCID and EID as personal data: restrict access, and don't send them to analytics tools that don't need them. ## 6. Decide refund and re-issue rules before launch Write the rules down as code, not as agent judgment:
Never downloaded and the trip hasn't started: refund automatically on request.- Downloaded, then deleted, no usage: re-issue a new profile if your supplier allows it; otherwise refund per policy.- Installed, no usage, checklist completed, user in destination: escalate to the supplier with the logged context, and offer a fallback (re-issue or refund) within a defined time.- Usage started: it's a network or plan question, not an activation one; route it differently.Clear rules keep refunds predictable for finance and fast for the user, which matters most when they're standing in an airport. ## 7. Agree who owns tier 1 and tier 2 If you're a bank, travel app or MVNO reselling someone else's connectivity, settle this in the contract:
Tier 1 (your brand): in-app checklist, settings guidance, refund and re-issue decisions within policy.- Tier 2 (connectivity supplier): profile state, provisioning faults, network attach problems, coverage issues.- The handoff: which fields you send (ICCID, timestamps, country), the expected response time, and how the answer flows back to the user.Without this, the user gets bounced between "contact your eSIM provider" and "contact the app you bought it from". ## Wrapping up Activation support is where an embedded eSIM either earns trust or loses it. The checklist is short: check compatibility before payment, track real profile state, guide the user through the common fixes in-app, log the identifiers support needs, automate refund and re-issue rules, and draw a clear line between your support and your supplier's. If you're adding branded eSIM to a travel, mobility or fintech product and want the provisioning, portal and support layer handled for you, that's what we're building at One-eSIM: One-eSIM for travel, mobility and fintech. Disclosure: I work on One-eSIM (1-esim.com), a B2B eSIM platform.

One Install, Many Trips: Designing Reusable eSIM Profiles, Top-ups and Unused-Data Refunds

Daniel — Sun, 25 Oct 2026 08:15:20 +0000

The first eSIM purchase in your app is the easy part. The interesting engineering starts on the second trip, when the customer already has a profile installed and just wants more data. In the last few weeks several financial apps have shipped travel eSIM with exactly this in mind: Wise in New Zealand announced plans with automatic refunds for unused data, and PostFinance in Switzerland and Erste Bank's George app in Austria both describe an eSIM you install once and reuse across trips. Whatever provider sits behind each of them, the product pattern is the same: one install, many trips.
This article walks through the data model and event flow behind that pattern: reusable profiles, top-ups driven by usage, refunds for unused data, and several lines under one account. It assumes you're working with an eSIM provider's API and don't run any network infrastructure yourself.

1. Separate the profile from the bundle

The most common early mistake is modelling "an eSIM" as one purchase. It isn't. There are two different things with different lifecycles:

Profile: the installed SIM on the customer's device, identified by its ICCID. It's installed once and can live for months or years.- Bundle (or package, or plan): a quantity of data for a region and a validity period, attached to a profile. A customer can buy many over time.A minimal schema looks like this:
accounts: your customer, the person who pays.- lines: one row per profile, with account_id, iccid, a display name ("Dana's phone"), install status and the provider's profile reference.- bundles: line_id, product code, region, data allowance in bytes, validity in days, purchased_at, activated_at, expires_at, status, and the provider's order reference.- usage_snapshots: bundle_id, bytes used, observed_at, source (webhook or poll).- ledger_entries: every charge, refund and credit, linked to a bundle.With this split, "buy more data" becomes "create a bundle on an existing line" and never triggers a new QR code. Before showing a second QR code to anyone, check whether the customer already has an installed line that supports the destination. ## 2. Decide when a bundle counts as started Providers differ on when the validity clock starts. Common options are: at purchase, at first network attach in the covered country, or at first data usage. Your app needs to know which applies to each product, because it drives three things: what you show the customer ("valid 7 days from first use"), when you can safely sell another bundle on the same line, and whether a refund is still possible. Store the rule per product, not as a global constant. Then compute bundle state from events rather than flags:
purchased: paid, not yet active.- active: provider reports activation or first usage.- depleted: usage reached the allowance.- expired: validity ended with data left over.- refunded or partially_refunded: money went back.If a line holds several bundles, also decide on ordering. Most providers consume the oldest active bundle first, but confirm it, because it changes how you display "data remaining". ## 3. Drive top-ups from usage events Top-ups convert best when they're offered at the moment of need. That means reacting to usage, not to a calendar. Two sources are typical:
Webhooks for thresholds (for example 80% and 100% used) and for activation and expiry.- Polling the usage endpoint as a fallback, because webhooks get delayed or dropped.Treat every incoming event as a snapshot, not a delta. Write it to usage_snapshots, make the handler idempotent on the provider's event id, and recompute the bundle state from the latest snapshot. Usage counters from networks can lag by minutes to hours, so never assume the number is real time; say "about" in the UI. Then define your triggers in one place:
At 80% used with more than a day of validity left, send an in-app notification with a one-tap top-up for the same region.- At 100% used, show the top-up as the first thing on the eSIM screen, using the stored payment method.- If a bundle expires with the customer still in the country (you can infer this from recent usage), offer a short extension rather than a full new plan.Keep the rule engine boring: a table of conditions and actions, evaluated after each state recompute, with a cooldown per line so nobody gets three notifications in an hour. ## 4. Refunds for unused data need reconciliation A refund-for-unused-data promise sounds simple and is mostly accounting. Before you offer one, answer these questions with your provider and your finance team:
What is "unused"? A bundle never activated is easy. A bundle that expired at 40% used is a policy choice: pro-rata, fixed tiers, or nothing.- Which number is authoritative? Your snapshots may lag. Refund on the provider's final usage figure after expiry, not on the last webhook you happened to receive.- When is it final? Wait a settlement window after expires_at (ask the provider how late usage records can arrive) before calculating.- What does it cost you? Check whether the provider credits you for unused data. If not, every refund comes out of your margin, so price accordingly.Implement it as a scheduled job that picks up expired bundles past the settlement window, fetches final usage, calculates the amount under the product's policy, and writes a ledger_entries row before calling the payment provider. The ledger row is the source of truth for support and reporting; the payment call can be retried. ## 5. Several lines under one account Families and small teams travel together, and one payer with several phones is a natural extension. The accounts/lines split already supports it. What you add is:
A way to send an install link to another person's device without exposing the payer's login.- Per-line notifications routed to the line holder, with billing notifications to the payer.- Optional spend caps per line, enforced in your top-up flow before you call the provider.Be explicit in the UI about which line a top-up is for. "Top up Dana's phone" prevents most of the support tickets this feature can create. ## 6. Plan for the support path When a reused profile doesn't connect on the second trip, the customer contacts you, not the network. Give your support team a single view per line: profile status, every bundle with its state and usage history, the last events received, and the ledger. Most tickets ("I bought data but it doesn't work") are answered by checking whether the new bundle is active, whether data roaming is on for that line, and whether the right line is selected for mobile data. ## Checklist
Profiles and bundles are separate entities.- Validity rules are stored per product.- Bundle state is computed from idempotent usage snapshots.- Top-up triggers live in one rule table with cooldowns.- Refunds run after a settlement window, from final provider usage, through a ledger.- Multi-line accounts route notifications and spend caps per line.## Where One-eSIM fits Disclosure: I work on One-eSIM, a B2B platform that handles the telecom side of this (connectivity supply, provisioning, top-ups, lifecycle events, support tooling and analytics) through an API or a white-label storefront. If you're adding reusable travel eSIM to a fintech, travel or mobility app, the travel, mobility and fintech page explains how that works. Happy to answer questions in the comments, including if you're building it all yourself.

eSIM Glossary for Developers: SM-DP+, LPA, ICCID, EID and Activation Codes Explained

Daniel — Sun, 18 Oct 2026 07:16:00 +0000

If you're adding eSIM to a travel, banking or mobility app, the first week usually goes to vocabulary. Provider docs mention SM-DP+, LPA, ICCID, EID, matching IDs and profile states as if everyone already knows them. This glossary explains each term in plain language and, more importantly, what it means for your integration: what to store, what to show the customer, and where things tend to break.

The hardware and the "SIM" itself

eUICC

The embedded chip inside the phone that replaces the plastic SIM. Unlike a physical SIM, it can hold several operator profiles at once and download new ones over the air.

For your integration: you never talk to the eUICC directly. The phone's operating system does. Your job is to deliver a profile in a form the OS can install.

Profile

The downloadable "SIM": the operator credentials, network settings and identifiers that used to live on a plastic card. When a customer "buys an eSIM", they're really getting a profile installed on their eUICC.

For your integration: one profile can usually carry many data bundles over time. Banks like N26 and Santander advertise exactly this in their apps: install once, then buy more data for each trip. Design your data model so a customer has one profile and many bundles, not one eSIM per purchase.

EID

The eUICC Identifier, a 32-digit number that identifies the chip itself. Users can find it in their phone's settings. It belongs to the device, not to a plan.

For your integration: you only need the EID if your provider supports device-bound delivery (pushing a profile to a known device) or if support needs to confirm which phone a profile was sent to. Treat it as personal data.

ICCID

The Integrated Circuit Card Identifier, usually 19 or 20 digits and starting with 89. It identifies the profile, the same way the number printed on a plastic SIM did.

For your integration: this is the most important ID you'll store. Link the ICCID to your customer, order and booking. Almost every provider call after purchase (usage, top-up, status, refund) is keyed on it, and it's the first thing a support agent needs.

IMSI and MSISDN

The IMSI is the subscriber identity the mobile network uses internally. The MSISDN is the phone number. Most travel eSIMs are data-only and have no usable phone number, which surprises customers who expect to receive SMS on them.

For your integration: say "data only" clearly at checkout if that's what you sell. It prevents a lot of tickets.

The servers behind provisioning

SM-DP+

Subscription Manager Data Preparation (the "+" marks the consumer version). This is the server that prepares, stores and securely delivers profiles to devices. When an order is placed, a profile is reserved on an SM-DP+ and waits there until the phone downloads it.

For your integration: you rarely run one yourself. Your connectivity provider does. What you get back from an order is the SM-DP+ address and a matching ID, usually combined into an activation code.

SM-DS

Subscription Manager Discovery Server. It lets a phone find a profile waiting for it without the user entering a code, as long as the profile was linked to that device's EID.

For your integration: it's useful for "it just appears" experiences, but support for it varies by provider and device. Most travel flows still rely on activation codes.

GSMA SGP.22 and SGP.32

The GSMA specifications behind all of this. SGP.22 covers consumer devices like phones, tablets and watches. SGP.32 covers IoT devices that have no screen or user. If you sell to travellers, SGP.22 is the one that matters.

On the device

LPA

The Local Profile Assistant: the software on the phone that downloads, installs, enables, disables and deletes profiles. On iPhone and most Android phones, it's built into the system settings ("Add eSIM", "Add mobile plan").

For your integration: the LPA is why your install instructions must be specific to each platform. The menu names, the order of steps and the options for installing from a link or from inside an app differ between iOS and Android, and between OS versions. Check current platform documentation instead of hard-coding screenshots that will go out of date.

Activation code

The string that tells the LPA where to fetch the profile. It usually looks like LPA:1$smdp.example.com$ABCD-1234-EFGH, which breaks down as the format version, the SM-DP+ address, and the matching ID. A QR code is just this string encoded as an image.

For your integration: show both the QR code and the copyable text, plus a one-tap install link where the platform supports it. A customer who opens your email on the same phone they need to scan with can't scan a QR code.

Matching ID

The part of the activation code that identifies one specific order on the SM-DP+. It's effectively a one-time voucher.

For your integration: treat it like a secret. Anyone with the full code can try to download the profile first.

Confirmation code

An optional extra PIN some providers require on top of the activation code. If yours does, deliver it through a separate channel or at least a separate step, and tell the user they'll be asked for it.

Lifecycle terms

Profile states

Providers describe the same journey with slightly different names, but it usually runs: released (ready on the SM-DP+), downloaded, installed, enabled, and later disabled or deleted. Bundles have their own states, such as not started, active, depleted and expired.

For your integration: subscribe to state-change webhooks if your provider offers them, and store the latest state per ICCID. "Was it ever installed?" is the first question in almost every support case, and you should be able to answer it without asking the customer.

Re-download and deletion

With many providers, a profile can be downloaded only once. If the customer deletes it from their phone, the profile may be gone, and a new one has to be issued. Policies vary, so check yours.

For your integration: warn customers inside the app before they remove an eSIM, and build a clear "reissue" path for support agents.

Activation policy

Many travel bundles start counting validity only when the phone first connects to a network in the destination, not at purchase or install. Starling's and N26's public descriptions of their eSIM plans both mention plans activating automatically on arrival.

For your integration: encourage installing before the trip (while the customer has Wi-Fi) and make it clear that the clock starts on arrival. That single message removes a common source of refund requests.

Data roaming and the data line

Because a travel profile's home network is usually not in the destination country, the phone treats it as roaming. If data roaming is off on that line, or the phone is still using the home SIM for data, nothing works.

For your integration: most "it's not connecting" tickets come down to these two settings. Put a three-step check in the app (correct line selected for data, data roaming on for that line, restart if needed) before the "contact support" button.

Top-up

Adding a new bundle to an existing profile. No new QR code, no reinstall.

For your integration: top-ups are where repeat revenue comes from. Trigger the offer from a low-data webhook or usage check, and make it one tap using the customer's saved payment method.

A minimal data model

If you only take one thing from this glossary, store these fields per customer:

ICCID, with the order and booking it came from
Profile state and the time it last changed
Bundles linked to the ICCID, each with its country or region, size, validity, state and remaining data
The activation code (stored securely) and when it was delivered
EID, only if your provider uses it

With that in place, support, top-ups and reporting (activation rate, attach rate, revenue per market) all become queries rather than investigations.

Where One-eSIM fits

Disclosure: I work on One-eSIM, a B2B platform that handles the telecom side of this (connectivity supply, provisioning, lifecycle, top-ups, support tooling and analytics) through a white-label storefront or an API, so your team can focus on the customer experience. If you're building eSIM into a travel, mobility or fintech product, the travel, mobility and fintech page explains how that works. I'm happy to answer questions in the comments, including if you're building it all yourself.

How to Embed eSIM Data Into a Travel or Fintech App (Without Becoming a Telco)

Daniel — Thu, 15 Oct 2026 17:33:43 +0000

Travellers already open your app before a trip to book a flight, pay for a hotel, or check a loyalty balance. Mobile data abroad is the one thing they still go somewhere else for. That makes it an obvious product to add, and more travel, mobility and fintech teams are trying it.
The catch is that an eSIM looks simple from the outside. It's a QR code. Underneath, it's a telecom product with supply, provisioning, lifecycle and support problems. This post walks through what it actually takes to embed eSIM data into an existing app, and the build choices you have.

What happens when a customer buys an eSIM

From the customer's side, buying an eSIM takes about thirty seconds. Behind that, a few systems have to work together:

Connectivity supply. Someone has to own data capacity in the destination country, through an operator or a roaming agreement, at a price that leaves you a margin.- Provisioning. An eSIM profile is generated and assigned on an SM-DP+ server (the system that securely delivers eSIM profiles to devices), then delivered as a QR code or an activation link.- Activation. The customer installs the profile, switches data to it, and turns on roaming. This step causes most support tickets.- Lifecycle. Usage tracking, low-data alerts, top-ups, expiry, and refunds.- Support. "It's not connecting" at 2 a.m. in another time zone.If you only build the checkout, you still own every one of these problems. Your customers just blame your brand for them. ## Three ways to add eSIM to your product ### 1. Redirect to a partner's store The fastest option is an affiliate link or a partner-branded store. It takes almost no engineering. But you give away the customer relationship, the data, and most of the margin. That's fine for a test, but weak as a product. ### 2. White-label storefront A storefront under your brand with your bundle catalogue, checkout, payments, QR delivery and onboarding pages. The customer stays with you and you control pricing. Integration is light, usually a subdomain or a link from inside your app. ### 3. API-embedded eSIM The deepest option. eSIM offers appear inside the existing journey: a "Add 5 GB for Japan" option on the flight confirmation page, or a data bundle as a card or loyalty perk. This converts best because the offer appears at the moment of need. It also takes the most engineering. ## A reference architecture for the API approach Here's a simplified flow for adding eSIM to a booking confirmation:
Offer. When a booking is confirmed, your backend calls a catalogue endpoint with the destination country and trip dates, and gets back matching bundles with prices.- Purchase. Payment goes through your existing payment flow. On success, your backend calls an order endpoint with an idempotency key, so a retry never creates two eSIMs.- Delivery. The order returns an activation code or QR. Show it in the app and send it by email. Install instructions should be specific to the device platform.- Lifecycle events. Subscribe to webhooks for installed, activated, low data, and expired. These drive push notifications and top-up prompts.- Top-up. A low-data event triggers a one-tap top-up offer in your app. This is where a lot of the revenue comes from.- Support. Pass the order and device status to your support tool, so agents can see whether a profile was ever installed before they ask the customer to reinstall.Some practical notes from this kind of build:
Treat the order endpoint as non-idempotent unless the provider says otherwise, and always send your own idempotency key.- Store the ICCID (the eSIM's unique ID) against your customer and booking. It's your key for every support and lifecycle call.- Don't make activation the customer's problem. Most failed activations come from roaming being off or the wrong data line being selected. A short in-app checklist cuts tickets a lot.- Price in local currency and show data and validity clearly. "5 GB / 30 days" sells better than plan names.## Where teams usually get stuck The API call is the easy part. The hard parts are:
Coverage and supply. Negotiating with operators country by country takes months.- Margins. You need per-market control over cost, price and partner share.- Operations. Refunds, failed installs, and top-ups all need tooling, not spreadsheets.- Analytics. You need to know activation rate, attach rate per booking, and revenue per market, or you can't tell whether this is working.This is why many teams use a platform for the telecom side and keep the customer experience for themselves. ## How One-eSIM fits in Disclosure: I work on One-eSIM. It's a cloud platform for this exact problem. It includes a connectivity marketplace with multi-region supply under one set of commercial terms, a white-label webshop engine, an API layer for embedding eSIM into booking, payment and loyalty journeys, a management portal for pricing and margins, AI-assisted support and top-up flows, and real-time analytics. The brand keeps the customer relationship. If you're working on this for a travel, mobility or fintech product, the platform overview lays out the deployment models. I'm also happy to answer questions in the comments, including if you're building it yourself.