Skip to main content
This workflow covers the full lifecycle of a guest’s card: capturing it on first visit, charging it, and storing a PCI DSS compliant token for future use. By tokenizing at capture time, you can process recurring payments and send card details to a property management system (PMS) without ever handling raw card data.

​
Capture and charge a new customer’s card

When a new customer arrives (or a returning customer provides a new card), use the Payments Library to handle card capture, payment, and tokenization in a single flow. The Payments Library renders a secure card form inside your checkout page, processes the payment through your PSP, and returns a token, all without card data touching your servers.

​
Step 1: Set Up the Payments Library

Integrate the Payments Library into your web or mobile application. The library handles the card form UI, payment processing, and tokenization. You can render the card form in popup mode (opens a modal overlay) or iframe mode (embeds directly in your page layout). Both modes keep card data inside PCI Booking’s secure environment.

​
Step 2: Initiate a Charge and Tokenize Session

Your backend calls the PCI Booking API to create a session with the CHARGE_AND_TOKENIZE operation type. This session specifies the PSP credentials, charge amount, and currency. PCI Booking returns a signed session token (JWS) that your frontend passes to the Payments Library. The session token is single-use and expires after a short period, so it must be created fresh for each transaction.

​
Step 3: Customer completes the payment

The Payments Library displays the card form (or digital wallet buttons for Apple Pay, Google Pay, etc.) to the customer. The customer enters their card details or selects a wallet. The library sends the card data directly to PCI Booking, which charges the card through your configured PSP and tokenizes the card in one step. Your frontend receives a callback with the transaction result and the token.

​
Step 4: Store the Token

Once the Payments Library completes processing, PCI Booking returns the token (a cardURI). Store this token in the customer’s profile in your system for future use. The token is safe to store in any database since it contains no actual card data. You can query the token later to retrieve metadata such as the masked card number, brand, and expiry date without accessing the real card number.

​
Charge a returning customer’s stored card

When a returning customer makes a new reservation and wants to use their stored card, charge it directly through the API using the token you stored earlier. There is no need to recapture the card or present a payment form.

​
Step 1: Send a Charge Request

Use the Universal Payment Gateway to send a charge request to the selected PSP using the stored token. Pass the cardURI token, amount, currency, and your PSP credentials. PCI Booking retrieves the real card data from its vault and submits the charge to the PSP on your behalf.

​
Step 2: Handle the Response

PCI Booking returns the PSP’s response, including approval status, transaction reference, and any error codes. Store the transaction reference for later use if you need to process a refund or void. If the charge fails (for example, due to insufficient funds or an expired card), the token remains valid and you can retry or prompt the customer to provide a new card.

​
Handling Expired Cards

If a returning customer’s card has expired since their last visit, you do not need to collect the full card number again. Use the Update Expired Card flow to refresh the token with a new expiration date or new card details while preserving the existing token reference in your system.

​
Sending Card Details to a PMS

When you need to send card details to a Property Management System (PMS), use Token Replacement to inject the real card data into an outgoing API request to the PMS. The card data never passes through your servers.