FAQ - Dragonpass API Developer Platform

1. Who is this FAQ for?

This FAQ is for new customers integrating the Dragonpass API for the first time. It is also useful for product, implementation, development, QA, support, and operations teams. Instead of only explaining endpoints, it connects the whole journey from commercial scope, Sandbox development, order flow, and callback handling to acceptance and Production launch.

2. What should we confirm before writing code?

Confirm the business scope first. Decide which modules to offer, which markets or airports are included, where users enter the journey, whether you need E-pass or Membership, whether prebooking and pricing are required, and how support, cancellation, refund, and reconciliation should work. A clear scope prevents repeated rework later.

3. What comes from commercial alignment and what comes from technical integration?

Commercial alignment usually confirms the partnership scope, available modules, resource and price authorization, and launch timeline. Technical integration turns that into a Program ID, API permissions, authentication setup, callback URLs, Sandbox tests, and Production credentials. In simple terms, commercial alignment defines what can be offered, and technical work makes it run reliably.

4. What is the difference between Sandbox and Production?

Sandbox is for development and testing. It is where you verify APIs, orders, callbacks, and exception handling without affecting real users or real orders. Production is the live environment for real users. Complete acceptance in Sandbox before requesting Production credentials, and keep secrets, Program IDs, and configuration separate between the two environments.

5. How does a new customer get API credentials?

First, align the integration scope with the Go To Market or Sales team and obtain Sandbox credentials. After integration and testing are complete, request Production credentials through the same team or portal. If you use the recommended RS256 authentication model, generate an RSA key pair, share the public key with Dragonpass, and Dragonpass will configure access and return the issuer value.

6. How should we understand API authentication?

Think of authentication as a server-to-server access pass. Each request from the customer backend to the Dragonpass API must include a valid token proving that the project is authorized. Secrets and tokens must stay on the server side and should never be exposed in mobile apps, web frontends, or public documents.

7. Why is RS256 recommended?

RS256 uses a key pair. The customer keeps the private key to sign tokens, and Dragonpass uses the public key to verify them. This avoids sharing the signing private key and is better suited to long-term production use. Existing HS256 customers can continue to use HS256, but new integrations should prepare for RS256 where possible.

8. How long is an access token valid?

When using the Generate Access Token API, the returned token is valid for 1 hour according to the documentation. The customer backend should cache the token and refresh it before expiry. If an API call fails because of authentication, the backend should refresh the token and retry where appropriate instead of forcing the user to repeat the action.

9. Which common headers should we pay attention to?

Most calls require Authorization and Content-Type. Project-specific APIs usually also require X-Program-ID. For create or update requests, use X-Request-ID as an idempotency key. This helps prevent duplicate orders or duplicate entitlement changes when a request times out and must be retried.

10. How do we know whether an API call succeeded or failed?

A successful response usually returns code=0, with business data inside data. A failure response usually includes code=-1, errCode, and msg.

11. What is the simplest difference between E-pass and Membership?

An E-pass is like a digital multi-use pass issued to a specific user. It has a defined module, usage allowance, validity period, and usage scope. Membership is more like a long-term account with managed entitlements, validity, and status. Use E-pass for fixed, short-term benefits, and Membership for long-term loyalty programs.

12. Should a new customer start with E-pass or Membership?

If your business gives users a fixed benefit, such as one or several lounge visits, E-pass is usually simpler. If your business manages loyalty tiers, long-term validity, and dynamic entitlement changes, Membership is usually the better fit. Some customers may use both models for different product lines.

13. Which services can be integrated?

According to the current documentation, both E-pass and Membership support Lounge Walk-in and Prebooking, Fast Track, Dining Set Meal, Dining Coupon, Fitness, and eSIM. The exact modules available to your project depend on the contract, project configuration, and resource authorization.

14. Can an E-pass be changed after it is issued?

Key E-pass attributes are defined at issuance, including module, user name, available usages, activation and expiration dates, and usage scope. The documentation describes these attributes as fixed after issuance. If you need to restrict the pass by country, airport, or resource, design allowedResources before creating it. Once an E-pass is cancelled, it becomes invalid immediately and cannot be restored.

15. When is Membership the right choice?

Membership is suitable when Dragonpass services are part of your own loyalty program. For example, you may configure different benefits for different tiers, extend membership validity, suspend or reactivate members, or add and remove entitlements based on campaigns. It is more flexible than E-pass for long-term member operations.

16. How does resource search usually work?

Think of resource search in three layers. First, retrieve transport hubs such as airports. Second, search resources by module or location, such as lounges or Fast Track services. Third, retrieve resource details, available options, or availability for a specific time. This lets users move from destination to service selection in a clear flow.

17. Does the pricing API return the user-facing selling price?

The documentation states that the pricing API returns the contractually agreed settlement price between Dragonpass and the customer. The customer can decide whether and how to display it to end users. In batch price queries, resources or options outside the authorized price list may not be returned.

18. Why might some resources or prices be missing?

Common reasons include missing authorization for a module or resource, a resource not being available at the selected location, a mismatch between transportHubId and module, a price list that does not include the resource or option, or a service that does not support prebooking. Before launch, product and technical teams should verify authorization and display rules together.

19. Why must availability be checked before prebooking?

Prebooking means reservation before usage, so the system must confirm that the selected resource, option, and time are available before the order is created. A prebookingToken is returned only when availability exists, and that token is required for order creation. If ePassId or membershipId is provided, availability is reserved for that credential. Sending the same identifier again releases the previous reservation and creates a new one.

20. What is the difference between walk-in and prebooking?

Walk-in means the user arrives on site and presents an E-pass ID or Membership ID. After successful validation, the usage is recorded immediately. Prebooking means the user reserves a service in advance. After order creation, the order may still be waiting for confirmation. Only Confirmed means the service is ready to use and vouchers can be shown to the user.

21. What is the difference between an E-pass order and a usage order?

An E-pass order is the issuance of the pass itself. It defines who can use it, how many times it can be used, when it becomes valid, and where it can be used. A usage order is created for each actual use or reservation, such as one lounge redemption or one Fast Track prebooking. When querying the E-pass usage order list, the returned orderId is the usage order ID, not the original E-pass issuance order ID.

22. Which IDs should the customer system store?

At minimum, store the Program ID, the customer's own user ID, E-pass ID or Membership ID, E-pass issuance order ID, every usage order ID, resource ID, option ID, voucher ID, and callback orderId. Support lookup, order-detail queries, cancellation, reconciliation, and callback idempotency all depend on these IDs.

23. How should we understand order statuses in plain language?

Confirmed means the order is confirmed and ready to use. Used means the service has been consumed. Cancelled means it can no longer be used. Expired means the validity period ended before usage. Pending means the order was created but is still waiting for confirmation. Failed means the order could not be created or processed. The user interface must not treat Pending as a successful booking.

24. How should Pending be shown to users?

Show Pending as processing or waiting for confirmation. Do not display it as a usable voucher. After a callback or order-detail query returns Confirmed, show the voucher, QR code, or reservation details. If the order becomes Failed or Cancelled, tell the user that the booking was not successful or has been cancelled, and then follow your refund or entitlement-restoration rules.

25. How should the customer system process the order flow?

Use an event-driven approach. After creating an order, save the local order and key IDs. For prebooking, show processing first. Show usable vouchers only after Confirmed. Mark the order complete after Used. After Cancelled, Failed, or Expired, stop showing usable entry points and trigger support, refund, entitlement restoration, or reconciliation steps as needed. Keep order-detail polling as a fallback for missed callbacks.

26. How should duplicate or out-of-order callbacks be handled?

For prebooking status callbacks, use orderId plus statusChangedDate for idempotency and ordering, and do not let older events overwrite newer statuses. For walk-in callbacks, use the unique orderId to identify the same usage. If a cancellation event arrives before the creation event for the same orderId, treat the order as cancelled and ignore the later creation event.

27. What should we consider when cancelling orders?

Cancelling an E-pass invalidates it immediately and it cannot be restored, so query its usage status before cancellation where needed. After a usage order is cancelled, the user interface should no longer show it as usable, and support or finance teams should handle entitlement restoration, refund, or reconciliation according to the business rules.

28. Which scenarios should be tested in Sandbox at minimum?

At minimum, test successful and failed authentication, resource search, price query, E-pass issuance and cancellation, Membership registration or update, prebooking availability and order creation, walk-in usage records, order-detail queries, successful callbacks, duplicate callbacks, out-of-order callbacks, order cancellation, and status changes from Pending to Confirmed or Failed.

29. What are the most important checks before go-live?

Before launch, confirm that Production credentials are requested and stored separately, API permissions and Program ID are correct, callback URLs are reachable from Production, order, cancellation, failure, refund, or entitlement-restoration journeys are accepted, support teams can look up issues by key IDs, and monitoring covers API failures, callback failures, and order exceptions.

30. What should be monitored after launch?

After launch, watch API success rate, orders stuck in intermediate statuses, callback failures, resource and price updates, user complaints, cancellations, refunds, and reconciliation differences. If resource update push is enabled, also process resource metadata updates, transport hub updates, and availability changes, with a recovery process where supported.

31. How should multi-language content and fallback be handled?

Some resource APIs support multiple languages and require prior authorization. Detail APIs can use fallbackAllowed so missing translations can fall back to en-US where configured. List APIs currently do not support fallback. Before launch, confirm the default language, target market languages, and what users should see when a translation is missing.