Zetexa eSIM API reference
In short: The core ordering flow of the Zetexa B2B API for partners (resellers): authenticate, browse countries, regions and packages, place an order, retrieve the eSIM activation details, check orders and usage, and list airport lounge, fast track and meet & greet services. All examples use placeholder values and are illustrative; the fields your account returns can differ and can change. Your Zetexa integration contact issues your credentials and confirms the details for your account before you go live.
Authentication and basics
Base URL and transport
- Base URL: https://<BASE_URL>. Zetexa supplies the real value (sandbox and production) with your credentials. Every path on this page is relative to it.
- Every call is an HTTP request over HTTPS. GET calls take query parameters; POST calls take a JSON body.
Authentication
- Two credentials are used together. The AccessToken header carries your long-lived partner access token, issued by Zetexa. The Authorization header carries a session token: Authorization: Bearer <SESSION_TOKEN>.
- Get a session token with Create-Token (below), using your AccessToken and your account email and password. Send both headers on every other call.
- A session token is valid for 10 days. Request a new one when you get a 401. A missing AccessToken returns 403; a missing, invalid or expired session token returns 401.
- Keep both tokens on your server only. Never put them in a mobile app, a browser page, a screenshot or a code repository.
Headers used by every example below, unless noted:
AccessToken: <ACCESS_TOKEN>
Authorization: Bearer <SESSION_TOKEN>
Content-Type: application/json (POST requests only)Responses and errors
- Responses are JSON with a boolean success, usually a message, and a payload key that varies (data, usage, qr_codes, balance, session_token).
- Errors look like {"success": false, "message": "..."}, or for validation {"success": false, "errors": [{"field": "...", "message": "..."}]}. Statuses you can expect: 200, 400, 401 and 403.
- A 200 can carry success: false (for example a package search with no match), so check success, not the status code alone. Do not match on the text of a message; it can change.
Money
- Amount formats differ by endpoint: plain numbers (package prices, balance), numeric strings (Orders-List) and symbol-prefixed strings such as "$ 5.00" (Order-Details). Take the currency from the currency field, never from the symbol.
Create a session token
POST /v1/Create-Token
Exchanges your account credentials for a session token. Send only the AccessToken header on this call.
- : Your partner account email.
- password
- : Your partner account password.
Example request
{"email": "partner@example.com", "password": "<PASSWORD>"}Example response
200
{"success": true, "session_token": "<SESSION_TOKEN>"}- 403 when the AccessToken header is missing.
List countries and regions
GET /v2/Countries-ListGET /v2/Regions-List
Lists the countries or regions you can sell eSIM packages for. No parameters.
Example response
GET /v2/Countries-List
200
{
"success": true,
"message": "Data Fetched Successfully",
"data": [
{"id": 1, "name": "Exampleland", "iso2": "XX", "iso3": "XXX", "image": "https://<IMAGE_HOST>/flag.svg"}
]
}- Region rows carry id, name and image only (no iso2 or iso3).
- Errors: 403 (AccessToken missing), 401 (session token missing or invalid).
List packages
GET /v3/Packages-List
Lists the packages you can sell for a country or a region.
- filterby
- : Required. Country or Region.
- country_code
- : Required when filterby is Country (the iso2 code from the country list).
- region_name
- : Required when filterby is Region.
- plan_name
- : Optional integer: 1 for data-only plans, 2 for plans with data, voice and SMS.
Example request
GET /v3/Packages-List?filterby=Country&country_code=XX&plan_name=1Example response
200
{
"success": true,
"currency_code": "USD",
"data": [
{
"package_id": "<PACKAGE_ID>",
"package_name": "Exampleland 1 Day 1 GB",
"data": "1.0 GB",
"data_in_mb": 1024,
"call": 0,
"call_in_seconds": 0,
"sms": 0,
"validity": 1,
"coverage": "4G",
"price": 3.1,
"network": null,
"status": true,
"fup_policy": null,
"countries": [{"countryname": "Exampleland", "countryiso2": "XX"}],
"package_category": 1
}
]
}- package_category is 1 for data-only packages and 2 for data, voice and SMS packages.
- A search with no match returns 200 with success: false and an empty data list.
- 400 when filterby is missing, or when country_code or region_name is missing for the chosen filterby.
Create an order
POST /v1/Create-Order
Orders one or more eSIM packages. The response does not carry the SIM data: fetch it afterwards with the QR code call or the order details call.
- package_id
- : Required. The package_id from the package list.
- country, first_name, last_name, address, email, quantity
- : Send these with every order. Your integration contact confirms which are enforced for your account and the limits on quantity.
- state, city, pincode, phone_number
- : Optional.
- reseller_orderid_name, reseller_orderid
- : Optional. Your own order reference.
Example request
{
"package_id": "<PACKAGE_ID>",
"country": "XX",
"first_name": "Jane",
"last_name": "Doe",
"address": "1 Example Street",
"email": "jane.doe@example.com",
"quantity": 1,
"reseller_orderid": "PARTNER-0001"
}Example response
200
{
"success": true,
"message": "Order Created successfully",
"order_id": "<ORDER_ID>",
"net_amount": 2.5,
"gross_amount": 2.5,
"total": 2.5,
"status": "Completed"
}- 400 "package id Field Required" when package_id is missing; 401 and 403 as above.
- Retry safety and duplicate-order handling are not described here: confirm them with your integration contact before you retry an order after a timeout.
Get the QR code and activation details
GET /v1/get-qrcode-details
Returns the activation details for an order, one entry per order line.
- order_id
- : Required. The order_id returned by Create an order.
Example request
GET /v1/get-qrcode-details?order_id=<ORDER_ID>Example response
200
{
"success": true,
"message": "QR codes retrieved successfully",
"qr_codes": [
{
"order_id": "<ORDER_ID>",
"orderline_id": "<ORDERLINE_ID>",
"iccid": "<ICCID>",
"plan_id": "<PLAN_ID>",
"plan_name": "Exampleland 1 Day 1 GB",
"lpa_server": "LPA:1$<SMDP_ADDRESS>$<MATCHING_ID>",
"qr_code": "data:image/png;base64,<BASE64_PNG>"
}
]
}- Treat the QR code and the lpa_server value as secrets: whoever holds them can install the eSIM. Show them only to the customer who bought it.
List your orders
GET /v1/Orders-List
Lists the orders of your partner account.
- page
- : Optional page number.
- page_size
- : Optional page size. Defaults and the maximum are confirmed with your integration contact.
Example request
GET /v1/Orders-List?page=1&page_size=10Example response
200
{
"success": true,
"message": "Order List fetched successfully",
"total_pages": 1,
"current_page": 1,
"total_records": 1,
"data": [
{
"order_id": "<ORDER_ID>",
"order_status": "Completed",
"email": "jane.doe@example.com",
"currency": "USD",
"payment_method_name": "wallet",
"total_net": "2.50",
"tax": "0.00",
"total_gross": "2.50",
"created_on": "2030-01-01T00:00:00",
"total_value": 2.5
}
]
}- order_status values include Pending, Processing, Completed, Refund, Kyc Pending, NO EKYC and Payment Link Sent.
Get one order
POST /v2/Order-Details
Returns one order with its packages and the SIMs on it.
- order_id
- : Required. The order to read.
Example request
{"order_id": "<ORDER_ID>"}Example response
200 (abridged)
{
"success": true,
"data": {
"order": {
"order_id": "<ORDER_ID>",
"currency": "USD",
"total_paid": "$ 2.50",
"order_status": "Completed"
},
"packages": [
{
"package_name": "Exampleland 1 Day 1 GB",
"quantity": 1,
"validity": 1,
"sim_type": "ESIM",
"unit_price": "$ 2.50",
"simsdata": [
{
"iccid": "<ICCID>",
"lpa_server": "LPA:1$<SMDP_ADDRESS>$<MATCHING_ID>",
"sim_status": "FREE",
"order_package_id": "<ORDER_PACKAGE_ID>",
"package_id": "<PACKAGE_ID>"
}
]
}
]
}
}- Amounts are symbol-prefixed strings and the spacing can vary: read the currency field.
Check eSIM usage and status
POST /v2/ESim-Usage
Returns the current usage counters and the status of one eSIM.
- iccid
- : Required. The ICCID of the eSIM.
Example request
{"iccid": "<ICCID>"}Example response
200
{
"success": true,
"usage": {
"sim_status": "UNUSED",
"iccid": "<ICCID>",
"data": 0,
"out_call": "0",
"in_call": "0",
"in_sms": "0",
"out_sms": "0",
"in_voip": "0",
"out_voip": "0"
}
}- sim_status values: UNUSED (not installed), BPP_INSTALLATION (installed), ENABLE (data on), DISABLE (data off) and DELETE (profile removed).
- The units of data and of the counters are confirmed with your integration contact.
Read your wallet balance
POST /v1/Reseller-Balance
Returns the balance of your partner wallet. No body.
Example response
200
{"success": true, "message": "Reseller Balance fetched successfully", "balance": 100.0}- The currency and precision of the balance are confirmed with your integration contact.
List ancillary services
GET /v1/available-services
Lists the ancillary services enabled for your partner account: airport lounge (BusinessLounge), fast track (FastTrack) and meet & greet (MeetAndGreet).
- reseller_id
- : Your partner account id, issued by Zetexa.
Example request
GET /v1/available-services?reseller_id=<RESELLER_ID>Example response
200
{
"success": true,
"message": "Available services fetched successfully.",
"data": [
{
"service_name": "BusinessLounge",
"display_name": "BusinessLounge",
"service_description": "Premium Business Lounge",
"reseller_id": "<RESELLER_ID>",
"agent_id": null,
"status": true,
"service_image_url": null
},
{
"service_name": "FastTrack",
"display_name": "FastTrack",
"service_description": "Fast Track Services",
"reseller_id": "<RESELLER_ID>",
"agent_id": null,
"status": true,
"service_image_url": "https://<IMAGE_HOST>/service.png"
},
{
"service_name": "MeetAndGreet",
"display_name": "MeetAndGreet",
"service_description": "Meet and greet Services",
"reseller_id": "<RESELLER_ID>",
"agent_id": null,
"status": true,
"service_image_url": "https://<IMAGE_HOST>/service.png"
}
]
}- Send your credentials as described under Authentication; your integration contact confirms the exact headers for the ancillary calls.
List ancillary plans at an airport
GET /v1/get-available-plans
Lists the lounge, fast track and meet & greet plans you can sell at one airport, grouped by service family, with prices, ages, opening times, facilities and cancellation rules.
- airportCode
- : The IATA airport code, for example DXB.
- currencyCode
- : The currency the prices are returned in, for example USD.
- language
- : The language of names and descriptions, for example en.
- reseller_id
- : Your partner account id.
Example request
GET /v1/get-available-plans?airportCode=DXB¤cyCode=USD&language=en&reseller_id=<RESELLER_ID>Example response
200 (one plan shown; the real list is longer)
{
"success": true,
"message": "Available services and plans fetched successfully.",
"data": {
"airport_code": "DXB",
"currency_code": "USD",
"language": "en",
"services": {
"BusinessLounge": [
{
"addons_service": {
"plan_id": "<PLAN_ID>",
"service_id": "<SERVICE_ID>",
"name": "Example Lounge (Terminal 1)",
"service_name": "BusinessLounge",
"display_name": "BusinessLounge",
"shortDescription": "Wifi Access;\nSnacks;\nBeverages",
"meetingPoint": "Airside, after passport control and security, on the level above the boarding gates.",
"terminalName": "Terminal 1",
"serviceDirection": "Departure",
"airportName": "Dubai International Airport",
"price": {
"adult": 35,
"child": 35,
"infant": 0
},
"isNonRefundable": true,
"facilities": [
{
"isEnabled": true,
"isPaid": false,
"name": "Wifi Access"
},
{
"isEnabled": true,
"isPaid": false,
"name": "Snacks"
},
{
"isEnabled": true,
"isPaid": false,
"name": "Beverages"
},
{
"isEnabled": true,
"isPaid": false,
"name": "Flight Monitor"
}
],
"cancellationFees": [],
"airportIataCode": "DXB",
"serviceCurrencyCode": "USD",
"prebookingFee": null,
"plannedPrice": null,
"isPlannedPriceEnabled": false,
"weekSchedule": [
{
"weekDay": "Monday",
"dayNumber": 0,
"dayName": "Monday",
"isActive": true,
"begin": "00:00:00",
"end": "23:59:59"
}
],
"tax_percentage": 0,
"booking_fields": [
{
"name": "name",
"type": "text",
"label": "Full Name",
"min_max": null,
"options": null,
"disabled": false,
"required": true,
"validator": "^[A-Za-z]+(?:\\s[A-Za-z]+)+$",
"placeholder": "Enter Your Name",
"default_value": null
}
],
"infantAge": {
"bottom": null,
"upper": 2
},
"childAge": {
"bottom": 2,
"upper": 12
},
"adultAge": {
"bottom": 12,
"upper": null
}
},
"policies": {
"terms_and_conditions": "",
"privacy_policy": "",
"refund_policy": "",
"cancellation_policy": ""
},
"contact_information": {
"contact_information": "",
"contact_email": "",
"contact_phone": "",
"contact_address": ""
},
"booking_fields": [
{
"name": "name",
"type": "text",
"label": "Full Name",
"min_max": null,
"options": null,
"disabled": false,
"required": true,
"validator": "^[A-Za-z]+(?:\\s[A-Za-z]+)+$",
"placeholder": "Enter Your Name",
"default_value": null
}
]
},
{
"minimum_started_from": 35
}
]
}
}
}- Plans come back grouped by family under data.services: BusinessLounge, FastTrack and MeetAndGreet. FastTrack and MeetAndGreet plans have the same shape as the lounge plan above.
- The last element of each family list is an object with minimum_started_from, the lowest starting price for that family. A large airport can return more than twenty plans in one family.
- price holds the adult, child and infant price in the requested currency; infantAge, childAge and adultAge give the age bands. isNonRefundable, cancellationFees (hours before the service time and the fee in percent) and preOrderPeriodInMinutes are the booking rules for the plan: show them to the customer before checkout.
- booking_fields lists the details to collect for a booking, with a validator pattern for each. weekSchedule has one entry for each weekday.
- Creating and cancelling an ancillary booking is not covered on this page.
Not on this page: top-ups for an existing eSIM, wallet transactions, per-plan data usage, the top-up package list, token validation, KYC, refunds, local lines, booking and cancelling ancillary services, and webhooks. Your Zetexa integration contact provides the reference for the ones in your agreement.
Last updated: . All values in the examples are placeholders.
Ready to integrate?
Request sandbox access through Book a demo. Your Zetexa integration contact issues your credentials and the reference for your agreement.