eSIM: Purchase a New eSIM
Disclaimer
Example field values in response JSON files are significant for format and type only. Do not interpret them as actual data; prices, for example, are invented and non-binding.
Example Product Retrieval
For full endpoint descriptions, see:
GET /products/50701{
"availability_zones": [
"INTERNATIONAL"
],
"benefits": [
{
"additional_information": null,
"amount": {
"base": 1,
"promotion_bonus": 0,
"total_excluding_tax": 1,
"total_including_tax": 1
},
"type": "DATA",
"unit": "GB",
"unit_type": "DATA"
}
],
"description": "1 GB 7 days Europe Extended",
"id": 50701,
"name": "1 GB 7 days Europe Extended",
"operator": {
"country": {
"iso_code": "EXX",
"name": "Europe",
"regions": [
{
"code": "ALB",
"name": "Albania"
},
{
"code": "AND",
"name": "Andorra"
},
{
"code": "AUT",
"name": "Austria"
}
]
}
},
"pin": {
"terms": null,
"usage_info": [
"To activate your eSIM, scan the QR code or manually enter the activation code.",
"For manual installation, use the code: LPA:1$smdp.io$K2-27D7HN-IP0UJ1"
]
},
"prices": {
"retail": {
"amount": -1,
"fee": 0,
"unit": "USD",
"unit_type": "CURRENCY"
},
"wholesale": {
"amount": 1,
"fee": 0,
"unit": "USD",
"unit_type": "CURRENCY"
}
},
"service": {
"id": 13,
"name": "eSIM"
},
"type": "FIXED_VALUE_PIN_PURCHASE"
}Geographical Coverage
This product provides coverage across multiple regions. To retrieve products based on geographical coverage, your platform can filter the response into three categories:
- Global Coverage: Products available worldwide.
- Regional Coverage: Products available in specific regions (e.g., Europe).
- Country-Specific Coverage: Products available in individual countries.
DT One assigns special codes to represent coverage for multiple countries:
- GXX: Represents global coverage.
- EXX: Represents coverage in Europe.
- ISO Country Codes: For country-specific coverage (e.g., MEX for Mexico).
- country_iso_code : will fetch for specific country
- region : will fetch if the region exists in the list of region
Below are examples of how to retrieve products based on coverage:
GET /products?service_id=13&country_iso_code=GXX
// Retrieves all products with global coverage (available worldwide).GET /products?service_id=13&country_iso_code=EXX
// Retrieves all products with coverage in the Europe region.GET /products?service_id=13&country_iso_code=MEX
// Retrieves all products with coverage specific to Mexico.Required Fields
The "required_*" fields indicate the additional data elements beyond the standard minimum payload that you must include in POST transaction requests for each corresponding party or identifier. These fields specify the necessary information for a particular product. If a field is listed as required, your transaction request will likely be unsuccessful if it is not included.
"required_additional_identifier_fields": null,
"required_beneficiary_fields": null,
"required_credit_party_identifier_fields": [
[
"account_number"
]
],
"required_debit_party_identifier_fields": null,
"required_sender_fields": null,
"required_statement_identifier_fields": nullIn this setup, the "required_credit_party_identifier_fields" array specifies that you must include the "account_number" field within the "credit_party_identifier" object when making a POST transaction request for this product.
{
"credit_party_identifier": {
"account_number": "5865151648338875078"
}
}When the value of a "required_*" field is null, it means that no additional fields are necessary for that specific section beyond the base requirements for this product. Always review the "required_*" configuration for the specific product you are working with to ensure your transaction requests contain all the necessary information for successful processing.
Additional Fields for PIN-based Products
Most PIN-based products do not require additional fields beyond the standard minimum payload, as a PIN code for redemption is provided. Therefore, fields such as credit_party_identifier.account_number are typically not mandatory.
However, if you include the credit_party_identifier.account_number in your request for a PIN-based product, the PIN code will also be delivered via SMS to the provided mobile number.
When purchasing a PIN product, the discovery process will include a new "pin" field. This field contains the following information:
"pin": {
"terms": "Determined terms and conditions on the operator's side, this information will be provided here",
"usage_info": [
"Activate this voucher via MyLebara app or dial 5588. Get 5 off when you register & buy at lebara.co.uk. Use promocode EPIN at checkout",
"To recharge your phone, please dial *#1345* followed by the pin number and the # key.",
"",
"IVR: 1345"
],
"validity": {
"quantity": 6,
"unit": "MONTH"
}
}The "pin" field provides "usage_info" detailing how to redeem the delivered PIN code, as well as "validity" information and any applicable "terms" and conditions.
Disclaimer
Example field values in response JSON files are significant for format and type only. Do not interpret them as actual data; prices, for example, are invented and non-binding.
To post a transaction for purchasing a new SIM, you use the POST: Create a transaction asynchronously endpoint.
Implementation Techniques
Technique 1: One-Step Transaction
Create and confirm the transaction in one step.
{
"external_id": "SIM-NEW-001",
"product_id": 50701,
"auto_confirm": true,
"callback_url": "https://callback.example.com",
"beneficiary": {
"first_name": "John",
"last_name": "Doe",
"email": "[email protected]",
"phone_number": "+1234567890"
}
}Explanation:
By setting auto_confirm to true, the transaction is created and confirmed immediately.
Technique 2: Two-Step Transaction
Create the transaction, then confirm it separately. When auto_confirm is set to false (or not specified):
- A separate POST request to Confirm a transaction asynchronously is required.
- This allows for a delay between transaction creation and submission to DT One, useful for:
- Collecting payment.
- Verifying RANGED product type prices.
Important:
- The maximum time allowed between the CREATED (1) and CONFIRMED (2) statuses is 60 minutes.
- Transactions not confirmed within 60 minutes will be automatically canceled.
{
"external_id": "SIM-NEW-001",
"product_id": 50701,
"auto_confirm": false,
"callback_url": "https://callback.example.com",
"beneficiary": {
"first_name": "John",
"last_name": "Doe",
"email": "[email protected]",
"phone_number": "+1234567890"
}
}Statuses for Transactions
For even more detailed information, see Handling Transactions.
---
config:
theme: neutral
fontSize: 16
look: neo
layout: fixed
---
flowchart LR
B@{ label: "<b>CREATED</b><br><span style=\"font-size: 2em;\">1</span>" } -- "<span style=color:>POST<br>/transactions<br>/[id]<br>/confirm</span>" --> C@{ label: "<b>CONFIRMED</b><br><span style=\"font-size: 2em;\">2</span>" }
C -- "<span style=color:>Sent to<br>receiving<br>partner</span>" --> D@{ label: "<b>SUBMITTED</b><br><span style=\"font-size: 2em;\">5</span>" }
D --> E@{ label: "<b>COMPLETED</b><br><span style=\"font-size: 2em;\">7</span>" }
E -- "<span style=color:>Callback</span>" --> F@{ label: "<b>REVERSED</b><br><span style=\"font-size: 2em;\">8</span>" }
B -- "<span style=color:>Callback</span>" --> G@{ label: "<b>REJECTED</b><br><span style=\"font-size: 2em;\">3</span>" }
B -- "<span style=color:>Callback<br>POST<br>/transactions<br>/[id]<br>/cancel</span>" --> H@{ label: "<b>CANCELLED</b><br><span style=\"font-size: 2em;\">4</span>" }
D -- "<span style=color:>Callback</span>" --> I@{ label: "<b>DECLINED</b><br><span style=\"font-size: 2em;\">9</span>" }
B@{ shape: rounded}
C@{ shape: rounded}
D@{ shape: rounded}
E@{ shape: rounded}
F@{ shape: rounded}
G@{ shape: rounded}
H@{ shape: rounded}
I@{ shape: rounded}
style B fill:#FFFFFF,stroke:#1D8DF0,stroke-width:3px
style C fill:#FFFFFF,stroke:#1D8DF0,stroke-width:3px
style D fill:#FFFFFF,stroke:#1D8DF0,stroke-width:3px
style E fill:#FFFFFF,color:#000,stroke:#90ee90,stroke-width:3px
style F fill:#FFFFFF,stroke:black,stroke-width:3px
style G fill:#FFFFFF,stroke:#f08080,stroke-width:3px
style H fill:#FFFFFF,stroke:#f08080,stroke-width:3px
style I fill:#FFFFFF,stroke:#f08080,stroke-width:3px
A final status is a status after which there are no further statuses.
Only COMPLETED 7, REJECTED 3, CANCELLED 4, and DECLINED 9 are final statuses. SUBMITTED 5 and CONFIRMED 2 are NOT final statuses.
- Transaction reachesSUBMITTED 5 status.
- An immediate hold is placed on the initiator’s wallet for the wholesale price of the product.
- If Status changes toCOMPLETED 7
- The wholesale price is deducted from the wallet.
- If Status remainsSUBMITTED 5
- The balance remains on hold.
- If Status changes toREVERSED 8, REJECTED 3, or DECLINED 9
- The hold is released, and the wallet balance is adjusted accordingly.
Minimum Payload Request for POST: Create a transaction asynchronously
{
"external_id": "SIM-NEW-001",
"product_id": 50701,
"auto_confirm": true,
"callback_url": "https://callback.example.com"
}Field Descriptions:
| Field Path | Description | Example |
|---|---|---|
external_id | Unique ID per request generated from customer side. | "SIM-NEW-001" |
product_id | ID of the product to be purchased. | 50701 |
auto_confirm | Specify if the transaction will be generated in one or two steps. | true |
callback_url | Callback URL or Webhook provided by the customer. DT One sends status updates to this URL. | "https://callback.example.com" |
Response for POST: Create a transaction asynchronously
{
"benefits": [
{
"additional_information": null,
"amount": {
"base": 1,
"promotion_bonus": 0,
"total_excluding_tax": 1,
"total_including_tax": 1
},
"type": "DATA",
"unit": "GB",
"unit_type": "DATA"
}
],
"callback_url": "https://callback.example.com",
"confirmation_date": "2025-04-09T22:04:27.760931000Z",
"confirmation_expiration_date": "2025-04-09T23:04:27.520011000Z",
"creation_date": "2025-04-09T22:04:27.520011000Z",
"external_id": "SIM-NEW-001",
"id": 2239249454,
"prices": {
"retail": null,
"wholesale": {
"amount": 3.49,
"fee": 0,
"unit": "USD",
"unit_type": "CURRENCY"
}
},
"product": {
"description": "1 GB 7 days Europe Extended",
"id": 50701,
"name": "1 GB 7 days Europe Extended",
"service": {
"id": 13,
"name": "eSIM",
"subservice": null
},
"tags": null,
"type": "FIXED_VALUE_PIN_PURCHASE"
},
"promotions": null,
"rates": {
"base": 1.14613180515759,
"retail": -1,
"wholesale": 1.14613180515759
},
"status": {
"class": {
"id": 2,
"message": "CONFIRMED"
},
"id": 20000,
"message": "CONFIRMED"
}
}Descriptions of Important Fields:
| Field Path | Description | Example |
|---|---|---|
id | Unique ID for the transaction generated by DT One. Use this to query the transaction later. | 2239249454 |
external_id | Unique ID per request generated from the customer side. | "SIM-NEW-001" |
creation_date | Date and time when the transaction was created. | "2025-04-09T22:04:27.520011000Z" |
confirmation_date | Date and time when the transaction was confirmed. | "2025-04-09T22:04:27.760931000Z" |
prices.wholesale.amount | Amount deducted from the initiator's wallet. | 3.49 |
product.type | Product type of the purchased product. | "FIXED_VALUE_PIN_PURCHASE" |
status.class.id | Class ID for the current transaction status. | 2 |
status.class.message | Class description for the current transaction status. | "CONFIRMED" |
status.id | Status ID for the current transaction. | 20000 |
status.message | Description of the current transaction status. | "CONFIRMED" |
Disclaimer
Example field values in response JSON files are significant for format and type only. Do not interpret them as actual data; prices, for example, are invented and non-binding.
To post a transaction for recharging an existing SIM, you use the POST: Create a transaction asynchronously endpoint.
Implementation Techniques
Technique 1: One-Step Transaction
Create and confirm the transaction in one step.
{
"external_id": "SIM-RECHARGE-001",
"product_id": 67890,
"auto_confirm": true,
"callback_url": "https://callback.example.com",
"credit_party_identifier": {
"account_number": "1234567890"
}
}Explanation:
By setting auto_confirm to true, the transaction is created and confirmed immediately.
Technique 2: Two-Step Transaction
Create the transaction, then confirm it separately. When auto_confirm is set to false (or not specified):
- A separate POST request to Confirm a transaction asynchronously is required.
- This allows for a delay between transaction creation and submission to DT One, useful for:
- Collecting payment.
- Verifying RANGED product type prices.
Important:
- The maximum time allowed between the CREATED (1) and CONFIRMED (2) statuses is 60 minutes.
- Transactions not confirmed within 60 minutes will be automatically canceled.
{
"external_id": "SIM-RECHARGE-001",
"product_id": 67890,
"auto_confirm": false,
"callback_url": "https://callback.example.com",
"credit_party_identifier": {
"account_number": "1234567890"
}
}Statuses for Transactions
For even more detailed information, see Handling Transactions.
---
config:
theme: neutral
fontSize: 16
look: neo
layout: fixed
---
flowchart LR
B@{ label: "<b>CREATED</b><br><span style=\"font-size: 2em;\">1</span>" } -- "<span style=color:>POST<br>/transactions<br>/[id]<br>/confirm</span>" --> C@{ label: "<b>CONFIRMED</b><br><span style=\"font-size: 2em;\">2</span>" }
C -- "<span style=color:>Sent to<br>receiving<br>partner</span>" --> D@{ label: "<b>SUBMITTED</b><br><span style=\"font-size: 2em;\">5</span>" }
D --> E@{ label: "<b>COMPLETED</b><br><span style=\"font-size: 2em;\">7</span>" }
E -- "<span style=color:>Callback</span>" --> F@{ label: "<b>REVERSED</b><br><span style=\"font-size: 2em;\">8</span>" }
B -- "<span style=color:>Callback</span>" --> G@{ label: "<b>REJECTED</b><br><span style=\"font-size: 2em;\">3</span>" }
B -- "<span style=color:>Callback<br>POST<br>/transactions<br>/[id]<br>/cancel</span>" --> H@{ label: "<b>CANCELLED</b><br><span style=\"font-size: 2em;\">4</span>" }
D -- "<span style=color:>Callback</span>" --> I@{ label: "<b>DECLINED</b><br><span style=\"font-size: 2em;\">9</span>" }
B@{ shape: rounded}
C@{ shape: rounded}
D@{ shape: rounded}
E@{ shape: rounded}
F@{ shape: rounded}
G@{ shape: rounded}
H@{ shape: rounded}
I@{ shape: rounded}
style B fill:#FFFFFF,stroke:#1D8DF0,stroke-width:3px
style C fill:#FFFFFF,stroke:#1D8DF0,stroke-width:3px
style D fill:#FFFFFF,stroke:#1D8DF0,stroke-width:3px
style E fill:#FFFFFF,color:#000,stroke:#90ee90,stroke-width:3px
style F fill:#FFFFFF,stroke:black,stroke-width:3px
style G fill:#FFFFFF,stroke:#f08080,stroke-width:3px
style H fill:#FFFFFF,stroke:#f08080,stroke-width:3px
style I fill:#FFFFFF,stroke:#f08080,stroke-width:3px
A final status is a status after which there are no further statuses.
Only COMPLETED 7, REJECTED 3, CANCELLED 4, and DECLINED 9 are final statuses. SUBMITTED 5 and CONFIRMED 2 are NOT final statuses.
- Transaction reachesSUBMITTED 5 status.
- An immediate hold is placed on the initiator’s wallet for the wholesale price of the product.
- If Status changes toCOMPLETED 7
- The wholesale price is deducted from the wallet.
- If Status remainsSUBMITTED 5
- The balance remains on hold.
- If Status changes toREVERSED 8, REJECTED 3, or DECLINED 9
- The hold is released, and the wallet balance is adjusted accordingly.
Minimum Payload Request for POST: Create a transaction asynchronously
{
"external_id": "SIM-RECHARGE-001",
"product_id": 67890,
"auto_confirm": true,
"callback_url": "https://callback.example.com",
"credit_party_identifier": {
"account_number": "1234567890"
}
}Field Descriptions:
| Field Path | Description | Example |
|---|---|---|
external_id | Unique ID per request generated from customer side. | "SIM-RECHARGE-001" |
product_id | ID of the product to be purchased. | 67890 |
auto_confirm | Specify if the transaction will be generated in one or two steps. | true |
callback_url | Callback URL or Webhook provided by the customer. DT One sends status updates to this URL. | "https://callback.example.com" |
credit_party_identifier | in case of eSIM send ICCID of the user’s eSIM (Note that the ICCID is sent back with transaction status in the PIN.Serial field of the Callback or when querying transactions through the API and/or viewing transaction details in DT Shop). ICCID can also be found on the user device under eSIM settings. | { "account_number": "1234567890" } |
Response for POST: Create a transaction asynchronously
{
"benefits": [
{
"additional_information": null,
"amount": {
"base": 1,
"promotion_bonus": 0,
"total_excluding_tax": 1,
"total_including_tax": 1
},
"type": "DATA",
"unit": "GB",
"unit_type": "DATA"
}
],
"callback_url": "https://callback.example.com",
"confirmation_date": "2025-04-09T22:04:27.760931000Z",
"confirmation_expiration_date": "2025-04-09T23:04:27.520011000Z",
"creation_date": "2025-04-09T22:04:27.520011000Z",
"credit_party_identifier": {
"account_number": "1234567890"
},
"external_id": "SIM-RECHARGE-001",
"id": 2239249455,
"prices": {
"retail": null,
"wholesale": {
"amount": 3.49,
"fee": 0,
"unit": "USD",
"unit_type": "CURRENCY"
}
},
"product": {
"description": "1 GB 7 days Europe Extended",
"id": 67890,
"name": "1 GB 7 days Europe Extended",
"service": {
"id": 13,
"name": "eSIM",
"subservice": null
},
"tags": null,
"type": "FIXED_VALUE_PIN_PURCHASE"
},
"promotions": null,
"rates": {
"base": 1.14613180515759,
"retail": -1,
"wholesale": 1.14613180515759
},
"status": {
"class": {
"id": 2,
"message": "CONFIRMED"
},
"id": 20000,
"message": "CONFIRMED"
}
}Descriptions of Important Fields:
| Field Path | Description | Example |
|---|---|---|
id | Unique ID for the transaction generated by DT One. Use this to query the transaction later. | 2239249455 |
external_id | Unique ID per request generated from the customer side. | "SIM-RECHARGE-001" |
credit_party_identifier.account_number | ICCID of the eSIM being recharged, echoed back from the request. | "1234567890" |
creation_date | Date and time when the transaction was created. | "2025-04-09T22:04:27.520011000Z" |
confirmation_date | Date and time when the transaction was confirmed. | "2025-04-09T22:04:27.760931000Z" |
prices.wholesale.amount | Amount deducted from the initiator's wallet. | 3.49 |
product.type | Product type of the purchased product. | "FIXED_VALUE_PIN_PURCHASE" |
status.class.id | Class ID for the current transaction status. | 2 |
status.class.message | Class description for the current transaction status. | "CONFIRMED" |
status.id | Status ID for the current transaction. | 20000 |
status.message | Description of the current transaction status. | "CONFIRMED" |
Disclaimer
Example field values in response JSON files are significant for format and type only. Do not interpret them as actual data; prices, for example, are invented and non-binding.
Example Status Retrieval
Technique 1: Callback
Provide the callback_url (described in Step 2. Post Transactions) in the transaction request to receive asynchronous status updates.
Technique 2: Query the transaction using an ID
Use one of the following endpoints:
-
GET: Query a list of transactions
Can be used to look up the transaction using the External ID generated by the customer side (as well as to query a list).
-
GET: Query a transaction by ID
Look up the transaction using the Transaction ID that DT One generated.
We recommend using Technique 1: Callback and - in parallel - using Technique 2: Query the transaction using an ID as a backup plan.
If you cannot use Technique 1: Callback, you must use Technique 2: Query the transaction using an ID.
{
"benefits": [
{
"additional_information": null,
"amount": {
"base": 1,
"promotion_bonus": 0,
"total_excluding_tax": 1,
"total_including_tax": 1
},
"type": "DATA",
"unit": "GB",
"unit_type": "DATA"
}
],
"callback_url": "https://testcallbackurl.com/",
"confirmation_date": "2025-04-09T22:04:27.760931000Z",
"confirmation_expiration_date": "2025-04-09T23:04:27.520011000Z",
"creation_date": "2025-04-09T22:04:27.520011000Z",
"external_id": "TEST-000008",
"id": 2239249454,
"metadata": {
"type": "ESIM",
"activation_type": "DATA_PLAN",
"balance": {
"size": {
"amount": 1,
"unit": "GB"
},
"validity": {
"quantity": 7,
"unit": "DAY"
},
"country_set": "EXX",
"extended_data_policy": {
"type": "STANDARD"
}
},
"profile": {
"iccid": "5865151648338875078",
"activation_code": "LPA:1$smdp.io$K2-27D7HN-IP0UJ1",
"apple_universal_link": "https://esimsetup.apple.com/esim_qrcode_provisioning?carddata=LPA:1$smdp.io$K2-27D7HN-IP0UJ1",
"android_universal_link": "https://esimsetup.android.com/switch?carddata=LPA:1$smdp.io$K2-27D7HN-IP0UJ1",
"installation_url": "https://esim.dtone.com/install?carddata=LPA:1$smdp.io$K2-27D7HN-IP0UJ1"
}
},
"operator_reference": "TX_2239249454",
"pin": {
"code": "LPA:1$smdp.io$K2-27D7HN-IP0UJ1",
"serial": "5865151648338875078"
},
"prices": {
"retail": null,
"wholesale": {
"amount": 3.49,
"fee": 0,
"unit": "USD",
"unit_type": "CURRENCY"
}
},
"product": {
"description": "1 GB 7 days Europe Extended",
"id": 50701,
"name": "1 GB 7 days Europe Extended",
"operator": {
"country": {
"iso_code": "EXX",
"name": "Europe",
"regions": [
{
"code": "ALB",
"name": "Albania"
},
{
"code": "AND",
"name": "Andorra"
},
{
"code": "AUT",
"name": "Austria"
}...
]
},
"id": 4919,
"name": "eSIM Europe",
"regions": [
{
"code": "ALB",
"name": "Albania"
},
{
"code": "AND",
"name": "Andorra"
},
{
"code": "AUT",
"name": "Austria"
}...
]
},
"pin": {
"terms": null,
"usage_info": [
"After buying, you'll get a QR Code. Scan it to install the eSIM profile. When you arrive at your destination, remember to turn on data roaming in your device settings."
],
"validity": {
"quantity": 365,
"unit": "DAY"
}
},
"regions": [
{
"code": "ALB",
"name": "Albania"
},
{
"code": "AND",
"name": "Andorra"
},
{
"code": "AUT",
"name": "Austria"
}...
],
"service": {
"id": 13,
"name": "eSIM",
"subservice": null
},
"tags": null,
"type": "FIXED_VALUE_PIN_PURCHASE"
},
"promotions": null,
"rates": {
"base": 1.14613180515759,
"retail": -1,
"wholesale": 1.14613180515759
},
"status": {
"class": {
"id": 7,
"message": "COMPLETED"
},
"id": 70000,
"message": "COMPLETED"
}
}The pin object
pin objectpin.code: The activation code (an LPA: string). Convert it into a QR code for scan-to-install, and also present it as copyable text so your end user can install the eSIM manually.
pin.serial: Contains the ICCID. This identifier is used for follow-up features such as eSIM top-up (recharge) and eSIM balance retrieval.
"pin": {
"code": "LPA:1$smdp.io$K2-27D7HN-IP0UJ1",
"serial": "5865151648338875078"
}The metadata object (eSIM)
metadata object (eSIM)From v1.23.0, a completed eSIM transaction also returns a metadata object. When metadata.type is ESIM, it carries structured eSIM details — the activation profile with ready-to-use installation links, plus the activated data balance — so you no longer need to hand-build install URLs from the raw activation code.
"metadata": {
"type": "ESIM",
"activation_type": "DATA_PLAN",
"balance": {
"size": { "amount": 1, "unit": "GB" },
"validity": { "quantity": 7, "unit": "DAY" },
"country_set": "EXX",
"extended_data_policy": { "type": "STANDARD" }
},
"profile": {
"iccid": "5865151648338875078",
"activation_code": "LPA:1$smdp.io$K2-27D7HN-IP0UJ1",
"apple_universal_link": "https://esimsetup.apple.com/esim_qrcode_provisioning?carddata=LPA:1$smdp.io$K2-27D7HN-IP0UJ1",
"android_universal_link": "https://esimsetup.android.com/switch?carddata=LPA:1$smdp.io$K2-27D7HN-IP0UJ1",
"installation_url": "https://esim.dtone.com/install?carddata=LPA:1$smdp.io$K2-27D7HN-IP0UJ1"
}
}| Field Path | Description | Example |
|---|---|---|
metadata.type | Discriminator for the metadata shape. ESIM indicates the eSIM-specific structure documented here. | "ESIM" |
metadata.activation_type | The kind of activation performed. DATA_PLAN for a new eSIM purchase (a profile is issued); TOP_UP when recharging an existing eSIM (no new profile). | "DATA_PLAN" |
metadata.balance.size | Total data size of the activated package (amount + unit, where unit is one of TB, GB, MB, KB, B). | { "amount": 1, "unit": "GB" } |
metadata.balance.validity | Validity period of the package (quantity + unit, where unit is one of YEAR, MONTH, WEEK, DAY, HOUR, MINUTE, SECOND). | { "quantity": 7, "unit": "DAY" } |
metadata.balance.country_set | Coverage code for the package (e.g. WWW for worldwide, EXX for Europe). | "EXX" |
metadata.balance.extended_data_policy.type | Package type: STANDARD (fixed data allowance) or UNLIMITED (high-speed volume then throttling). Additional throttling fields are returned for UNLIMITED. | "STANDARD" |
metadata.profile.iccid | Integrated Circuit Card Identifier of the issued eSIM. Same value as pin.serial; use it for balance retrieval and future top-ups. | "5865151648338875078" |
metadata.profile.activation_code | QR-code content for eSIM installation (the LPA: string). Same value as pin.code. | "LPA:1$smdp.io$K2-27D7HN-IP0UJ1" |
metadata.profile.apple_universal_link | Universal link that installs the eSIM directly on Apple (iOS) devices. Present it as a tappable button in your iOS flow. | "https://esimsetup.apple.com/…" |
metadata.profile.android_universal_link | Universal link that installs the eSIM directly on Android devices. Present it as a tappable button in your Android flow. | "https://esimsetup.android.com/…" |
metadata.profile.installation_url | Generic installation URL for the eSIM. Use it as a device-agnostic fallback when you cannot detect the end user's platform. | "https://esim.dtone.com/install?…" |
profileis only present forDATA_PLANactivations. ForTOP_UP(recharge) transactions themetadata.profileobject is not returned, because no new eSIM profile is issued — the existing eSIM identified by its ICCID simply receives the additional data.metadata.type,metadata.activation_type, andmetadata.balanceare always returned.
Delivering the eSIM to your user. Prefer the ready-made links in metadata.profile — hand apple_universal_link to iOS users and android_universal_link to Android users for one-tap installation, and fall back to installation_url when the platform is unknown. Always also render activation_code as a QR code and as copyable text so users can install manually if the deep link fails.
Disclaimer
Example field values in response JSON files are significant for format and type only. Do not interpret them as actual data; prices, for example, are invented and non-binding.
4.1. Ad-Hoc eSIM Balance Retrieval
Enables user flow when users can request their remaining data balance at any time.
Request
{
"service_id": 13,
"credit_party_identifier": {
"account_number": "5865151648338875078"
}
}Descriptions of Important Fields:
| Field Path | Description | Example |
|---|---|---|
service_id | Service ID, in this case eSIM. | 13 |
account_number | in case of eSIM send ICCID of the user’s eSIM (Note that the ICCID is sent back with transaction status in the PIN.Serial field of the Callback or when querying transactions through the API and/or viewing transaction details in DT Shop). ICCID can also be found on the user device under eSIM settings.. | "5865151648338875078" |
Response (Relevant Fields)
[
{
"amount": 1,
"expiration_date": null,
"type": "DATA",
"unit": "GB",
"unit_type": "DATA"
}
]Updated 25 days ago