> **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. For full endpoint descriptions, see: * **GET**: [Retrieve product by ID](/reference/getproductbyid) * **GET**: [Retrieve list of products](/reference/getproducts) ```json Retrieve product by ID GET /products/50701 ``` ```json Response to Retrieve product by ID { "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" } ``` 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., **MXN** 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: ```json Global Coverage GET /products?service_id=13&country_iso_code=GXX // Retrieves all products with global coverage (available worldwide). ``` ```json Europe Coverage GET /products?service_id=13&country_iso_code=EXX // Retrieves all products with coverage in the Europe region. ``` ```json Mexico Coverage GET /products?service_id=13&country_iso_code=MXN // Retrieves all products with coverage specific to Mexico. ``` 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. ```json Example "required_*" field configuration "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": null ``` In 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. ```json Request Payload needed for Example { "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: ```json pin field "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. #### Technique 1: One-Step Transaction Create and confirm the transaction in one step. ```json Create and confirm 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": "john.doe@example.com", "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. ```json auto_confirm set to false { "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": "john.doe@example.com", "phone_number": "+1234567890" } } ``` For even more detailed information, see [Handling Transactions](/docs/handling-transactions-r-for-review-copy#/). ```mermaid --- config: theme: neutral fontSize: 16 look: neo layout: fixed --- flowchart LR B@{ label: "CREATED
1" } -- "POST
/transactions
/[id]
/confirm" --> C@{ label: "CONFIRMED
2" } C -- "Sent to
receiving
partner" --> D@{ label: "SUBMITTED
5" } D --> E@{ label: "COMPLETED
7" } E -- "Callback" --> F@{ label: "REVERSED
8" } B -- "Callback" --> G@{ label: "REJECTED
3" } B -- "Callback
POST
/transactions
/[id]
/cancel" --> H@{ label: "CANCELLED
4" } D -- "Callback" --> I@{ label: "DECLINED
9" } 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.

###### **COMPLETED 7** The digital value service has been delivered. In rare cases, a successfully completed transaction can be reversed and assigned a **REVERSED 8** status (so the definition for "Final Status" is applicable almost always.).

###### **REJECTED 3** The transaction was unsuccessful on DT One’s side.

###### **CANCELLED 4** The transaction was canceled by the initiator before confirmation.

###### **DECLINED 9** The transaction was unsuccessful on the provider’s side.

###### **REJECTED 3** The transaction was unsuccessful on DT One’s side.

###### **CANCELLED 4** The transaction was canceled by the initiator before confirmation.

###### **DECLINED 9** The transaction was unsuccessful on the provider’s side.

* **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. ```json Minimum Payload { "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" }` | ```json Response { "transaction_id": "123456789", "status": "CREATED", "message": "Transaction created successfully", "details": { "amount": 20, "currency": "USD", "product_id": 67890 } } ``` **Descriptions of Important Fields:** | Field Path | Description | Example | | -------------------- | ------------------------------------------------------ | ------------------------------------ | | `transaction_id` | Unique ID for the transaction generated by the system. | `"123456789"` | | `status` | Current status of the transaction. | `"CREATED"` | | `message` | Message indicating the result of the transaction. | `"Transaction created successfully"` | | `details.amount` | Amount of the transaction. | `20` | | `details.currency` | Currency of the transaction. | `"USD"` | | `details.product_id` | ID of the product being purchased. | `67890` | > **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**. ```json Response (for either query) { "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, "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" } } ``` **PIN.code:** Activation code, which not only needs to be converted into a QR code but also should be easily copyable by your end user for manual eSIM installation processes. **PIN.serial:** Contains the ICCID. This identifier will be used for features like eSIM top-up and eSIM balance retrieval ``` "pin": { "code": "LPA:1$smdp.io$K2-27D7HN-IP0UJ1", "serial": "5865151648338875078" } ``` To enable quick install, use the universal link: [https://esimsetup.apple.com/esim\_qrcode\_provisioning?carddata=eSIMcode}}](https://esimsetup.apple.com/esim_qrcode_provisioning?carddata=eSIMcode}}) **Example** [https://esimsetup.apple.com/esim\_qrcode\_provisioning?carddata=LPA:1$smdp.io$K2-27D7HN-IP0UJ1](https://esimsetup.apple.com/esim_qrcode_provisioning?carddata=LPA:1$smdp.io$K2-27D7HN-IP0UJ1) > **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" } ] ```