Skip to main content

eSIM

Sell a traveller a data plan and provision the eSIM profile they install. There are four resources, in the order you use them, and a link to a hosted page.

What it is
PackagesThe catalog. A plan with a data allowance, validity period, and the countries it works in.
OrdersBuying a package. An order allocates an eSIM and puts the package on it.
ProfilesThe eSIM itself, along with the packages running on it.
Top-upsAdding more data to a package that's already running.
H5A short-lived link to a hosted eSIM page for one cardholder.

How it fits together​

Ordering is synchronous. There's no queue or callback: a 201 means the eSIM is ready. If something goes wrong, you get an error response and the order isn't left half-finished.

Before you start​

  • You need a credential with the eSIM scopes. See authentication.
  • The catalog is shared across the platform and read-only. It changes when coverage or pricing changes, so cache it for a few minutes, not days.

The one thing to get right​

The activation code is the profile. It's returned when you retrieve a single eSIM and deliberately left out of listings. Otherwise, a page showing a hundred eSIMs could also expose a hundred secrets.

Treat the activation code like a card number: don't put it in logs, analytics, or URLs.

Retrieve an eSIM when you're about to send the customer their install instructions, not when the page first loads.

Ordering can fail, so check first​

A package must be available when you place the order. Fetch the package you're about to buy right beforehand instead of relying on a cached list. If the package has been frozen or withdrawn, the order is rejected with esim_package_unavailable.

The same idea applies to top-ups. Which add-ons an eSIM can use depends on what's currently running on it, so fetch the list right before creating a top-up.

An H5 link sends one cardholder to a hosted eSIM page. It lasts 15 minutes, and it opens as many times as you like until then.

Create the link from your backend when the cardholder asks for the page, then redirect them straight to url. Don't put the link itself in an email, SMS, or push notification, because it has usually expired by the time it's opened. Link to your own endpoint instead, and have it create a fresh H5 link and redirect when it's followed.

Treat url like the activation code. Anyone holding it acts as that cardholder until it expires, so keep it out of logs, analytics, and storage.

Reference​

Last updated on