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.

{
  "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": {
    "plan_title": "5GB for 30 Days",
    "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"
  }
}

Local pricing

When the order has a local pricing snapshot, custom_attributes also includes:

original_price — the order total in the quote currency, before conversion.
initial_converted_price — that total converted into the local currency, before rounding.
rounding_rule — code of the rounding rule that produced the charged amount. Omitted when no rounding rule ran.

amount on original_price and initial_converted_price is a decimal string with trailing zeros removed. provider_net_price is not converted. When the source charges in the local currency, currency, amount, subtotal_amount, discount_amount, and tax_amount are the local amounts. amount is the rounded snapshot taken when the order was created, not a fresh conversion. Tax and discount are converted with the snapshot rate, and subtotal_amount absorbs the rounding difference so that subtotal_amount - discount_amount + tax_amount equals amount. When a snapshot exists but the source still charges in the quote currency, the top-level amounts stay in that currency and the three attributes are still sent. The attributes are omitted entirely when the order has no snapshot. In this example a 88.13 USD total is converted at 400 and ceiled to the next 100, so the host is asked to charge 35300 AMD:

{
  "currency": "AMD",
  "amount": "35300.00",
  "subtotal_amount": "40048.00",
  "shipping_amount": "0.00",
  "discount_amount": "7948.00",
  "tax_title": "",
  "tax_amount": "3200.00",
  "taxes_included": false,
  "note": "",
  "miniapp_order_id": "5b2f4d08-9081-4665-9eb1-325419310d4e",
  "hostapp_user_id": "5b2f4d08-9081-4665-9eb1-325419310d4e",
  "custom_attributes": {
    "plan_title": "5GB for 30 Days",
    "location": {
      "id": "8c467680-6d9a-4eca-9f43-b1da9be44ecf",
      "code": "ES",
      "title": "Spain",
      "type": "COUNTRY",
      "is_global": false
    },
    "provider_net_price": {
      "amount": "10.00",
      "currency": "USD"
    },
    "data": 1024,
    "duration": 7,
    "order_type": "ACTIVATION",
    "original_price": {
      "amount": "88.13",
      "currency": "USD"
    },
    "initial_converted_price": {
      "amount": "35252",
      "currency": "AMD"
    },
    "rounding_rule": "ceil-100"
  }
}

Locale

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

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:

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

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

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'

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

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

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.

// 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. Example code reference can be viewed here. 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. The plan object in webhook payloads includes a location object (the country or region the plan covers) and title_translations. Translated titles (title_translations on both the plan and its location) are included for the languages configured for your miniapp’s webhooks; if no languages are configured, these objects are empty.

eSIM order success

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

{
  "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",
      "title_translations": {
        "en": "2 GB - 15 days",
        "es": "2 GB - 15 días"
      },
      "location": {
        "id": "1e8ca9cd-1878-4d8b-9922-d0c57aeaf717",
        "code": "AE",
        "title": "United Arab Emirates",
        "title_translations": {
          "en": "United Arab Emirates",
          "es": "Emiratos Árabes Unidos"
        },
        "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.

{
  "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",
      "title_translations": {
        "en": "2 GB - 15 days",
        "es": "2 GB - 15 días"
      },
      "location": {
        "id": "1e8ca9cd-1878-4d8b-9922-d0c57aeaf717",
        "code": "AE",
        "title": "United Arab Emirates",
        "title_translations": {
          "en": "United Arab Emirates",
          "es": "Emiratos Árabes Unidos"
        },
        "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.

{
  "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",
      "title_translations": {
        "en": "2 GB - 15 days",
        "es": "2 GB - 15 días"
      },
      "location": {
        "id": "1e8ca9cd-1878-4d8b-9922-d0c57aeaf717",
        "code": "AE",
        "title": "United Arab Emirates",
        "title_translations": {
          "en": "United Arab Emirates",
          "es": "Emiratos Árabes Unidos"
        },
        "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.

{
  "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",
          "title_translations": {
            "en": "Unlimited - 3 days",
            "es": "Ilimitado - 3 días"
          },
          "location": {
            "id": "1e8ca9cd-1878-4d8b-9922-d0c57aeaf717",
            "code": "AE",
            "title": "United Arab Emirates",
            "title_translations": {
              "en": "United Arab Emirates",
              "es": "Emiratos Árabes Unidos"
            },
            "type": "COUNTRY",
            "is_global": false
          }
        },
        "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).

{
  "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",
            "title_translations": {
              "en": "1 GB - 7 days",
              "es": "1 GB - 7 días"
            },
            "location": {
              "id": "1e8ca9cd-1878-4d8b-9922-d0c57aeaf717",
              "code": "AE",
              "title": "United Arab Emirates",
              "title_translations": {
                "en": "United Arab Emirates",
                "es": "Emiratos Árabes Unidos"
              },
              "type": "COUNTRY",
              "is_global": false
            }
          },
          "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.

{
  "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",
          "title_translations": {
            "en": "1 GB - 7 days",
            "es": "1 GB - 7 días"
          },
          "location": {
            "id": "1e8ca9cd-1878-4d8b-9922-d0c57aeaf717",
            "code": "AE",
            "title": "United Arab Emirates",
            "title_translations": {
              "en": "United Arab Emirates",
              "es": "Emiratos Árabes Unidos"
            },
            "type": "COUNTRY",
            "is_global": false
          }
        },
        "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%.

{
  "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",
          "title_translations": {
            "en": "1 GB - 7 days",
            "es": "1 GB - 7 días"
          },
          "location": {
            "id": "1e8ca9cd-1878-4d8b-9922-d0c57aeaf717",
            "code": "AE",
            "title": "United Arab Emirates",
            "title_translations": {
              "en": "United Arab Emirates",
              "es": "Emiratos Árabes Unidos"
            },
            "type": "COUNTRY",
            "is_global": false
          }
        },
        "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:

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"
}'

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

Welcome

Host Apps

Miniapps

API References

White Label Miniapps

Changelog

Boxo Platform and Boxo SDK

Payment Payload

Local pricing

Locale

Closing miniapp and landing on Home page on next launch

Deeplinks

Hide About from Menu

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

Caching

Android compatibility check enhancement

iOS direct installation

Capacitor plugin

Webhooks

eSIM order success

eSIM order failed

eSIM order expired

eSIM activated

eSIM expired

eSIM data zero

eSIM data running low

Webhook Simulator

​Boxo Platform and Boxo SDK

​Payment Payload

​Local pricing

​Locale

​Closing miniapp and landing on Home page on next launch

​Deeplinks

​Hide About from Menu

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

​Caching

​Android compatibility check enhancement

​iOS direct installation

​Capacitor plugin

​Webhooks

​eSIM order success

​eSIM order failed

​eSIM order expired

​eSIM activated

​eSIM expired

​eSIM data zero

​eSIM data running low

​Webhook Simulator

Boxo Platform and Boxo SDK

Payment Payload

Local pricing

Locale

Closing miniapp and landing on Home page on next launch

Deeplinks

Hide About from Menu

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

Caching

Android compatibility check enhancement

iOS direct installation

Capacitor plugin

Webhooks

eSIM order success

eSIM order failed

eSIM order expired

eSIM activated

eSIM expired

eSIM data zero

eSIM data running low

Webhook Simulator