Issuing, Querying, and Cancelling an E-pass

Issue An E-pass

→ Use /orders/{module}/ePasses to create a DragonPass E-pass order for your end users.

The system requires each clientUserId to be bound to a unique name in order to maintain user identity integrity.

You may register multiple different E-passes under the same name using the same clientUserId.

Using the same clientUserId to create E-passes with different names is not allowed and will result in a validation error.

Request

Create E-pass Order - Request

Response

Create E-pass Order - Response

{
    "status": 1,
    "module": 1,
    "category": 1,
    "clientUserId": "3EF5D065-76F8-4D3E-801A-B329D15F461A",
    "orderId": "DP00000000000001",
    "orderCreatedDate": "2024-12-31T00:00:00+00:00",
    "orderCancelledDate": null,
    "usageDate": null,
    "extra": {
        "ePassId": "1788000066668888",
        "ePassStatus": 1,
        "firstName": "DragonPass",
        "lastName": "DragonPass",
        "activationDate": "2028-10-31T23:59:59+00:00",
        "expirationDate": "2028-12-31T23:59:59+00:00",
        "availableUsages": 1,
        "usedUsages": 0,
        "allowedResources": {
            "resourceIds": []
        }
    }
}

E-pass Activation Date

The activationDate field is optional.

If it is not provided, the E-pass will be activated immediately upon issuance.

If an activationDate is specified, the E-pass will only become active after the given datetime and cannot be used beforehand. The datetime can include a time zone offset, but must not be earlier than the current time.

Request Example 1
This request does not specify an activation date, therefore, this E-pass will be activated immediately upon issuance.

{
  "module": 1,
  "clientUserId": "3EF5D065-76F8-4D3E-801A-B329D15F461A",
  "extra": {
    "firstName": "DragonPass",
    "lastName": "DragonPass",
    "expirationDate": "2028-12-31T23:59:59+00:00",
    "availableUsages": 1,
    "allowedResources": {
      "resourceIds": []
    }
  }
}

Request Example 2
The activation date specified in the request is 2028-10-31T23:59:59+00:00. Accordingly, this E-pass will be automatically activated after this time and will not be valid for use beforehand.

{
    "module": 3,
    "clientUserId": "3EF5D065-76F8-4D3E-801A-B329D15F461A",
    "extra": {
        "firstName": "DragonPass",
        "lastName": "DragonPass",
        "activationDate": "2028-10-31T23:59:59+00:00",
        "expirationDate": "2028-12-31T23:59:59+00:00",
        "availableUsages": 5,
        "allowedResources": {
            "resourceIds": []
        }
    }
}

E-pass Allowed Resources

The allowedResources object defines where an E-pass can be used by restricting its applicable resources at one specific dimension only.

It is designed to support different E-pass distribution models such as country-based passes, airport-based passes, or resource-specific passes.

Only one restriction type is supported per E-pass.

Within allowedResources, exactly one of resourceIds, iata, or countryOrRegion can be configured.

Country-based E-pass (Country Pass)
Use countryOrRegion to issue an E-pass that is valid in one or more countries or regions.

Example: An E-pass that can be used at any eligible DragonPass resource within United Kingdom.

"allowedResources": {
    "countryOrRegion": ["GB"]
}

Airport-based E-pass (Airport Pass)
Use iata to limit the E-pass to specific airports.
This is applicable to airport-related resources only.

Example: An E-pass that can be redeemed at DragonPass lounges services at Hong Kong and Manchester airports.

"allowedResources": {
    "iata": ["HKG","MAN"]
}

Resource-specific E-pass
Use resourceIds to restrict the E-pass to designated individual resources.

Example: An E-pass that is valid only for specific lounges.

"allowedResources": {
    "resourceIds": ["N00001","N00002"]
}

Retrieve E-pass Details

→ Use /orders/ePasses/search to retrieve the details of a specific E-pass order by providing the E-pass ID or Order ID.

Request

Retrieve E-pass Details - Request

{
    "orderId": "DP00000000000001"
}

Response

A successful response returns the following information about the order:

Retrieve E-pass Details - Response

{
    "code": 0,
    "data": {
        "status": 2,
        "module": 1,
        "category": 1,
        "clientUserId": "3EF5D065-76F8-4D3E-801A-B329D15F461A",
        "orderId": "DP00000000000001",
        "orderCreatedDate": "2024-12-31T00:00:00+00:00",
        "orderCancelledDate": null,
        "extra": {
            "ePassId": "1788000066668888",
            "ePassStatus": 1,
            "firstName": "DragonPass",
            "lastName": "DragonPass",
            "activationDate": "2028-10-31T23:59:59+00:00",
            "expirationDate": "2028-12-31T23:59:59+00:00",
            "availableUsages": 0,
            "usedUsages": 1,
            "allowedResources": {
                "resourceIds": [
                    "N00001"
                ]
            }
        }
    }
}

Cancel An E-pass

→ Use the /orders endpoint to cancel an E-pass order.

Once the order is canceled, the E-pass will be instantly invalidated and cannot be restored.

We recommend checking the E-pass usage status through the Retrieve E-pass Details before proceeding with cancellation and refund, to avoid potential financial loss.

Issue An E-pass#

E-pass Activation Date#

E-pass Allowed Resources#

Retrieve E-pass Details#

Cancel An E-pass#

Issue An E-pass

E-pass Activation Date

E-pass Allowed Resources

Retrieve E-pass Details

Cancel An E-pass