> ## Documentation Index
> Fetch the complete documentation index at: https://developers.pcibooking.net/llms.txt
> Use this file to discover all available pages before exploring further.

# Receiving Cards from Booking.com

> How a Booking.com connectivity partner pulls reservations through PCI Booking so that guest cards and virtual cards arrive as tokens, and what to do with the tokens afterwards.

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](#part-1-receiving-the-card-from-booking-com): 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](#part-2-what-to-do-with-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](https://developers.pcibooking.net/capture-cards/tokenization-on-response.md): 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](https://developers.pcibooking.net/reference/outbound-ips.md) 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](#testing).

### Step 1: Choose the profile

PCI Booking maintains ready-made [universal profiles](https://developers.pcibooking.net/capture-cards/universal-tokenization.md) for the three Booking.com endpoints, so there is no profile to write:

| Profile name | Calls | Use it for |
| - | - | - |
| `Booking_com` | `https://secure-supply-xml.booking.com/hotels/xml/reservations` | B.XML reservations |
| `BookingComReservationRequest` | `https://secure-supply-xml.booking.com/hotels/ota/OTA_HotelResNotif` | OTA new reservations |
| `BookingComModificationRequest` | `https://secure-supply-xml.booking.com/hotels/ota/OTA_HotelResModifyNotif` | OTA modifications |

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](https://developers.pcibooking.net/api-reference/tokenize-cards/get-tokenization-profiles.md).

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](https://developers.pcibooking.net/api-reference/tokenize-cards/tokenize-on-response-using-preset-profiles.md) with the profile name in the path. The body and headers are exactly what you would send to Booking.com directly.

B.XML:

```bash theme={null}
curl -X POST "https://service.pcibooking.net/api/booker/Booking_com/reservation?accessToken=your-access-token&saveCVV=true&eliminateCardDuplication=true" \
  -H "Content-Type: application/xml" \
  --data-binary @your-bxml-request.xml
```

OTA new reservations:

```bash theme={null}
curl -X POST "https://service.pcibooking.net/api/booker/BookingComReservationRequest/reservation?accessToken=your-access-token&saveCVV=true&eliminateCardDuplication=true&fwd=hotel_ids%3D123456" \
  -H "Authorization: Bearer your-booking-com-token" \
  -H "Content-Type: application/xml" \
  --data-binary @your-ota-request.xml
```

OTA modifications use the same request with `BookingComModificationRequest` in the path.

| Part of the request | What to send |
| - | - |
| `accessToken` or `sessionToken` | PCI Booking authentication. This endpoint takes an [access token](https://developers.pcibooking.net/getting-started/authentication.md#access-token) or a [session token](https://developers.pcibooking.net/api-reference/general/start-temporary-session.md), not the API key. |
| Body and headers | Whatever Booking.com requires for the endpoint: B.XML credentials in the body, or the `Authorization: Bearer` header for OTA. They are forwarded to Booking.com unchanged. |
| `fwd` | Query string parameters for Booking.com, URL-encoded, for example the hotel IDs, the last-change timestamp or a limit. PCI Booking appends them to the Booking.com URL. |
| `saveCVV` | `true` to keep the CVC on the token. The default discards it. |
| `eliminateCardDuplication` | `true` to get the existing token back when the card is already stored. See [Modifications](#modifications). |
| `ref` | Your own reference, so you can find the tokens later with [Query Tokens](https://developers.pcibooking.net/api-reference/manage-tokens/query-tokens.md). A pull returns many reservations, so a per-pull reference is more useful than a booking ID here. |

### 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](https://developers.pcibooking.net/capture-cards/cvv-retention-policy.md) 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](https://developers.pcibooking.net/capture-cards/cvv-retention-policy.md).

**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](https://developers.pcibooking.net/capture-cards/tokenization-on-response.md#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](https://developers.pcibooking.net/account-setup/target-profiles.md) and call it through [Tokenization in Response](https://developers.pcibooking.net/api-reference/tokenize-cards/tokenization-in-response.md), with the Booking.com URL in `targetURI` and `httpMethod=POST`. Send a sample response to [support@pcibooking.net](mailto: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](https://developers.pcibooking.net/concepts/pci-scope-and-compliance.md). 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](https://developers.pcibooking.net/getting-started/testing-and-going-live.md).

## 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](https://developers.pcibooking.net/use-tokens/card-display.md): 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](https://developers.pcibooking.net/use-tokens/card-display-otp.md): 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](https://developers.pcibooking.net/capture-cards/cvv-retention-policy.md#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](https://developers.pcibooking.net/capture-cards/cvv-retention-policy.md) 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](https://developers.pcibooking.net/use-tokens/universal-payment-gateway.md) to charge the token through the property's own PSP account. You store [PSP credentials](https://developers.pcibooking.net/account-setup/gateway-credentials.md) 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](https://developers.pcibooking.net/use-cases/multi-hotel-gateway-routing.md) walks through the pattern. For the current list of gateways, with each gateway's capability flags, call [Get Payment Gateways](https://developers.pcibooking.net/api-reference/process-cards/get-payment-gateways.md).

### 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](https://developers.pcibooking.net/use-tokens/token-replacement-in-request.md). 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](https://developers.pcibooking.net/account-setup/security-settings.md#relay-restrictions) if your account uses them, and give the destination PCI Booking's [outbound IP addresses](https://developers.pcibooking.net/reference/outbound-ips.md) if it allow-lists callers.

### Retention and deletion

Tokens do not expire on their own. Delete a token with [Delete Token](https://developers.pcibooking.net/api-reference/manage-tokens/delete-token.md) 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](https://developers.pcibooking.net/manage-tokens/delete-tokens.md) and [Token Lifetime](https://developers.pcibooking.net/concepts/tokenization-explained.md#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

> [card] [Tokenization on Response](https://developers.pcibooking.net/capture-cards/tokenization-on-response.md)
>
> The capture method behind the Booking.com profiles.

> [card] [Universal Tokenization Profiles](https://developers.pcibooking.net/capture-cards/universal-tokenization.md)
>
> How ready-made profiles work.

> [card] [PCI Scope and Compliance](https://developers.pcibooking.net/concepts/pci-scope-and-compliance.md)
>
> The documents to request and what to tell a third party.

> [card] [Testing and Going Live](https://developers.pcibooking.net/getting-started/testing-and-going-live.md)
>
> Sandbox, test data and the move to production.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.