Skip to main content

eSIM purchase​

Flowchart​

Lets your users search for and purchase mobile data eSIMs for their destination country. The flow starts with fetching active contracts and the list of countries with eSIM availability, then narrows down to specific data plans by destination country. Once a variant is selected, an order is created and a PDF voucher containing the QR code and eSIM ID is issued to the traveler.

Sequence diagram​

eSIM purchase flow​

This scenario describes the interaction flow between the client and the ETT API via the WebApp for searching eSIM data plans by destination country, purchasing an eSIM, and retrieving the voucher.

Overall process logic​

The process consists of the following steps:

  1. Retrieve available contracts
  2. Retrieve the list of countries with eSIM availability
  3. Retrieve the list of eSIM products for the selected country
  4. Create an order
  5. Retrieve order details
  6. Generate a voucher
  7. Refund the order (optional)

The WebApp acts as an intermediary between the client and the ETT API.

1. Retrieve contracts​
  • Method: getContracts
  • Description: Retrieves the list of available contracts for the agent, including balance and credit.
  • Result: A list of valid agent contracts.
2. Retrieve eSIM countries​
  • Method: getEsimCountries
  • Description: Retrieves the list of countries where eSIM data plans are available.
  • Result: A list of countries with their ISO code, unlimited-data availability, and data allowance.
3. Retrieve eSIM products by country​
  • Method: getEsimProductsByCountry(contractId, isoCode)
  • Parameters:
    • contractId — selected contract identifier
    • isoCode — destination country ISO code
  • Description: Returns the list of eSIM products available for the selected country.
  • Result: A list of eSIM products with title, covered countries, and variants (variantId, price, dataHash, call minutes, data).
4. Create order​
  • Method: createOrder(contractId, variantId, email, dataHash, destinationCountry, homeCountry)
  • Parameters:
    • contractId — contract identifier
    • variantId — selected eSIM variant identifier
    • email — traveler's email
    • dataHash — selected variant's data hash
    • destinationCountry — destination country
    • homeCountry — traveler's home country
  • Description: Creates an order for the selected eSIM plan.
  • Result: Coupon code, orderId, and orderItemId.
5. Retrieve order details​
  • Method: getOrder(contractId, orderId)
  • Parameters:
    • contractId — contract identifier
    • orderId — order identifier
  • Description: Retrieves full information about the order.
  • Result: Order details including order items, coupon code, iccid, and status.
6. Generate voucher​
  • Method: generateOrderItemCoupon(orderId, orderItemId)
  • Parameters:
    • orderId — order identifier
    • orderItemId — order item identifier
  • Description: Generates a PDF voucher for the selected order item.
  • Result: A downloadable PDF document containing the QR code and eSIM ID.
7. Refund order (optional)​
  • Method: refundOrder(orderId, orderItemId)
  • Parameters:
    • orderId — order identifier
    • orderItemId — order item identifier
  • Description: Cancels and refunds the selected order item.
  • Result: A success confirmation.

eSIM top-up​

Flowchart​

Lets your users add extra data to an eSIM they already purchased. The flow starts by looking up the existing eSIM order by its ICCID, then retrieves the list of top-up plans available from the same supplier as the original eSIM. Once a top-up plan is selected, a new order is created against the existing ICCID.

Sequence diagram​

eSIM top-up flow​

This scenario describes the interaction flow between the client and the ETT API via the WebApp for looking up an existing eSIM, retrieving available top-up plans, and purchasing a top-up.

Overall process logic​

The process consists of the following steps:

  1. Retrieve the existing eSIM order (optional)
  2. Retrieve the list of available top-up plans
  3. Create a top-up order

The WebApp acts as an intermediary between the client and the ETT API.

1. Retrieve eSIM order (optional)​
  • Method: getEsimOrder(contractId, iccid)
  • Parameters:
    • contractId — contract identifier
    • iccid — ICCID of the existing eSIM
  • Description: Retrieves details of the existing eSIM order, used only to show which eSIM is being topped up. Not required for the top-up itself, since getEsimTopUps already validates the ICCID.
  • Result: eSIM order details including orderId, order items, supplier, and iccid.
2. Retrieve top-up plans​
  • Method: getEsimTopUps(contractId, iccid)
  • Parameters:
    • contractId — contract identifier
    • iccid — ICCID of the existing eSIM
  • Description: Returns the list of top-up plans available from the same supplier as the original eSIM.
  • Result: A list of top-up plans (variantId, price, dataHash, data).
3. Create top-up order​
  • Method: createOrder(contractId, variantId, iccid, dataHash)
  • Parameters:
    • contractId — contract identifier
    • variantId — selected top-up variant identifier
    • iccid — ICCID of the existing eSIM
    • dataHash — selected variant's data hash
  • Description: Creates a top-up order for the existing eSIM.
  • Result: Order details including order items, coupon code, iccid, and status.