zendit developers Logo
Search zendit documentation
Menu

zendit eSIM

Zendit eSIMs provide roaming data connectivity for the travel market on eSIM capable devices. eSIMs are available for a specific destination country or for a destination region.

eSIM v2.0 Release

Zendit eSIMs are in full release for purchase.  

New in this release

  • Reloadable eSIMs
  • eSIM Plan Usage

About the product

Zendit eSIMs provide roaming data connectivity for the travel market on eSIM capable devices. eSIMs are available for a specific destination country or for a destination region. Many specific destination country eSIMs have additional roaming beyond the destination country. As an example, eSIMs purchased for France will support roaming in Spain, Germany, Austria, etc. 

Plans are available for the following configurations:

  • 7 Days / 1 GB
  • 30 Days / 3 GB
  • 30 Days / 5 GB
  • 30 Days / 10 GB*
  • 30 Days / 20 GB*

* Plans not available in all destinations

You can find the list of known devices that support eSIMs in the Zendit User’s Guide.

eSIM Activation

An eSIM will become active the first time the user turns on data roaming with the eSIM and it successfully connects to the cellular network. An eSIM can be purchased and installed on the user’s device without being activated until a later date. Once the purchased offer has been activated and either the data limit or duration of the offer is reached, the eSIM will no longer have a valid plan. Currently the eSIM will not be reloadable and if the customer purchases another offer, they will receive a new ICCID. In a future release, Zendit will support reloading an eSIM issued by Zendit so the user can retain the eSIM. When this feature is rolled out, an eSIM without a remaining offer will be expired and no longer reloadable after 12 months of inactivity.

eSIM Types

Zendit eSIMs are available in 2 types: Regional and Destination Country without Roaming.

Regional eSIM

eSIMs are available to support roaming within a specific region. There is a Global regional eSIM available for roaming in most countries in the world. Additionally there are eSIMs available for Europe, Central America, Africa, Asia, Middle East, North America and Oceania.

Regional eSIMs contain an array of countries for roaming with the available data speeds on networks within the countries. This information is available through the catalog endpoints for retrieving offers.

To see the list of regions for eSIMs, visit the catalog topic.

Destination Country with No Roaming eSIM

eSIMs are available for a specific destination country. These eSIMs are only supported in the destination country and do not support roaming. For example, an eSIM for Mexico will only work in Mexico and will not operate in Guatemala.

New Endpoints for eSIM

eSIMs have a new set of API endpoints for pulling the catalog and pricing, submitting a transaction for fulfillment, getting the status of the transaction and getting the QR Code to install the eSIM. You can find this information in the API Guide.

Requirements to Purchase an eSIM

Purchasing an eSIM only requires 2 parameters – the offer ID and the transaction ID. All products are of fixed pricing type. This simplifies the purchase process.

Webhook

eSIM has a webhook available for receiving the status of the transaction. The webhook format is identical to the format of polling the transaction by ID on the eSIM endpoints for status and will have the following format:

For more information on setting up Webhooks in Zendit, see the Webhooks documentation.

QR Code generation

Zendit provides an endpoint to retrieve the QR code on the API. Optionally, eSIMs can be generated by the client using their QR generator of choice. To create the eSIM the following format must be encoded into the eSIM:

LPA:1$smdpAddress$matchingID

The SMDP+ Address is an url to retrieve from the transaction in the smdpAddress field and the matching ID is in the externalReferenceId field. Both fields can be found in the confirmation section of the transaction.

Note for Test Mode transactions, QR Codes from the API are dummy QR codes.

Generating the Receipt for Customers

When generating a receipt for your customers, be sure to include values from the confirmation section of the transaction with friendly names that will help your customers if they aren’t able to install through the QR Code.

The outputs should include:

  • SMDP+ Address – from confirmation smdpAddress
  • Activation Code – from confirmation externalRefrenceId
  • Confirmation Code – from confirmation activation code
  • ICCID – from confirmation iccid

These value mappings will assist users when using the instructions for installing their eSIM . In the confirmation section of a successful transaction, the redemption instructions link to the instructions page. For preserving your branding, you are welcome to copy the instructions from that page to your own integration to supply your users with branded instructions. There’s also a white label PDF available from the instructions page that you may include for your customers to assist in installing the eSIM.

Tracking the ICCID of Customers

When users purchase eSIM products, to provide the user with information about how many days are left in their plan and how much data they have remaining, you’ll need to track the ICCID they are using to retrieve this data for them when the feature is available on Zendit.

An eSIM may be loaded with multiple plans based on customer needs. Keeping an inventory or user profile that your ICCIDs are assigned to will assist with locating the customer so their ICCID can be sent through when purchasing a plan instead of issuing a new eSIM each time a customer purchases a plan.

eSIM and Plan Expiration

eSIMs that remain unused for 12 months will be reclaimed. If the eSIM contains any plans, these plans will be forfeited by the purchaser. The eSIM must have activity on it every 12 months to remain active. Activities include:

  • Purchasing a Plan
  • Using a Plan

Each of these activities will reset the 12 month expiration countdown for the eSIM. Additionally, each eSIM may have up to 30 bundles queued on them simultaneously.

How Plans are Used

Plans are used in order of which plan will expire first. As an example a user with 2 7 day, 1 GB plans for the US would use the plans one after another. The first plan would be consumed until either the data is completely consumed or the plan expires. After that, the second plan would become active and would be consumed until it has either exhausted data or has expired.

In the case that a user has a 7 day, 1 GB US plan and a 30 day, 3 GB US plan, when the use attaches to the network in the US, the 7 day plan would be used first until it has expired or been exhausted. If the user is still in the US, the 30 day, 3 GB plan would become active and begin to be used first.

In the case of Regional Plans, they follow the same rules of usage by earliest expiration. Consider the scenario that a user has purchased a 30 day, 3 GB North America plan, a 7 day, 1 GB US plan and a 30 day, 3 GB US plan.

If the user arrives in the US, the 7 day, 1 GB US plan would begin being used since it would expire before the 30 day plans. If after 3 days, the user travels to Canada for 2 days, the 30 day, 3 GB North America plan would become active and used in Canada.

If the user then arrives back in the US 5 days into their usage, usage would resume on the 7 day, 1 GB plan until it is exhausted of data or expired. At this point the 30 day, 3 GB North America plan would be used (since it will expire before the 30 day US plan that has not yet been used) until the plan is exhausted of data or expired. If the user is still in the US the 30 day, 3GB US plan would begin being used.

eSIM Usage

The usage of an eSIM can be tracked through both the API and the through the user console in the eSIM usage section. All queued or active plans will be available. Queued plans are plans that have not been used by the customer yet. Active plans will have a start and end date based on the user’s first usage and will return the original amount of data that the plan was issued with as well as the remaining data. Only queued or active plans are available to view usage. Plans that have expired or all data has been consumed will no longer be available in the list of plans assigned to the eSIM.