Fast Track 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. A fast track order is a pre-booking for a specific airport. quantity is the number of passengers. custom_attributes.currency and entry_price are the catalog price per passenger. The top-level currency and amount are what the host charges. paid_entries is how many passengers are paid; the rest are covered by a tier, and discount_amount is the value of the free passengers. tax_amount is 0. country_code, country_title, and hub_title identify the airport. tier_applied, tier_name, tier_names, and free_entries are included only when a tier covered one or more passengers. tier_applied is the string "true". tier_names is a comma-separated list when more than one tier was used.

{
  "currency": "USD",
  "amount": "15.00",
  "subtotal_amount": "30.00",
  "shipping_amount": "0",
  "discount_amount": "15.00",
  "tax_title": "",
  "tax_amount": "0",
  "taxes_included": false,
  "note": "",
  "miniapp_order_id": "5b2f4d08-9081-4665-9eb1-325419310d4e",
  "hostapp_user_id": "5b2f4d08-9081-4665-9eb1-325419310d4e",
  "custom_attributes": {
    "entry_price": "15.00",
    "currency": "USD",
    "quantity": "2",
    "paid_entries": "1",
    "country_code": "AE",
    "country_title": "United Arab Emirates",
    "hub_title": "Dubai International",
    "tier_applied": "true",
    "tier_name": "Prime",
    "tier_names": "Prime",
    "free_entries": "1"
  }
}

Local pricing

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

original_price — the order total in the catalog 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 those price objects is a decimal string with trailing zeros removed. entry_price and custom_attributes.currency stay in the catalog currency. When the source charges in the local currency, currency, amount, subtotal_amount, and discount_amount are the local amounts. amount is the rounded snapshot taken when the order was created. discount_amount is converted with the snapshot rate, and subtotal_amount absorbs the rounding difference so that subtotal_amount - discount_amount equals amount. When a snapshot exists but the source still charges in the catalog 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.

"original_price": {
  "amount": "15.13",
  "currency": "USD"
},
"initial_converted_price": {
  "amount": "6052",
  "currency": "AMD"
},
"rounding_rule": "ceil-100"

With that rule the charged amount is "6100.00" and currency is "AMD".

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

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.

Webhooks

Here are example payloads for the webhooks the fast track miniapp sends, if you have provided us with the webhook URL. The fast track backend uses hostapp_client_id and hostapp_secret_key configured in Boxo Platform. They are passed as basic auth in the Authorization header on every request. You can use this to authenticate your webhook endpoint. Match an order webhook to the payment with external_source_payment_id (the same value as external_id). tier is the tier id that provided the free passengers, or null. membership is null on a fast track order; the guest is the hostapp_user_id from the payment.

Fast track order success

This event is fired when the fast track pass is issued.

{
  "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",
    "external_id": "261ba7b4-a578-451a-a05a-7ee26ba36e65",
    "tier": "73def29d-99b0-4370-9100-4321ee6faabd",
    "membership": null,
    "quantity": 2,
    "subtotal": {
      "amount": "30.00",
      "currency": "USD"
    },
    "total": {
      "amount": "15.00",
      "currency": "USD"
    },
    "free_entries_count": 1,
    "wholesale_price": {
      "amount": "8.00",
      "currency": "USD"
    },
    "completed": "2026-10-12T11:33:43Z"
  }
}

Fast track order failed

This event is fired when the guest was charged and the pass could not be issued. Hostapp can use it to initiate a refund if this event is received. The payload has the same shape as order.completed. completed is null.

{
  "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",
    "external_id": "261ba7b4-a578-451a-a05a-7ee26ba36e65",
    "tier": null,
    "membership": null,
    "quantity": 2,
    "subtotal": {
      "amount": "30.00",
      "currency": "USD"
    },
    "total": {
      "amount": "30.00",
      "currency": "USD"
    },
    "free_entries_count": 0,
    "wholesale_price": {
      "amount": "8.00",
      "currency": "USD"
    },
    "completed": null
  }
}

Fast track visit redeemed

This event is fired when a fast track pass is redeemed. The redeemed lane is under lounge. resource_type is FAST_TRACK. membership is null when the visit is not tied to a membership.

{
  "event_type": "membership.redemption",
  "app_id": "app_XXXXXX",
  "client_id": "host_XXXXXXXXXXXX",
  "payload": {
    "id": "26a275d1-356d-4f59-92f7-640aded2c5ae",
    "membership": {
      "id": "eb275a7f-3b4c-4c35-881c-f5535d509202",
      "external_id": "M-10001",
      "available_entries": 7,
      "expired": "2027-10-12T00:00:00Z",
      "user_id": "5b2f4d08-9081-4665-9eb1-325419310d4e"
    },
    "lounge": {
      "id": "1e8ca9cd-1878-4d8b-9922-d0c57aeaf717",
      "external_id": "FT-30003",
      "title": "Fast Track Departure",
      "resource_type": "FAST_TRACK",
      "route_types": ["INTERNATIONAL_DEPARTURE"],
      "hub": {
        "id": "8c467680-6d9a-4eca-9f43-b1da9be44ecf",
        "title": "Dubai International",
        "external_id": "H-DXB",
        "hub_type": "AIRPORT",
        "iata": "DXB",
        "city": "Dubai",
        "country": "AE"
      }
    },
    "redeemed": "2026-10-12T11:33:43Z",
    "used_usages": 1,
    "cardholder_passenger_count": 1,
    "guest_passenger_count": 1
  }
}

Webhook Simulator

This endpoint allows to simulate webhooks sent by the fast track backend. Webhook simulator is available at <lounge-backend-url>/api/v1/sources/<source_slug>/webhook/simulator/. event_type is order.completed or membership.redemption. membership_id and reference are optional; the simulator generates them when they are omitted.

curl --location 'https://lounge-staging.boxo.io/api/v1/sources/<source_slug>/webhook/simulator/' \
--header 'Content-Type: application/json' \
--data '{
    "app_id": "app_XXXXX",
    "event_type": "order.completed",
    "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

Caching

Webhooks

Fast track order success

Fast track order failed

Fast track visit redeemed

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

​Caching

​Webhooks

​Fast track order success

​Fast track order failed

​Fast track visit redeemed

​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

Caching

Webhooks

Fast track order success

Fast track order failed

Fast track visit redeemed

Webhook Simulator