--- updatedAt: 2026-07-26T19:25:06.000Z agentTools: projectIndex: https://developers.dtone.com/llms.txt --- # eSIM: Top-Up an Existing 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. A **top-up** (also called a *recharge*) adds a new data package to an eSIM that the end user has **already installed** — no new eSIM profile is issued. It uses the same `FIXED_VALUE_PIN_PURCHASE` product type and the same **POST**: Create a transaction asynchronously endpoint as a new eSIM purchase. #### What decides "top-up" vs. "new purchase" The **presence of an ICCID** in the request is the only switch: | You send… | DT One performs | New profile issued? | | ------------------------------------------------ | ---------------------- | ------------------- | | `credit_party_identifier.account_number` (ICCID) | **Top-up** (recharge) | No | | *(no ICCID)* | **New eSIM purchase** | Yes | When you include the ICCID in `credit_party_identifier.account_number`, the existing eSIM is reloaded with the selected plan. When you omit it, a brand-new eSIM is ordered and an activation profile is returned instead (see [eSIM: FIXED_VALUE_PIN_PURCHASE](/docs/esim-fixed_value_pin_purchase#/)). #### Where to find the ICCID The ICCID is returned when the eSIM is first purchased, in the completed transaction's `pin.serial` field (and, from **v1.23.0**, in `metadata.profile.iccid`). It is also available in the transaction status callback and in DT Shop, and can be found on the end user's device under **eSIM settings**. > **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 top up an existing eSIM, call the **POST**: Create a transaction asynchronously endpoint with the target plan's `product_id` and the eSIM's ICCID in `credit_party_identifier.account_number`. #### Technique 1: One-Step Transaction Create and confirm the transaction in one step. ```json Create and confirm in one step { "external_id": "ESIM-TOPUP-001", "product_id": 67890, "auto_confirm": true, "callback_url": "https://callback.example.com", "credit_party_identifier": { "account_number": "8948010000074885468" } } ``` **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 first. **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": "ESIM-TOPUP-001", "product_id": 67890, "auto_confirm": false, "callback_url": "https://callback.example.com", "credit_party_identifier": { "account_number": "8948010000074885468" } } ``` ```json Minimum Payload { "external_id": "ESIM-TOPUP-001", "product_id": 67890, "auto_confirm": true, "callback_url": "https://callback.example.com", "credit_party_identifier": { "account_number": "8948010000074885468" } } ``` **Field Descriptions:** | Field Path | Description | Example | | ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------ | | `external_id` | Unique ID per request generated from the customer side. | `"ESIM-TOPUP-001"` | | `product_id` | ID of the data plan to load onto the existing eSIM. | `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.account_number` | **The ICCID of the eSIM being topped up.** Including it is what makes this a top-up rather than a new purchase. The ICCID is returned on the original purchase (`pin.serial` / `metadata.profile.iccid`) and is on the device under eSIM settings. | `"8948010000074885468"` | A top-up follows the same transaction lifecycle as any other DVS transaction — **CREATED → CONFIRMED → SUBMITTED → COMPLETED** — with the same wallet effects (a hold is placed at SUBMITTED and the wholesale price is deducted at COMPLETED). For the full status diagram, final-status definitions, and wallet effects, see the [eSIM: FIXED_VALUE_PIN_PURCHASE](/docs/esim-fixed_value_pin_purchase#/) guide and [Handling Transactions](/docs/handling-transactions#/). > **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. Retrieve the final status either via your `callback_url` or by querying the transaction (**GET**: Query a transaction by ID / Query a list of transactions), exactly as for a new eSIM purchase. A key difference from a new purchase: **a top-up does not issue a new eSIM profile.** The completed transaction therefore does **not** contain a new `pin.code` (activation code) or a `metadata.profile` object — the existing eSIM simply receives the additional data. The `metadata` object confirms the recharge with `activation_type: TOP_UP` and reports the newly activated `balance`. ```json Response (COMPLETED top-up) { "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": "8948010000074885468" }, "external_id": "ESIM-TOPUP-001", "id": 2239249455, "metadata": { "type": "ESIM", "activation_type": "TOP_UP", "balance": { "size": { "amount": 1, "unit": "GB" }, "validity": { "quantity": 7, "unit": "DAY" }, "country_set": "EXX", "extended_data_policy": { "type": "STANDARD" } } }, "operator_reference": "TX_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": 7, "message": "COMPLETED" }, "id": 70000, "message": "COMPLETED" } } ``` **Descriptions of Important Fields:** | Field Path | Description | Example | | ---------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------- | | `id` | Unique ID for the transaction generated by DT One. | `2239249455` | | `external_id` | Unique ID per request generated from the customer side. | `"ESIM-TOPUP-001"` | | `credit_party_identifier.account_number` | The ICCID that was topped up, echoed back from the request. | `"8948010000074885468"` | | `prices.wholesale.amount` | Amount deducted from the initiator's wallet at COMPLETED. | `3.49` | | `metadata.type` | Metadata discriminator; `ESIM` for the eSIM structure. | `"ESIM"` | | `metadata.activation_type` | `TOP_UP` confirms this transaction recharged an existing eSIM (a new purchase would report `DATA_PLAN`). | `"TOP_UP"` | | `metadata.balance.size` | Total data size added by the top-up (`amount` + `unit`). | `{ "amount": 1, "unit": "GB" }` | | `metadata.balance.validity` | Validity period of the topped-up package (`quantity` + `unit`). | `{ "quantity": 7, "unit": "DAY" }` | | `metadata.balance.country_set` | Coverage code for the package (e.g. `WWW` worldwide, `EXX` Europe). | `"EXX"` | | `status.class.id` / `status.id` | Transaction status. `7` / `70000` = **COMPLETED**. | `7` / `70000` | > **No `metadata.profile` on a top-up.** Because no new eSIM profile is created, the completed top-up omits `metadata.profile` (and its `activation_code`, `iccid`, and installation links) as well as the top-level `pin.code`. The end user keeps using the eSIM they already installed. Only `metadata.type`, `metadata.activation_type`, and `metadata.balance` are guaranteed. > **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. After a top-up completes, you can confirm the eSIM's remaining data at any time by querying its balance with the ICCID — the same ad-hoc balance retrieval used for a newly purchased eSIM. **Request** ```json Request { "service_id": 13, "credit_party_identifier": { "account_number": "8948010000074885468" } } ``` | Field Path | Description | Example | | ---------------- | ------------------------------------------------------------------ | ----------------------- | | `service_id` | Service ID, in this case eSIM. | `13` | | `account_number` | ICCID of the eSIM whose balance you are retrieving. | `"8948010000074885468"` | **Response (Relevant Fields)** ```json Response [ { "amount": 1, "expiration_date": null, "type": "DATA", "unit": "GB", "unit_type": "DATA" } ] ``` For the full balance-retrieval flow, see the **Get eSIM Balance** tab of the [eSIM: FIXED_VALUE_PIN_PURCHASE](/docs/esim-fixed_value_pin_purchase#/) guide.