> ## Documentation Index
> Fetch the complete documentation index at: https://boxo.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# eSIM Integration

## Boxo Platform and Boxo SDK

In this section we will look at some additional integration details (such as user's locale) when working with Boxo Platform and Boxo SDK.

### Payment Payload

Here is the payload that Boxo will send via platform to host app backend.

```json theme={"system"}
{
  "currency": "CAD",
  "amount": "20.00",
  "subtotal_amount": "20.00",
  "shipping_amount": "0.00",
  "discount_amount": "0.00",
  "tax_title": "",
  "tax_amount": "5.00",
  "taxes_included": false,
  "note": "",
  "miniapp_order_id": "5b2f4d08-9081-4665-9eb1-325419310d4e",
  "hostapp_user_id": "5b2f4d08-9081-4665-9eb1-325419310d4e",
  "custom_attributes": {
    "location": {
      "id": "8c467680-6d9a-4eca-9f43-b1da9be44ecf",
      "code": "ES",
      "title": "Spain",
      "type": "COUNTRY",
      "is_global": false
    },
    "provider_net_price": {
      "amount": "10.00",
      "currency": "CAD"
    },
    "data": 1024,
    "duration": 7,
    "order_type": "ACTIVATION"
  }
}
```

### Locale

Host app can provide language during initial launch and miniapp will be able to retrieve latest language settings.

```kotlin theme={"system"}
Appboxo.setConfig(Config.Builder().setClientId().setLanguage("en").build()))
```

### Closing miniapp and landing on Home page on next launch

In order to land on Home page each time miniapp is closed and reopened, a `saveState=false` can be passed. This behavior is available in versions starting from `v0.1.4`.

For example:

```kotlin theme={"system"}
Appboxo.openMiniapp({ appId: appId, saveState: false });
```

### Deeplinks

The deeplink URL should include miniapp id and the relevant URL route, if needed to land user on a specific page.

User will first deeplink to host app, then in host app it parses the deeplink and obtains the miniapp ID and the path to the page.

**Open the homepage of the miniapp**

```kotlin theme={"system"}
const appId = "<app_id>"  // Get miniapp appId from deeplink
Appboxo.closeMiniapp({ appId: appId });
Appboxo.openMiniapp({ appId: appId, saveState: false });
```

**Open a specific page within the miniapp**

```kotlin theme={"system"}
const appId = "<app_id>"  // Get miniapp appId from deeplink
Appboxo.closeMiniapp({ appId: appId });
Appboxo.openMiniapp({ appId: appId, data: {'deeplink': '/help'}, saveState: false });
// Deeplink contains root slash, path and query params. Example: '/path?id=123'
```

### Hide About from Menu

Available from SDK version `v0.1.6` (Capacitor v5) and `v0.2.4` (Capacitor v6).

```kotlin theme={"system"}
Appboxo.setConfig({ clientId: clientId, showAboutPage: false }); // By default showAboutPage is true
```

### Returning user who has NOT purchased an eSIM will launch into Explore page. Otherwise, will launch Homepage

```kotlin theme={"system"}
Appboxo.openMiniapp({ appId: appId, saveState: false, data: {havePurchasedSims: false } });
```

### Caching

Miniapp config is cached for 60 seconds. Logo and other related miniapp configuration changes should be reflected on next launch after 60 seconds have passed.

### Android compatibility check enhancement

Available from SDK version `v0.3.0` for Capacitor v6.

Instead of performing model check against a compatible device list, Android SDK will perform eSIM compatibility check using native method and pass on the result to eSIM miniapp.

The feature is supported inside the SDK, no code change needed on host app side.

## iOS direct installation

Here is an example of implementation of eSIM direct installation, sample code is also available [here](https://github.com/Appboxo/esim-direct-install).

```swift theme={"system"}
// JS SDK call AppBoxoEsimDirectInstall with direct install URL parameter
// SDK will check iOS version and open given URL
if #available(iOS 17.4, *) {
    guard let url = URL(string: url) else { return }

    if UIApplication.shared.canOpenURL(url) {
      UIApplication.shared.open(url)
    }
}
```

## Capacitor plugin

Capacitor plugin can be downloaded [here](https://www.npmjs.com/package/@appboxo/capacitor-boxo-sdk). Example code reference can be viewed [here](https://github.com/Appboxo/capacitor-appboxo-sdk/tree/main/example). Latest version: `v0.1.1` (includes changes to support play instruction video on Install Now page).

## Webhooks

Here are examples payloads for various webhooks that eSIM Miniapp BE will send, if you have provided use with the webhook URL.

eSIM backend will use `hostapp_client_id` and `hostapp_client_secret` configured in Boxo Platform and they will be passed as basic auth in `Authorization` header along with all requests. You can use this implement authentication for your webhook endpoint.

### eSIM order success

This event is fired when user successfully purchases a new eSIM or tops up existing eSIM.

```json theme={"system"}
{
  "event_type": "order.completed",
  "app_id": "app_XXXXXX",
  "client_id": "host_XXXXXXXXXXXX",
  "payload": {
    "id": "6168918c-befc-46c4-9f2c-ca84c898bcf7",
    "external_source_payment_id": "261ba7b4-a578-451a-a05a-7ee26ba36e65",
    "order_type": "TOP_UP",
    "user_id": "eb275a7f-3b4c-4c35-881c-f5535d509202",
    "plan": {
      "id": "1bcc2d27-1863-4ef1-8a82-4f292511f5a2",
      "title": "2 GB - 15 days",
      "location": {
        "id": "1e8ca9cd-1878-4d8b-9922-d0c57aeaf717",
        "code": "AE",
        "title": "United Arab Emirates",
        "type": "COUNTRY",
        "is_global": false
      }
    },
    "sim": {
      "id": "26a275d1-356d-4f59-92f7-640aded2c5ae",
      "iccid": "8900000261135167972"
    },
    "provider_net_local_price": {
      "amount": "10.00",
      "currency": "USD"
    },
    "subtotal": {
      "amount": "10.00",
      "currency": "USD"
    },
    "tax": {
      "amount": "0.00",
      "currency": "KZT"
    },
    "total": {
      "amount": "10.00",
      "currency": "USD"
    }
  }
}
```

### eSIM order failed

This event is fired when we were unable to fulfill given eSIM order. Hostapp can use it to initiate refund if this event is received. Can happen if eSIM is currently unavailable or eSIM provider is not available at given moment.

```json theme={"system"}
{
  "event_type": "order.failed",
  "app_id": "app_XXXXXX",
  "client_id": "host_XXXXXXXXXXXX",
  "payload": {
    "id": "6168918c-befc-46c4-9f2c-ca84c898bcf7",
    "external_source_payment_id": "261ba7b4-a578-451a-a05a-7ee26ba36e65",
    "order_type": "TOP_UP",
    "user_id": "eb275a7f-3b4c-4c35-881c-f5535d509202",
    "plan": {
      "id": "1bcc2d27-1863-4ef1-8a82-4f292511f5a2",
      "title": "2 GB - 15 days",
      "location": {
        "id": "1e8ca9cd-1878-4d8b-9922-d0c57aeaf717",
        "code": "AE",
        "title": "United Arab Emirates",
        "type": "COUNTRY",
        "is_global": false
      }
    },
    "sim": null,
    "provider_net_local_price": {
      "amount": "10.00",
      "currency": "USD"
    },
    "subtotal": {
      "amount": "10.00",
      "currency": "USD"
    },
    "tax": {
      "amount": "0.00",
      "currency": "KZT"
    },
    "total": {
      "amount": "10.00",
      "currency": "USD"
    }
  }
}
```

### eSIM order expired

This event is fired when if order hasn't been marked as completed / failed by the hostapp within 15 minutes of order creation. All orders in pending status get automatically cancelled after 15 minutes if no final status (paid or failed) received from the hostapp.

```json theme={"system"}
{
  "event_type": "order.expired",
  "app_id": "app_XXXXXX",
  "client_id": "host_XXXXXXXXXXXX",
  "payload": {
    "id": "6168918c-befc-46c4-9f2c-ca84c898bcf7",
    "external_source_payment_id": "261ba7b4-a578-451a-a05a-7ee26ba36e65",
    "order_type": "TOP_UP",
    "user_id": "eb275a7f-3b4c-4c35-881c-f5535d509202",
    "plan": {
      "id": "1bcc2d27-1863-4ef1-8a82-4f292511f5a2",
      "title": "2 GB - 15 days",
      "location": {
        "id": "1e8ca9cd-1878-4d8b-9922-d0c57aeaf717",
        "code": "AE",
        "title": "United Arab Emirates",
        "type": "COUNTRY",
        "is_global": false
      }
    },
    "sim": null,
    "provider_net_local_price": {
      "amount": "10.00",
      "currency": "USD"
    },
    "subtotal": {
      "amount": "10.00",
      "currency": "USD"
    },
    "tax": {
      "amount": "0.00",
      "currency": "KZT"
    },
    "total": {
      "amount": "10.00",
      "currency": "USD"
    }
  }
}
```

### eSIM activated

This event is fired when eSIM activates for the first time.

```json theme={"system"}
{
  "event_type": "sim.activated",
  "app_id": "app_XXXXXX",
  "client_id": "host_XXXXXXXXXXXX",
  "payload": {
    "id": "26a275d1-356d-4f59-92f7-640aded2c5ae",
    "iccid": "8900000261135167972",
    "expired": "2026-06-12T11:33:43Z",
    "user_id": "eb275a7f-3b4c-4c35-881c-f5535d509202",
    "activated": "2026-06-12T11:33:43Z",
    "data_total": 0,
    "subscriptions": [
      {
        "id": "77ada95e-ca4c-4b47-b772-42b61e105172",
        "plan": {
          "id": "73def29d-99b0-4370-9100-4321ee6faabd",
          "title": "Unlimited - 3 days"
        },
        "status": "ACTIVE",
        "data_remaining": 924
      }
    ],
    "data_remaining": 924
  }
}
```

### eSIM expired

This event is fired when eSIM has expired (data run out or it reached expiry date).

```json theme={"system"}
{
  "event_type": "sim.expired",
  "app_id": "app_XXXXXX",
  "client_id": "host_XXXXXXXXXXXX",
  "payload": {
    "id": "51a9e5f8-4962-4a40-8c3c-a8e2f641bfaf",
    "data": {
      "id": "95a20b92-12cf-434d-8998-23ee65944fb0",
      "iccid": "89424242426606109842",
      "expired": "2025-08-23T07:37:10Z",
      "user_id": "c671550c-88e9-4386-b072-70c9c378e40b",
      "activated": "2025-07-24T07:37:12Z",
      "data_total": 1024,
      "subscriptions": [
        {
          "id": "d11e8d86-9f46-4893-9d8c-eb9601b4d233",
          "plan": {
            "id": "8070b80e-61f9-419f-8711-543827e72b23",
            "title": "1 GB - 7 days"
          },
          "status": "EXPIRED",
          "data_remaining": 1024
        }
      ],
      "data_remaining": 1024
    },
    "type": "sim.expired",
    "created": "2025-08-23T07:50:09.387684Z"
  }
}
```

### eSIM data zero

This event is fired when eSIM data remaining reaches 0.

```json theme={"system"}
{
  "event_type": "sim.data_zero",
  "app_id": "app_XXXXXX",
  "client_id": "host_XXXXXXXXXXXX",
  "payload": {
    "id": "2699a0fa-d99b-443f-aa43-04e2dfc27856",
    "iccid": "8900000371411193282",
    "expired": "2026-06-05T08:30:46.581991Z",
    "user_id": "e0093bf4-6de7-4653-96c7-e6e10e77b3a6",
    "activated": "2026-06-09T14:23:16Z",
    "data_total": 0,
    "subscriptions": [
      {
        "id": "6c321664-cef9-4074-9331-8ec41cc6993d",
        "plan": {
          "id": "46cee6d0-7788-44ae-bd69-8a8e932b7ab9",
          "title": "1 GB - 7 days"
        },
        "status": "EXPIRED",
        "data_remaining": 0
      }
    ],
    "data_remaining": 0
  }
}
```

### eSIM data running low

This event is fired when eSIM data has been used 75% or 90%.

```json theme={"system"}
{
  "event_type": "sim.data_low",
  "app_id": "app_XXXXXX",
  "client_id": "host_XXXXXXXXXXXX",
  "payload": {
    "id": "2699a0fa-d99b-443f-aa43-04e2dfc27856",
    "iccid": "8900000371411193282",
    "expired": "2026-06-05T08:30:46.581991Z",
    "user_id": "e0093bf4-6de7-4653-96c7-e6e10e77b3a6",
    "activated": "2026-06-09T14:23:16Z",
    "data_total": 1024,
    "subscriptions": [
      {
        "id": "6c321664-cef9-4074-9331-8ec41cc6993d",
        "plan": {
          "id": "46cee6d0-7788-44ae-bd69-8a8e932b7ab9",
          "title": "1 GB - 7 days"
        },
        "status": "ACTIVE",
        "data_remaining": 100
      }
    ],
    "data_remaining": 100
  }
}
```

### Webhook Simulator

This endpoint allows to simulate various webbhooks sent by eSIM backend. Webhook simulator is available at `<esim-backend-url>/api/v1/sources/<hostapp_name>/webhook/simulator/`.

Here as an example request to webhook simulator and it's payload:

```bash theme={"system"}
curl --location 'https://esim-staging.shopboxo.io/api/v1/sources/<hostapp_name>/webhook/simulator/' \
--header 'Content-Type: application/json' \
--data '{
    "app_id": "app_XXXXX",
    "event_type": "order.succeeded",
    "iccid": "893000000000057339",
    "reference": "06b66222-4ff4-4056-803b-dc81c74fcbdc"
}'
```

```json theme={"system"}
{
    "event_type": "order.succeeded",
    "iccid": "893000000000057339",
    "reference": "06b66222-4ff4-4056-803b-dc81c74fcbdc"
}
```