Skip to main content
If you are a Booking.com connectivity partner, such as a property management system, channel manager or booking engine, your system pulls reservations from Booking.com’s secure supply endpoints. Each reservation can carry a guest card or a Booking.com virtual card. This guide covers the two halves of taking those cards without bringing card data into your own servers:
  1. Receiving the card: the capture method that fits Booking.com, the ready-made profiles, the exact request, and what Booking.com needs from you first.
  2. Using the token: what connectivity partners usually add once the card is a token, with a link to the page for each.

​
Part 1: Receiving the Card from Booking.com

​
How Booking.com releases card data

Booking.com does not push reservations. Your system calls Booking.com’s secure supply host, secure-supply-xml.booking.com, with your own Booking.com machine account credentials, and Booking.com returns the reservations with the card inside the XML. That host serves two generations of API: the B.XML reservations endpoint and the OTA OTA_HotelResNotif and OTA_HotelResModifyNotif endpoints. That shape decides the capture method. The reservation is fetched, not pushed, so you use Tokenization on Response: you send the pull through PCI Booking, PCI Booking calls Booking.com, tokenizes every card in the response, and returns the reservations to you with the cards masked and the tokens in a header. Because PCI Booking makes the call, it is PCI Booking’s address that Booking.com sees, and PCI Booking’s PCI DSS attestation that supports your own.

​
Before you start

  • A Booking.com machine account. The pull is made with your own Booking.com credentials. PCI Booking does not hold a Booking.com account and cannot pull on its own behalf.
  • Allow-list PCI Booking on that machine account. Booking.com checks the address a request comes from against the allow-list of the machine account. The call comes from PCI Booking, so add PCI Booking’s outbound IP addresses to your machine account in the Booking.com Provider Portal. The same list serves PCI Booking sandbox and live accounts. The list may change, so check that page rather than copying addresses from elsewhere. Until the allow-list is in place, Booking.com answers 401 and nothing is tokenized.
  • A test property on Booking.com. PCI Booking cannot supply Booking.com test reservations. Use your own test property and Booking.com’s test bookings. See Testing.

​
Step 1: Choose the profile

PCI Booking maintains ready-made universal profiles for the three Booking.com endpoints, so there is no profile to write: All three send POST to Booking.com, wait up to 120 seconds for the reply, and take no path segments. The B.XML profile reads the customer block of each reservation: card number, expiration date, cardholder name, CVC, card type and issue number. The OTA profiles read the PaymentCard element under GuaranteeAccepted: card number, expiration date, cardholder name, CVC and card code. The current list of universal profiles is returned by Get Tokenization Profiles. Your Booking.com credentials pass through PCI Booking unchanged. For B.XML they sit in the request body as Booking.com specifies. For the OTA endpoints they go in the Authorization: Bearer header. PCI Booking’s own authentication for this endpoint is an access token or session token in the query string, never the Authorization header, so that header stays free for Booking.com.

​
Step 2: Send the pull through PCI Booking

Call Tokenize on Response Using Preset Profiles with the profile name in the path. The body and headers are exactly what you would send to Booking.com directly. B.XML:
OTA new reservations:
OTA modifications use the same request with BookingComModificationRequest in the path.

​
What comes back

  • Status 201: at least one new token was created. Status 200: every card already existed and eliminateCardDuplication returned the existing tokens.
  • X-pciBooking-cardUri header: the token URIs. A pull usually holds several reservations, so this header holds several tokens separated by ;, in the order the cards appear in the XML. Store each one against its reservation.
  • Body: Booking.com’s XML as Booking.com sent it, with the card number and CVC masked. The cardholder name is returned as received. Everything else, including the expiration date, card type and the virtual card attributes, comes back unchanged, so your existing parsing of the reservation keeps working.
  • X-pciBooking-Tokenization-Errors header: one entry per card that could not be tokenized, separated by ;;. A card with an error has no entry in the token header. Reservations that carry no card, such as bank-transfer bookings, cancellations or some modifications, produce entries like Number has less than 12 digits and Expired card. These are not failures of the pull: the status stays 2xx, the other reservations are tokenized, and the reservation without a card is returned to you as it was.
  • X-pciBooking-Tokenization-Warnings header: present only when PCI Booking wants to tell you something about a card that was still tokenized.
  • Any non-2xx status from Booking.com is passed to you unchanged, with Booking.com’s own body, and nothing is tokenized. A 401 from Booking.com means the machine account credentials are wrong or PCI Booking’s addresses are not on its allow-list yet.
The CVC is stored only when you send saveCVV=true, and then the CVV retention policy decides how long it stays and what it may be used for. Set an account-wide default once and it applies to every token from every pull.

​
Booking.com behaviours to plan for

The first pull is the only pull on B.XML. Booking.com’s reservations endpoint removes a reservation from the queue once it has been served. If your side fails after PCI Booking has returned the response, that reservation and its token are only in that response. Store the tokens from the response before you treat the pull as done. PCI Booking does not keep a copy of the response body. The OTA endpoints let you acknowledge reservations explicitly, which is one reason partners move to them. CVC of 000 on B.XML. At the time of writing, the B.XML endpoint returns 000 in the CVC field when the guest gave no CVC, and the OTA endpoints omit the field instead. PCI Booking stores the value it receives, so a token created from B.XML can carry a CVC of 000. Treat that value as no CVC. Virtual cards. Booking.com virtual cards arrive in the same card element as guest cards. The OTA XML adds attributes such as the effective date, current balance, decimal places, currency code and virtual card expiration date; B.XML carries equivalent fields alongside the card. PCI Booking tokenizes a virtual card exactly like any other card. The extra attributes are not card data, so they come back readable and you keep them with the token. When you charge the virtual card later, whether the CVC goes with it depends on the token’s CVV retention policy. No 3-D Secure data. Booking.com cards arrive without authentication data. If a hotel’s acquirer requires strong customer authentication, that is a matter between the hotel and the acquirer; there is nothing in the feed for PCI Booking to pass on.

​
Modifications

When a modified reservation arrives with the same card, send eliminateCardDuplication=true and PCI Booking returns the token you already hold instead of creating a second one. A duplicate is a card with the same number and expiration date. If the pull carries a CVC, it is stored on the existing token and that token’s CVV retention policy is reset to your account default. See Duplicate Card Handling.

​
Your own profile instead of the preset

If you pull from a Booking.com endpoint the three profiles do not cover, or you want to control which fields are tokenized, create your own target profile and call it through Tokenization in Response, with the Booking.com URL in targetURI and httpMethod=POST. Send a sample response to support@pcibooking.net and our team builds the content filter for you.

​
Compliance

Booking.com asks its connectivity partners for PCI DSS evidence. With PCI Booking in the path, Booking.com’s card data reaches PCI Booking, not your servers. The documents you can request from PCI Booking for your own compliance process, and the statement to give a third party that asks, are on PCI Scope and Compliance. PCI Booking is not a Qualified Security Assessor, so which questionnaire you file is for you and your assessor to decide.

​
Testing

The three profiles point at Booking.com’s production host. Test with a PCI Booking sandbox account, your own Booking.com test property and Booking.com’s test bookings, with PCI Booking’s addresses allow-listed on the machine account you use for testing. See Testing and Going Live.

​
Part 2: What to Do with the Token

Once the card is a token, these are the things connectivity partners most often add. Each one works with the tokens from Part 1 as they are.

​
Show the card to hotel staff

Most properties key the card into their own terminal, so staff need to see it. Two options:
  • Card Display: an iframe inside your own portal. You decide who may log in and who may view cards. The card renders inside PCI Booking’s domain, so nothing reaches your servers.
  • Card Display with OTP: a hosted page when you have no portal or do not want to manage viewer access. PCI Booking emails the viewer a link and verifies their phone with a code before showing the card.
Whether the CVC is shown depends on the token’s CVV retention policy. Viewing in your own portal is the Owner destination; the hosted page is OtpCardView. See Destination Types.

​
The CVC

PCI DSS does not allow the CVC to stay with the card once the card has been used. Your CVV retention policy is where you define what “used” means for your business: how long the CVC may stay, and how many times it may go to each destination, for example a hotel viewing it or a charge through a payment gateway. The policy cannot be changed on an existing token, so decide it before the first pull is tokenized.

​
Charge through the hotel’s own payment provider

Use the Universal Payment Gateway to charge the token through the property’s own PSP account. You store PSP credentials once per hotel under a credentialsId of your choosing, then name that ID on each charge, pre-authorization, capture or refund. The money settles with the hotel. Charge Multiple Hotels’ Gateways From One Account walks through the pattern. For the current list of gateways, with each gateway’s capability flags, call Get Payment Gateways.

​
Send the card to any HTTPS endpoint

When a property’s acquirer or system is not on the gateway list but has an API, use Token Replacement in Request. You build the request the way that API expects it, with the token in place of the card, and send it through PCI Booking. PCI Booking inserts the card number in transit. Register the destination under relay restrictions if your account uses them, and give the destination PCI Booking’s outbound IP addresses if it allow-lists callers.

​
Retention and deletion

Tokens do not expire on their own. Delete a token with Delete Token when the reservation no longer needs it, for example a set number of days after departure, driven from your own system. If a token without a CVC has no value to you, set DeleteCardUponCvvCleanup on the CVV retention policy and the token is removed when its CVC is cleared. See Delete Tokens and Token Lifetime.

​
Many hotels on one account

One PCI Booking account serves all your properties. Use ref on each pull to tag the tokens, store one set of PSP credentials per hotel, and route each transaction with credentialsId. The hotels do not need PCI Booking accounts of their own.

​
Next Steps

Tokenization on Response

The capture method behind the Booking.com profiles.

Universal Tokenization Profiles

How ready-made profiles work.

PCI Scope and Compliance

The documents to request and what to tell a third party.

Testing and Going Live

Sandbox, test data and the move to production.