This API provides a unified, secure interface to enrich cardholders with travel rewards. Key features include:
\nPass Creation and Management: Create Lounge Pass, eSim and future services via a single endpoint, determined by plan_id mappings in our database. Supports batch operations for scale. For Priority Pass plans (determined by plan_id), support for tokenized enrollment via an optional enrol_token parameter, obtained from tokenized engine API, to avoid handling sensitive card data and ensure PCI de-scoping.
\nSecurity and Compliance: OAuth 2.0 authentication
\nKey Benefits: Simplifies integration, ensures idempotency for retries, and provides type-specific responses
\nScope: Covers enrollment, updates, status queries, and cancellations.
\nEnvironments: UAT for testing; Production for live use.
\nCredentials: During onboarding, you'll receive a client_id and client_secret for OAuth. Share plan_id mappings via secure channel for our DB configuration. For Priority Pass / LoungeKey integrations, call /card/tokenize to generate an enrol_token (see Tokenized Engine section). For eSIM integrations, the enrol_token is an Airalo package_id — no card tokenization is needed. Share plan_id mappings via secure channel during onboarding.
Tools: Postman for testing. Use environment variables: base_url, client_id, client_secret, access_token (auto-set via auth request), pass_id (from create responses).
\nAuthenticate: Call LoyaltyLayer API /auth/token to get an access_token (expires in 30 minutes, control by system). Test script sets access_token.
\nTokenize Card (card-based plans only): Required for Priority Pass and LoungeKey plans. Skip this step for eSIM plans.
\nFetch encryption keys from GET /v1/card/encryption-keys.
Encrypt card data (CardNumber, CardExpiry, NameOnCard, Cvv) into a JWE compact string using the RSA public key. See the Card Data Encryption Guide section below for code examples.
\nCall POST /v1/card/tokenize with the encrypted_value, plan_id, and card_type. This returns an enrol_token.
Create a Pass: Use POST /v1/pass/create with the enrol_token, along with holder details. The response shape depends on the plan type — e.g., dmc_qr_data for Priority Pass; iccid and qr_code_data for eSIM. For eSIM plans, card_type and holder.address are not required.
Batch Operations: For bulk, use POST /v1/pass/batch-create with an array of pass objects, each including enrol_token from the tokenize step.
Manage Passes: Use POST /v1/pass/status, POST /v1/pass/update, or POST /v1/pass/cancel.
Testing: For Priority Pass in UAT, use a mock enrol_token. Validate responses against updated specs, ensuring no PAN is sent.
\nGo Live: Switch to Prod base URL after UAT complete.
\nPostman Tips: Run \"Auth Token\" first. Use variables for chaining (e.g., set pass_id from create response). Test edge cases like invalid plan_id (expect 400).
\nFor support, schedule a demo or provide logs with correlation IDs from errors.
\nIf you use AI agent to assiant development. You can find a .md file to pass to AI agent to overview the integration guideline.
\n\nOur API uses OAuth 2.0 Client Credentials flow. This ensures secure B2B access without user involvement.
\nEndpoint: POST /auth/token
\nRequest Format: application/json
\nclient_id: Required, issued during onboarding.
\nclient_secret: Required, secure key.
\nResponse: JSON with access_token (opaque string, Bearer type), expires_in (1800 seconds). Expired token in 401 error.
\nUsage: Include Authorization: Bearer {{access_token}} in all subsequent headers.
\nSecurity Notes: Tokens are reference-based (validated server-side). Use HTTPS/TLS 1.2. No session cookies; stateless.
\nBest Practices: Cache tokens per client_id to reduce calls. Handle expiry with auto-refresh logic.
\nSecurity Notes: Our API does not handle or store PANs; use of enrol_token for Priority Pass keeps integrations out of PCI scope.
\nTo ensure fair usage and system stability, we enforce the following limits:
\nRate Limiting: 100 requests per minute per IP. And 1 minute blocked traffic from same IP after exceed rate limit. Exceeded: HTTP 429 Too Many Requests.
\nError Handling: Limits reset minute. Can retry after reset period.
\nMonitoring: We log usage; contact us if higher limits needed (e.g., for campaigns).
\nSuccessful responses (200 OK) return JSON.
\nErrors are returned with standard HTTP status codes and JSON bodies for easy parsing. Implement retry logic for transient issues (e.g., 5xx) and backoff on 429.
\n400 Bad Request: Invalid or missing parameters (e.g., wrong grant_type).
Example:
{ \"error\": \"invalid_enrol_token\", \"error_description\": \"Provided enrol_token is invalid or expired\", \"code\": 400 }
401 Unauthorized: Invalid client_id or client_secret.
Example:
{ \"error\": \"invalid_client\", \"error_description\": \"Client authentication failed.\", \"code\": 401}
(mapped from Priority Pass/LoungeKey auth failures).
401 Unauthorized (Bearer Token): Missing, empty, or expired Bearer token on any protected endpoint.
Examples:
{ \"error\": \"unauthorized\", \"error_description\": \"Missing or invalid Authorization header.\", \"code\": 401 } { \"error\": \"invalid_token\", \"error_description\": \"Access token is invalid or expired.\", \"code\": 401 }
404 Not Found: Invalid pass ID.
Example:
{ \"error\": \"invalid_pass_id\", \"error_description\": \"Invalid pass ID\", \"code\": 404}
409 Already Cancelled: Pass is already cancelled.
Example:
{ \"error\": \"already_cancelled\", \"error_description\": \"Pass {pass_id} is already cancelled.\", \"code\": 409 }
429 Too Many Requests: Rate limit exceeded.
Example:
{ \"error\": \"rate_limit_exceeded\", \"error_description\": \"Retry after 60 seconds\", \"code\": 429, \"retry_after\": 60 }
500 Internal Server Error: Rare server issues (we retry calls internally).
Example:
{ \"error\": \"server_error\", \"error_description\": \"Unexpected error; try again\", \"code\": 500 }
502 Provider Unavailable: Upstream provider returned an error.
Example:
{ \"error\": \"server_error\", \"error_description\": \"Provider operation failed.\", \"code\": 502 }
504 Provider Timeout: Upstream provider did not respond in time.
Example:
{ \"error\": \"provider_timeout\", \"error_description\": \"Provider operation failed.\", \"code\": 504 }
Returns the JWKS public keys required to encrypt card data before calling the Tokenize Card endpoint. Partners must encrypt sensitive card fields (CardNumber, CardExpiry, NameOnCard, Cvv) into a JWE compact string before sending to our API. This ensures no raw card data flows through LoyaltyLayer, maintaining PCI DSS compliance.
\nTokenize encrypted card data to obtain an enrol_token for use with the Create Pass endpoint. Partners encrypt their card data client-side using JWE (JSON Web Encryption) with keys from the encryption-keys endpoint, then send the encrypted payload here. LoyaltyLayer handles the upstream provider authentication and tokenization internally.
To maintain PCI DSS de-scoping and avoid handling sensitive Primary Account Number (PAN) data in our system, use this tokenized flow for pass creations (identified by plan_id mappings configured in our database). In this approach, client first interacts directly with tokenized engine API to tokenize the card details, obtaining an enrol_token. This token is then passed to our /passes/create or /passes/batch-create endpoints, where our backend completes the enrolment and pass creation on your behalf.
\nThis flow simplifies integration while ensuring security, idempotency, and compliance.
\nClient must have tokenized engine credentials (client_id and client_secret) for their OAuth 2.0 Client Credentials flow.
\nEnsure plan_id mappings are shared securely during onboarding for entiltment configurations.
\nTest in UAT environment first in tokenized engine API UAT entry point.
\nSwitch to production.
\nAuthenticate with tokenized engine: Obtain a short-lived access token (expires in 30 minutes) for secure API calls.
\nEndpoint: POST /oauth2/token
\nRequest Headers: Content-Type: application/x-www-form-urlencoded
\nRequest Body: grant_type=client_credentials&client_id={your_client_id}&client_secret={your_client_secret}
\nResponse: JSON with access_token (use as Bearer in Authorization header for subsequent calls).
\nTokenize Card: Validate and tokenize the cardholder's details to generate an enrol_token. This step handles PAN securely within PCI Level 1 compliant environment.
\nEndpoint: POST /cards (or equivalent card tokenization endpoint).
\nRequest Headers: Authorization: Bearer {access_token}, Content-Type: application/json
\n{ \"card_number\": \"4111111111111111\", \"expiry_date\": \"12/2028\", \"cardholder_name\": \"John Doe\", \"other_validation_fields\": {} // As per Collinson's requirements, e.g., CVV if needed for validation}
Response: JSON including enrol_token (an opaque string) and any validation status.
\nError Handling: Expect 400 for invalid card details; retry transients (5xx) with backoff.
\nNote: Use mock data in UAT (e.g., card_number: \"4111111111111111\"). The enrol_token is single-use and expires; handle accordingly.
\nTo tokenize a card through LoyaltyLayer, partners must encrypt the card data client-side using JWE (JSON Web Encryption). This ensures sensitive card data never passes through LoyaltyLayer in cleartext, maintaining PCI DSS de-scoping.
\nFetch encryption keys from GET /v1/card/encryption-keys. Cache the response (keys rarely change). Select the first key from the keys array.
Build the JSON payload containing the sensitive card fields:
\n {\n \"CardNumber\": \"5571419898406210\",\n \"CardExpiry\": \"12/2027\",\n \"NameOnCard\": \"J SMITH\",\n \"Cvv\": \"123\"\n }\n\nEncrypt using JWE with the RSA public key from step 1:
\nSet the JWE protected header with alg, enc, and kid (the key ID from the JWKS)
Encrypt the JSON payload string
\nOutput in JWE compact serialization format (5 Base64url-encoded parts separated by dots)
\nSend the encrypted value as the encrypted_value field in the POST /v1/card/tokenize request.
import { importJWK, CompactEncrypt } from 'jose';\n// 1. Fetch encryption keys from LoyaltyLayer\nconst keysResponse = await fetch('https://your-api.loyaltylayer.xyz/v1/card/encryption-keys', {\n headers: { 'Authorization': 'Bearer YOUR_LL_ACCESS_TOKEN' }\n});\nconst { keys } = await keysResponse.json();\nconst jwk = keys[0]; // Use the first available key\n// 2. Build the card payload to encrypt\nconst cardData = JSON.stringify({\n CardNumber: '5571419898406210',\n CardExpiry: '12/2027',\n NameOnCard: 'J SMITH',\n Cvv: '123'\n});\n// 3. Encrypt using JWE\nconst publicKey = await importJWK(jwk, 'RSA-OAEP-256');\nconst jwe = await new CompactEncrypt(new TextEncoder().encode(cardData))\n .setProtectedHeader({\n alg: 'RSA-OAEP-256',\n enc: 'A256GCM',\n kid: jwk.kid\n })\n .encrypt(publicKey);\n// 4. Call LoyaltyLayer tokenize endpoint\nconst tokenizeResponse = await fetch('https://your-api.loyaltylayer.xyz/v1/card/tokenize', {\n method: 'POST',\n headers: {\n 'Authorization': 'Bearer YOUR_LL_ACCESS_TOKEN',\n 'Content-Type': 'application/json'\n },\n body: JSON.stringify({\n plan_id: 'PP-HKTCLLSG26-MC',\n encrypted_value: jwe,\n card_type: 'MC'\n })\n});\nconst { enrol_token } = await tokenizeResponse.json();\n// Use enrol_token in POST /v1/pass/create\n\nimport json, requests\nfrom jwcrypto import jwk, jwe\n# 1. Fetch encryption keys\nkeys_resp = requests.get(\n 'https://your-api.loyaltylayer.xyz/v1/card/encryption-keys',\n headers={'Authorization': 'Bearer YOUR_LL_ACCESS_TOKEN'}\n)\njwks = keys_resp.json()['keys']\npublic_key = jwk.JWK(**jwks[0])\n# 2. Build card payload\ncard_data = json.dumps({\n 'CardNumber': '5571419898406210',\n 'CardExpiry': '12/2027',\n 'NameOnCard': 'J SMITH',\n 'Cvv': '123'\n})\n# 3. Encrypt using JWE\nprotected_header = {\n 'alg': 'RSA-OAEP-256',\n 'enc': 'A256GCM',\n 'kid': jwks[0]['kid']\n}\njwe_token = jwe.JWE(card_data.encode('utf-8'), recipient=public_key,\n protected=json.dumps(protected_header))\nencrypted_value = jwe_token.serialize(compact=True)\n# 4. Call tokenize endpoint\nresp = requests.post(\n 'https://your-api.loyaltylayer.xyz/v1/card/tokenize',\n headers={\n 'Authorization': 'Bearer YOUR_LL_ACCESS_TOKEN',\n 'Content-Type': 'application/json'\n },\n json={\n 'plan_id': 'PP-HKTCLLSG26-MC',\n 'encrypted_value': encrypted_value,\n 'card_type': 'MC'\n }\n)\nenrol_token = resp.json()['enrol_token']\n\nThe encrypted_value string is a JWE compact serialization with 5 parts separated by dots:
BASE64URL(header).BASE64URL(encrypted_key).BASE64URL(iv).BASE64URL(ciphertext).BASE64URL(tag)\n\nWhere:
\nheader: {\"alg\":\"RSA-OAEP-256\",\"enc\":\"A256GCM\",\"kid\":\"...\"}
encrypted_key: Content Encryption Key (CEK) wrapped with the RSA public key
\niv: Initialization vector for AES-GCM
\nciphertext: The encrypted card data JSON
\ntag: Authentication tag from AES-GCM
\nPartner LoyaltyLayer Collinson\n | | |\n |-- POST /auth/token ------------ -->| |\n |<-- { access_token } --------------| |\n | | |\n |-- GET /v1/card/encryption-keys -->| |\n | |-- GET /.well-known/jwks.json->|\n |<-- { keys: [...] } --------------|<-- { keys: [...] } ----------|\n | | |\n | [encrypt card data locally] | |\n | | |\n |-- POST /v1/card/tokenize ----- -->| |\n | { encrypted_value, ... } |-- POST /card/tokenize ---- -->|\n | | { EncryptedValue, ... } |\n |<-- { enrol_token } --------------|<-- { EnrolToken } -----------|\n | | |\n |-- POST /v1/pass/create -------- -->| |\n | { enrol_token, holder, ... } |-- POST /v1/members ------- -->|\n |<-- { pass_id, dmc_qr_data } -----|<-- { MembershipNumber } -----|\n\nThe Auth Token API endpoint provides secure OAuth 2.0 authentication using the Client Credentials grant type, allowing to obtain short-lived access tokens (30 minutes) for subsequent API calls, such as creating or managing Priority Pass or LoungeKey passes. Tokens are opaque and validated server-side for all requests.
\nKey Features: Stateless, HTTPS/TLS 1.2 enforced, and tied to your client_id and client_secret.
\nUse Case: Call this before any protected endpoint (e.g., /passes/create). Refresh proactively to avoid 401 errors.
\nSecurity Notes: Tokens grant access only to permitted operations per your account.
\nTo use this endpoint successfully:
\nThe request body is JSON (Content-Type: application/json). All parameters are required.
\nSuccessful responses (200 OK) return JSON. Error responses include an error object as described above.
\n","urlObject":{"path":["auth","token"],"host":["{{base_url}}"],"query":[],"variable":[]}},"response":[{"id":"6de5b8a2-8da0-4434-99ad-edc7fb241609","name":"200 Success","originalRequest":{"method":"POST","header":[],"body":{"mode":"urlencoded","urlencoded":[{"key":"client_id","value":"","type":"text"},{"key":"client_secret","value":"","type":"text"},{"key":"grant_type","value":"client_credentials","type":"text"}]},"url":"/auth/token"},"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json","description":"","type":"text"}],"cookie":[],"responseTime":null,"body":"{\n \"access_token\": \"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...\",\n \"expires_in\": 1800\n}"},{"id":"f9677a14-9366-46cc-aeac-df4dee96869c","name":"400 Bad Request","originalRequest":{"method":"POST","header":[],"body":{"mode":"urlencoded","urlencoded":[{"key":"client_id","value":"{{client_id}}","type":"text"},{"key":"client_secret","value":"{{client_secret}}","type":"text"},{"key":"grant_type","value":"client_credentials","type":"text"}]},"url":"{{base_url}}/auth/token"},"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json","description":"","type":"text"}],"cookie":[],"responseTime":null,"body":"{\n \"error\": \"invalid_request\",\n \"error_description\": \"client_id and client_secret are required.\",\n \"code\": 400\n}"},{"id":"1a2364e8-b45b-4e5a-b14d-5e76a9c96a21","name":"429 Too Many Requests","originalRequest":{"method":"POST","header":[],"body":{"mode":"urlencoded","urlencoded":[{"key":"client_id","value":"{{client_id}}","type":"text"},{"key":"client_secret","value":"{{client_secret}}","type":"text"},{"key":"grant_type","value":"client_credentials","type":"text"}]},"url":"{{base_url}}/auth/token"},"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json","description":"","type":"text"}],"cookie":[],"responseTime":null,"body":"{\n \"error\": \"rate_limit_exceeded\",\n \"error_description\": \"Too many requests; retry after 60 seconds\",\n \"code\": 429,\n \"retry_after\": 60\n}"}],"_postman_id":"b45e5409-06a7-4ff9-b2be-178473ff3b73"},{"name":"Create Pass","id":"b849bed2-feb8-4540-9dc0-766562b2be1b","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"auth":{"type":"bearer","bearer":{"basicConfig":[{"key":"token","value":"{{access_token}}"}]},"isInherited":false},"method":"POST","header":[{"key":"Content-Type","value":"application/json","type":"text"}],"body":{"mode":"raw","raw":"{\n \"plan_id\": \"{{plan_id}}\",\n \"enrol_token\": \"ASDU78123AASDGJ\",\n \"holder\": {\n \"first_name\": \"John\",\n \"last_name\": \"Doe\",\n \"address\": {\n \"address_line_1\": \"123 Main St\",\n \"city\": \"Hong Kong\",\n \"country_code\": \"HKG\"\n }\n },\n \"card_type\": \"{{card_type}}\",\n \"expiry_date\": \"2026-12-31\",\n \"ext_card_id\": \"8712DASD7878FDD\",\n \"extra_info\": {\n \"BUUID\": \"COBANK01\"\n }\n}"},"url":"{{base_url}}/v1/pass/create","description":"The Create Pass API endpoint enables creation of different travel entitlements in a single, unified call:
\nPriority Pass membership (ongoing entitlements such as free lounge visits)
\nLoungeKey Pass voucher (transactional / one-time access)
\neSIM data plan
\nThe entitlement type is determined by the plan_id (mapped in our system during onboarding).
A bundle plan is a special plan_id that maps to multiple service entitlements at once. When you call Create Pass with a bundle plan_id, the gateway automatically provisions all configured services (e.g., lounge access + eSIM) and returns a single parent pass.
No API changes required — use the same Create Pass endpoint. The plan_id determines whether a single or bundle plan is created.
201 pass created:
{ \"pass_id\": \"12345678901234567890123456789012\", \"type\": \"priority\", \"status\": \"created\", \"dmc_qr_data\": \"QR_STRING_FOR_PRIORITY\", \"expiry\": \"2026-12-31\", \"code\": 201}
400 enrol_token validation failed:
{ \"error\": \"invalid_enrol_token\", \"error_description\": \"...\", \"code\": 400 }
{ \"error\": \"invalid_request\", \"error_description\": \"holder is required and must be an object.\", \"code\": 400 }
{ \"error\": \"invalid_request\", \"error_description\": \"holder.first_name is required.\", \"code\": 400 }
{ \"error\": \"invalid_request\", \"error_description\": \"holder.last_name is required.\", \"code\": 400 }
{ \"error\": \"invalid_request\", \"error_description\": \"holder.address is required and must be an object.\", \"code\": 400 }
{ \"error\": \"invalid_request\", \"error_description\": \"holder.address.address_line_1 is required.\", \"code\": 400 }
{ \"error\": \"invalid_request\", \"error_description\": \"holder.address.city is required.\", \"code\": 400 }
{ \"error\": \"invalid_request\", \"error_description\": \"holder.address.country_code is required.\", \"code\": 400 }
{ \"error\": \"invalid_request\", \"error_description\": \"enrol_token is required.\", \"code\": 400 } (card-based plans only)
401 provider authentication failed:
{ \"error\": \"invalid_client\", \"error_description\": \"...\", \"code\": 401 }
402 External Card ID Duplicate or Invalid: Provided external card ID is duplicate or invalid
Example:
{ \"error\": \"invalid_ext_card_id\", \"error_description\": \"Provided external card id is duplicate or invalid\", \"code\": 402 }
404 pass not found at provider:
{ \"error\": \"invalid_pass_id\", \"error_description\": \"...\", \"code\": 404 }
409 duplicate at provider:
{ \"error\": \"invalid_ext_card_id\", \"error_description\": \"...\", \"code\": 409 }
502 provider server error:
{ \"error\": \"server_error\", \"error_description\": \"...\", \"code\": 502 }
504 provider timeout:
{ \"error\": \"provider_timeout\", \"error_description\": \"...\", \"code\": 504 }
The request body is JSON (Content-Type: application/json). Required fields ensure valid creation; optional ones depend on pass type (e.g., lounge_id for LoungeKey).
\nThe parameter expiry_date default 365 days from create date. You also can configure the expiry date in passing expiry_date parameter value.
\nSuccessful responses (201 Created) return JSON with pass details. Error responses include an error object as described above.
\nThe Batch Create Passes API endpoint allows to create multiple passes in one efficient call, with each item's type determined by its plan_id (mapped in our system. This supports bulk operations for scalability, wrapping batch capabilities. Responses return job ID in success and /webhook/pass/batch-create webhook will pass same job ID in request. All requests will process in queue mode.
Use Case: Bulk issuance during promotions; call after authentication and follow with status checks for individual passes.
\nSecurity Notes: Requires valid Bearer token from /auth/token.
\n400:
{ \"error\": \"invalid_request\", \"error_description\": \"Request body must be a non-empty JSON array.\", \"code\": 400 }
400:
{ \"error\": \"invalid_request\", \"error_description\": \"Batch size cannot exceed 500 items.\", \"code\": 400 }
400:
{ \"error\": \"invalid_request\", \"error_description\": \"plan_id is required.\", \"code\": 400 }
400:
{ \"error\": \"invalid_request\", \"error_description\": \"enrol_token is required.\", \"code\": 400 }
404:
{ \"error\": \"invalid_plan\", \"error_description\": \"No active routing rule found for plan_id: {plan_id}\", \"code\": 404 }
The request body is a JSON array (Content-Type: application/json), where each object mirrors Create Pass params. Required per-item; supports up to 500 items.
\neSIM plan items (provider_key: airalo) do not require card_type or holder.address. Only holder.first_name and holder.last_name are required for record-keeping. Mixed batches (card-based and eSIM items in the same array) are supported.
The parameter expiry_date default 365 days from create date. You also can configure the expiry date in passing expiry_date parameter value.
\nSuccessful responses return a JSON results. Error responses include partial results where possible, with an error object.
\neSIM plan items do not require enrol_token, card_type, or holder.address. Bundle plan items automatically provision multiple services per user. Supply card_type, enrol_token, and holder.address when the bundle includes a card-based service component. The batch item is queued and processed asynchronously via the same cron job — no API changes required.
The Check Pass Status API endpoint allows to query the current status, entitlements for a previously created passes.
\nThe request body is JSON (Content-Type: application/json). Minimal input for querying.
\nSuccessful responses (200 OK) return JSON with status details. Error responses include an error object as described above.
\nThe Update Pass Details API endpoint enables to perform partial updates to an existing pass, such as changing email, card expiry, or phone, without recreating the pass.
\nThe request body is JSON (Content-Type: application/json). Include pass_id and only the fields to update (partial).
\nSuccessful responses (200 OK) return JSON with the updated pass details. Error responses include an error object as described above.
\n","urlObject":{"path":["v1","pass","update"],"host":["{{base_url}}"],"query":[],"variable":[]}},"response":[{"id":"ddb3bc0a-3073-4de6-9540-65b6425eb57f","name":"200 Success","originalRequest":{"method":"POST","header":[{"key":"Content-Type","value":"application/json","type":"text"}],"body":{"mode":"raw","raw":"{\n \"pass_id\": \"abc123sadadasdae2131\",\n \"expiry_date\": \"2028-01-30\",\n \"extra_info\": {\n \"BUUID\": \"ASDH12738123\",\n \"time\": 12312312312\n }\n\n}","options":{"raw":{"language":"json"}}},"url":"{{base_url}}/v1/pass/update"},"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json","description":"","type":"text"}],"cookie":[],"responseTime":null,"body":"{\n \"pass_id\": \"abc123sadadasdae2131\",\n \"status\": \"updated\",\n \"expiry_date\": \"2028-01-30\",\n \"extra_info\": {\n \"BUUID\": \"ASDH12738123\",\n \"time\": 12312312312\n }\n}"}],"_postman_id":"3cb6b56a-5759-470d-9555-691c104c11f8"},{"name":"Cancel Pass","id":"0a140afe-f369-4d80-9540-a3f5cca31b48","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"auth":{"type":"bearer","bearer":{"basicConfig":[{"key":"token","value":"{{access_token}}"}]},"isInherited":false},"method":"POST","header":[{"key":"Content-Type","value":"application/json","type":"text"}],"body":{"mode":"raw","raw":"{\n \"pass_id\": \"abc123\",\n \"reason\": \"User request\"\n}"},"url":"{{base_url}}/v1/passes/cancel","description":"The Cancel Pass API endpoint allows to cancel an existing pass.
\nUse Case: Revoke passes due to user request, fraud, or expiry; use after status check to confirm eligibility (e.g., not already redeemed).
\neSIM Note: eSIM cancellation is not supported. Calling this endpoint for an eSIM pass returns 400 not_supported. The eSIM remains active; users must manage cancellation from their device settings.
The request body is JSON (Content-Type: application/json). pass_id required; reason optional for logging.
\nSuccessful responses (200 OK) return JSON with cancellation confirmation. Error responses include an error object as described above.
\neSIM cancellation is not supported. Calling this endpoint on an eSIM pass returns a 400 not_supported error and does not change the pass status.
{ \"error\": \"not_supported\", \"error_description\": \"Airalo eSIM cancellation is not supported.\", \"code\": 400 }\n\n","urlObject":{"path":["v1","passes","cancel"],"host":["{{base_url}}"],"query":[],"variable":[]}},"response":[{"id":"f9976ff7-da12-4cab-823f-5183c19f1afa","name":"Cancel Pass","originalRequest":{"method":"POST","header":[{"key":"Content-Type","value":"application/json","type":"text"}],"body":{"mode":"raw","raw":"{\n \"pass_id\": \"abc123\",\n \"reason\": \"User request\"\n}","options":{"raw":{"language":"json"}}},"url":"{{base_url}}/v1/passes/cancel"},"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json","description":"","type":"text"}],"cookie":[{"expires":"Invalid Date","domain":"","path":""}],"responseTime":null,"body":"{\n \"status\": \"cancelled\",\n \"pass_id\": \"abc123\"\n}"},{"id":"81b787e9-42a8-4216-8cb7-023b4f9a8824","name":"400 eSIM Cancel Not Supported","originalRequest":{"method":"POST","header":[{"key":"Content-Type","value":"application/json"},{"key":"Authorization","value":"Bearer {{access_token}}"}],"body":{"mode":"raw","raw":"{\n \"pass_id\": \"sim-user-001\",\n \"reason\": \"User request\"\n}"},"url":"{{base_url}}/v1/pass/cancel"},"status":"Bad Request","code":400,"_postman_previewlanguage":"Text","header":[{"key":"Content-Type","value":"application/json"}],"cookie":[],"responseTime":null,"body":"{\n \"error\": \"not_supported\",\n \"error_description\": \"Airalo eSIM cancellation is not supported.\",\n \"code\": 400\n}"}],"_postman_id":"0a140afe-f369-4d80-9540-a3f5cca31b48"},{"name":"Query Transactions","id":"71c1ed63-906f-4071-9f41-43a4e7d6d102","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"auth":{"type":"bearer","bearer":{"basicConfig":[{"key":"token","value":"{{access_token}}"}]},"isInherited":false},"method":"POST","header":[],"body":{"mode":"raw","raw":"{\n \"start_date\": \"\",\n \"end_date\": \"\",\n \"pass_ids\": [\n \"asdb12312\",\n \"bdfb1231\"\n ],\n \"offset\": 0,\n \"limit\": 100\n}","options":{"raw":{"language":"json"}}},"url":"{{base_url}}/v1/pass/transactions","description":"Bundle passes: Cancel is not supported directly on a bundle parent pass. Each child service must be cancelled individually (future feature). Returns
\n400 unsupported_provider_operationif attempted.
The Query Transactions API endpoint enables client to fetch lounge visit and transaction history for cardholders within a specified date range. It supports querying by a single pass_id or aggregating across all cards linked to your client account. Transactions include details like visit dates, lounges, guests, and costs, abstracted from Collinson's backends (e.g., Priority Pass transaction history with dates/guests/transactions, or LoungeKey status-derived usage). This facilitates finance reporting, audits, and loyalty monitoring, aligning with Collinson's emphasis on enriching cardholders through rewards (e.g., tracking high-value benefits like lounge access).
\nKey Features: Flexible filtering (single card or all); pagination support; returns aggregated summaries if requested.
\nUse Case: Retrieve period-based reports for billing, compliance, or user insights; e.g., all December visits across cards.
\nThe request body is JSON (Content-Type: application/json). Dates required; card_id optional for single vs. all.
\nSuccessful responses (200 OK) return JSON with transaction array. Error responses as above.
\n","urlObject":{"path":["v1","pass","transactions"],"host":["{{base_url}}"],"query":[],"variable":[]}},"response":[{"id":"adafd002-47d5-4aca-8d0f-7e026382928b","name":"Success (multi-card)","originalRequest":{"method":"POST","header":[],"body":{"mode":"raw","raw":"{\n \"start_date\": \"2025-01-01\",\n \"end_date\": \"2025-12-31\",\n \"pass_ids\": [\n \"asdsa12313\",\n \"ajjjhhj12778s\"\n ],\n \"offset\": 0,\n \"limit\": 100\n}","options":{"raw":{"language":"json"}}},"url":"{{base_url}}/v1/pass/transactions"},"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json","description":"","type":"text"}],"cookie":[],"responseTime":null,"body":"{\n \"transactions\": [\n {\n \"date\": \"2025-11-01\",\n \"lounge_id\": \"LAX001\",\n \"lounge_name\": \"LAX Lounge\",\n \"guests\": 1,\n \"cost\": 80,\n \"transaction_id\": \"tx123\",\n \"pass_id\": \"tokenized_pan_123\",\n \"extra_info\": {\n \"BUUID\": \"ASDHADS1231\",\n \"time\": 12321312312\n }\n },\n {\n \"date\": \"2025-12-05\",\n \"lounge_id\": \"JFK002\",\n \"lounge_name\": \"JFK Lounge\",\n \"guests\": 0,\n \"cost\": 40,\n \"transaction_id\": \"tx456\",\n \"pass_id\": \"tokenized_pan_456\",\n \"extra_info\": {\n \"BUUID\": \"ASDHADS1231\",\n \"time\": 12321312312\n }\n }\n ],\n \"total_count\": 120,\n \"offset\": 0,\n \"next_offset\": 50\n}"},{"id":"f2dc53b1-d6a1-4148-9873-69b156c69273","name":"Success (all-card)","originalRequest":{"method":"POST","header":[],"body":{"mode":"raw","raw":"{\n \"start_date\": \"2025-01-01\",\n \"end_date\": \"2025-12-31\",\n \"offset\": 0,\n \"limit\": 100\n}","options":{"raw":{"language":"json"}}},"url":"{{base_url}}/v1/pass/transactions"},"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json","description":"","type":"text"}],"cookie":[],"responseTime":null,"body":"{\n \"transactions\": [\n {\n \"date\": \"2025-11-01\",\n \"lounge_id\": \"LAX001\",\n \"lounge_name\": \"LAX Lounge\",\n \"guests\": 1,\n \"cost\": 80,\n \"transaction_id\": \"tx123\",\n \"pass_id\": \"ouasd78123\",\n \"extra_info\": {\n \"BUUID\": \"ASDHADS1231\",\n \"time\": 12321312312\n }\n },\n {\n \"date\": \"2025-12-05\",\n \"lounge_id\": \"JFK002\",\n \"lounge_name\": \"JFK Lounge\",\n \"guests\": 0,\n \"cost\": 40,\n \"transaction_id\": \"tx456\",\n \"pass_id\": \"hyasd7812321\",\n \"extra_info\": {\n \"BUUID\": \"ASDHADS1231\",\n \"time\": 12321312312\n }\n }\n ],\n \"total_count\": 150,\n \"offset\": 0,\n \"next_offset\": 50\n}"}],"_postman_id":"71c1ed63-906f-4071-9f41-43a4e7d6d102"},{"name":"Top Up Pass","id":"6ff186c9-40e8-4881-bc9b-62372f6d6e3c","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"auth":{"type":"bearer","bearer":{"basicConfig":[{"key":"token","value":"{{access_token}}"}]},"isInherited":false},"method":"POST","header":[{"key":"Content-Type","value":"application/json","type":"text"}],"body":{"mode":"raw","raw":"{\n \"pass_id\": \"{{pass_id}}\",\n \"plan_id\": \"{{plan_id}}\",\n \"enrol_token\": \"ASDU78123AASDGJ\",\n \"card_type\": \"MC\",\n \"holder\": {\n \"first_name\": \"John\",\n \"last_name\": \"Doe\",\n \"address\": {\n \"address_line_1\": \"123 Main St\",\n \"city\": \"Hong Kong\",\n \"country_code\": \"HKG\"\n }\n }\n}"},"url":"{{base_url}}/pass/topup","description":"The Top Up Pass API endpoint enables renewal of an existing pass by cancelling the current provider membership and re-enrolling with a new plan and token. The same pass_id is preserved — all transaction history remains under the same pass account.
\nThe topup behaviour depends on the provider determined by the new plan_id:
Syncs transaction history from current membership (best-effort)
\nArchives old provider membership ID to pass_provider_history
Cancels current membership at the provider
\nRe-enrols with the new plan_id and enrol_token
\nUpdates existing pass record with new provider data
\nNote: If cancel succeeds but re-enrolment fails, the pass is marked cancelled (old membership already terminated).
Archives the current ICCID to pass_provider_history (action: topup_esim)
Skips cancel — the existing ICCID is preserved
\nCalls the Airalo top-up API to add data/days to the same SIM card
\nUpdates expiry and plan details on the existing pass record
\nThe pass_id and iccid never change on eSIM topup. Each topup increments topup_count.
{ \"pass_id\": \"abc-123\", \"type\": \"priority\", \"status\": \"active\", \"dmc_qr_data\": \"PP/260326/NEWQR\", \"topup_count\": 1, \"expiry\": \"2027-03-26\" }400 invalid_request — missing required fields:
{ \"error\": \"invalid_request\", \"error_description\": \"pass_id is required.\", \"code\": 400 }
400 invalid_state — pass has no provider membership:
{ \"error\": \"invalid_state\", \"error_description\": \"Pass has no provider membership to cancel.\", \"code\": 400 }
404 pass_not_found:
{ \"error\": \"pass_not_found\", \"error_description\": \"Pass not found: abc-123\", \"code\": 404 }
404 invalid_plan — no routing rule for plan_id:
{ \"error\": \"invalid_plan\", \"error_description\": \"No active routing rule found for plan_id: XYZ\", \"code\": 404 }
409 already_cancelled:
{ \"error\": \"already_cancelled\", \"error_description\": \"Pass is already cancelled.\", \"code\": 409 }
4xx/5xx provider errors — cancel or enrol failure forwarded from provider:
{ \"error\": \"cancel_forbidden\", \"error_description\": \"Not allowed in UAT\", \"code\": 403 }
Note: If the cancel succeeds but re-enrolment fails, the pass is marked as cancelled because the old membership has already been terminated at the provider.
The request body is JSON (Content-Type: application/json).
\nSuccessful responses (200 OK) return JSON with updated pass details.
\n\n\nBundle passes: Topup is not supported directly on a bundle parent pass. Each child service must be topped up individually (future feature). Returns
\n400 unsupported_provider_operationif attempted.
The Daily Report API returns pass transaction records for a specific date, scoped to the authenticated partner. Useful for daily reconciliation and reporting.
\nResults are returned in pages of 200 records. Use the page parameter to navigate through results. The response includes total_count, total_pages, and page_size for easy pagination handling.
The request body is JSON (Content-Type: application/json).
\nSuccessful responses (200 OK) return JSON with transaction records and pagination metadata.
\n{ \"error\": \"invalid_request\", \"error_description\": \"date must be a valid date in YYYY-MM-DD format.\", \"code\": 400 }Search for lounges by various criteria. The gateway translates partner snake_case parameters to Collinson's lounge catalogue API and returns normalized snake_case data. The gateway automatically requests Location, Facilities, and Media detail sections — partners do not need to specify this.
pass_id is provided, the gateway resolves the membership number and deal ID automatically — partner clients never need to supply provider-specific identifiers.The request body is JSON (Content-Type: application/json). pass_id is required. All other filters are optional.
* At least one starred parameter must be provided. When pass_id is used, the pass must exist and have an active provider membership.
Successful responses (200 OK) return JSON with snake_case lounge fields. The gateway always requests Location, Facilities, and Media from Collinson, so these fields appear in the response whenever the provider returns them.
Find lounges at the nearest airport to the user's current GPS coordinates. The gateway resolves the coordinates to the closest airport via Google Places, queries Collinson for all lounges at that airport, and returns them sorted by distance from the submitted location (nearest first).
\nThe request body is JSON (Content-Type: application/json). pass_id, latitude, and longitude are required.
Successful responses (200 OK) return a nearest_airport block and an array of lounges sorted by distance_km ascending. Lounges without GPS coordinates are included but appear at the end of the list.
The Batch Create Passes Webhook provides asynchronous notifications to client upon completion of a batch pass creation job, delivering results (successes, failures, per-item details) without polling. This enhances efficiency for large-scale operations, abstracting batch processing into push-based updates. Notifications include aggregated status, allowing user system to handle finance reports/audits seamlessly.
\nUse Case: Receive real-time batch outcomes (e.g., for campaigns issuing 1000+ passes) to update user's systems or notify users.
\nSecurity Notes: Attend shared secret in X-Signature header. Use HTTPS for your URL.
\nOur system sends POST JSON to your URL. Verify X-Signature header (HMAC-SHA256 of body using shared secret).
\n