> ## 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.

# Tokenization on Request (Gateway)

> Intercept inbound HTTP requests containing card data. PCI Booking tokenizes card numbers and forwards sanitized requests.

Tokenization on Request lets you intercept inbound HTTP requests from third parties before they reach your systems. PCI Booking sits as a gateway in front of your API. When a third party sends a request containing card data, PCI Booking tokenizes the card details and forwards a sanitized version to you. You never see raw card numbers.

To see how this method fits with the other three ways card data passes between you and a third party, see [Working with Third Parties](/concepts/working-with-third-parties).

## How It Works

1. **PCI Booking sets up a gateway endpoint**. The gateway is configured with your SSL certificate and a custom site name. Third parties send their requests to this gateway URL instead of directly to your API.
2. **Third party sends a request**. The request arrives at the PCI Booking gateway.
3. **Message filtering**. The gateway checks the request against pre-configured message filters, based on the URL path or specific headers. A path filter is an exact, case-sensitive match on the request path: `/api/bookings` and `/api/bookings/` are different paths. Tell support every path variant your callers use. If a request matches no filter, it is relayed to your API unchanged, with the card data in clear text and no token header.
4. **Card extraction and tokenization**. If the message matches a filter, PCI Booking parses the message body using [content filters](/account-setup/content-filters) that define where card data is located. All matching cards are tokenized.
5. **Sanitized relay**. PCI Booking masks the card details in the message body, adds the token URIs to a request header (typically `x-Token`), and forwards the amended request to your API.
6. **Response relay**. Your API's response is relayed back to the original sender.

```mermaid theme={null}
sequenceDiagram
    participant TP as Third Party
    participant PCIB as PCI Booking Gateway
    participant You as Your API

    TP->>PCIB: Request with card data<br/>(sent to your gateway URL)
    Note over PCIB: Match message filter,<br/>extract & tokenize cards
    PCIB->>You: Sanitized request<br/>(cards masked, tokens in x-Token header)
    You-->>PCIB: Your response
    PCIB-->>TP: Response relayed as-is
```

<Info>
  While the flow above refers to one card, PCI Booking can tokenize all cards in the request, as many as are present, as long as the content filter identifies their locations.
</Info>

## What PCI Booking Adds to the Request

Before forwarding the request to your API, PCI Booking adds several headers:

* **Token header** (typically `x-Token`). Contains the token URI(s) for the card(s) found in the request.
* **`X-Forwarded-For`**. The original sender's IP address.
* **Error/warning headers**. If tokenization fails or encounters issues, diagnostic information is added.

## Target Profiles

The gateway uses a [target profile](/account-setup/target-profiles) to know where card data appears in the inbound request and how to tokenize it. Each profile includes [content filters](/account-setup/content-filters) that define the location of card fields in the message. The PCI Booking support team configures this as part of the gateway setup.

## Setting Up a Gateway Endpoint

Gateway setup is done by the PCI Booking support team. To set up a new gateway endpoint, contact [support@pcibooking.net](mailto:support@pcibooking.net) with the following details:

* Your PCI Booking username.
* The target URI where processed messages should be relayed to (your API endpoint).
* How to identify requests that contain card data. This can be based on URL path or a specific request header.
* A sample of the message structure (XML or JSON) that should be processed.
* How to handle duplicate cards:
  * **Eliminate duplicates (true)**. If a card already exists as a token, the existing token is returned. If the new message includes a CVV, it's stored on the existing token and its CVV retention policy is reset to your account default - see [CVV Policy and Duplicate Card Handling](/capture-cards/cvv-retention-policy#cvv-policy-and-duplicate-card-handling).
  * **No deduplication (false)**. Every card processed gets a new token, regardless of whether it already exists.

If the third party sending requests to this gateway needs to whitelist PCI Booking's origin, see [Outbound IP Addresses](/reference/outbound-ips).

<Note>
  Setup also typically involves DNS/subdomain configuration pointing to your gateway endpoint, an SSL certificate for that endpoint, and a separate migration step when you're ready to move the endpoint from sandbox to production. These are worked out with the support team as part of setup - mention them up front if you're planning ahead.

  If the endpoint runs under your own domain name, you supply the SSL certificate and every renewal. Send a renewed certificate to support at least two weeks before the current one expires; installation is a manual step on our side. PCI Booking does not issue or auto-renew certificates (for example through Let's Encrypt) for customer domains.
</Note>

## Payload Requirements

The structure, layout, and naming convention of the payload are up to you to define with your partners - when creating the profile, the PCI Booking team maps the card data fields to your message structure. Make sure your API requires partners to send the data needed for tokenization:

* **Minimum required fields**: the card number (PAN) and expiration date.
* The gateway can tokenize both card data and 3DS authentication results.

Example of a simple message payload with all possible data fields:

```xml Payload sample theme={null}
<?xml version="1.0" encoding="UTF-8"?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
   <soap:Body>
      <AcceptFromMeCC>
         <payCard>
            <ccInfo>
               <Cc_type>Visa</Cc_type>
               <FirstName>John</FirstName>
               <LastName>Doe</LastName>
               <Cc_number>4580458045804580</Cc_number>
               <Cc_date_month>10</Cc_date_month>
               <Cc_date_year>2028</Cc_date_year>
               <Cc_cvv>123</Cc_cvv>
               <AuthenticationValue>AAACBDgxAnlENWNRSTECEwAAAAA=</AuthenticationValue>
               <eci>05</eci>
               <id>cnFwcXVLRjlKZ2pPeGpySzJieGQ=</id>
               <Version>1.0</Version>
            </ccInfo>
         </payCard>
      </AcceptFromMeCC>
   </soap:Body>
</soap:Envelope>
```

<Info>
  **3DS data:** the authentication result always contains the AuthenticationValue (CAVV) and ECI. Depending on the 3DS version used, the merchant will have either the XID value (3DS v1) or the 3DS\_Trans\_ID value (3DS v2). Both are stored in PCI Booking interchangeably under the same field. See [3DS Auth Management](/manage-tokens/3ds-auth-management) for how this data is used once stored.

  3DS data is stored only when your profile includes selectors for the 3DS fields. Without them, 3DS values in the message are not stored on the token. Ask support to add them to your profile.
</Info>

## Timeout and Failure Handling

If your API does not respond within the gateway's configured timeout, or responds with `403 Forbidden`, PCI Booking **deletes any tokens created during that request** and returns an error (a timeout returns `504 Gateway Timeout`) rather than leaving orphaned tokens behind.

## Use Cases

* Receiving reservation or booking requests from OTAs or channel managers that include card details.
* Any scenario where a third party pushes card data to your API and you want to keep card data off your servers.

## Next Steps

<CardGroup cols={2}>
  <Card title="Tokenization on Response" icon="book" href="/capture-cards/tokenization-on-response">
    The reverse direction. Tokenize card data in responses from third parties.
  </Card>

  <Card title="Capture Cards Overview" icon="book" href="/capture-cards/overview">
    All available tokenization methods.
  </Card>
</CardGroup>


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