Skip to main content
Token Replacement in Response lets you send card data to a third party without making the outbound call yourself. PCI Booking sits as a gateway in front of your API. When a third party sends a request, your API processes it and responds with tokens. PCI Booking replaces the tokens with real card data before relaying the response back to the sender. This is the mirror of Tokenization on Request in the Capture Cards section. Both use the same gateway infrastructure, but in opposite directions: Tokenization on Request tokenizes card data in the third party’s inbound request, while Token Replacement in Response detokenizes tokens in your outbound response.

​
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. Request forwarded to your API. PCI Booking relays the request to your API endpoint (with optional tokenization of inbound card data).
  4. Your API responds with tokens. Your API processes the request and returns the card token(s) in the x-pciBooking-cardUri response header. The response body contains the message structure the third party expects, with the card field locations defined by your profile’s content filter.
  5. Token replacement. PCI Booking reads the token(s) from the header, retrieves the real card data, and injects it into the response body at the locations defined by the profile’s content filter. The header is removed before the response leaves PCI Booking.
  6. Response relayed to sender. The third party receives the response with real card data. Your systems never handled raw card details.
Response compression: gzip and deflate are supported. If your API compresses the response, set the Content-Encoding header accordingly; omit it when the response is uncompressed.

​
Worked Example

A channel manager sends a reservation lookup to your gateway URL, expecting the card details back in the response. 1. Third party’s request (forwarded to your API unchanged):
2. Your API’s response - the token URI goes in the x-pciBooking-cardUri header, and the body has a placeholder wherever the real card data should end up:
3. What the third party actually receives - PCI Booking reads the token from the header, injects the real card data at the locations defined by your profile’s content filter, and strips the header before relaying the response:
Your API never sees or handles the real card number - it only ever works with the token.

​
Bi-Directional: Tokenize and Detokenize in One Call

The same gateway can handle both directions simultaneously:
  • Inbound: Tokenize card data in the third party’s request before it reaches your API (Tokenization on Request).
  • Outbound: Replace tokens in your API’s response with real card data before relaying back to the sender (this page).
This means a single gateway endpoint can keep card data off your systems in both directions.
If you need the CVV included when relaying to the third party, the token’s CVV retention policy must have an IpAddress destination matching the requester’s IP - otherwise the CVV is stripped even if the token has one stored.

​
Target Profiles

The gateway uses a target profile to know where tokens appear in your response and how to replace them. Each profile includes 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 the Gateway

Gateway setup is done by the PCI Booking support team. Contact support@pcibooking.net with:
  • Your PCI Booking username.
  • The target URI where requests should be relayed to (your API endpoint).
  • How to identify which responses contain tokens that need replacement.
  • A sample of your response structure (XML or JSON) showing where the card data should be injected. Remember: the token itself travels in the x-pciBooking-cardUri response header, not in the body.
If you already have a Tokenization on Request gateway set up, the same gateway can be enhanced to also perform token replacement on the response. Contact support to enable it.
If the third party sending requests to this gateway needs to whitelist PCI Booking’s origin, see Outbound IP Addresses.
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.

​
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

  • Sending card details back to a booking platform or OTA that originally sent you the reservation.
  • Responding to a channel manager’s request with card data for payment processing on their end.
  • Any scenario where a third party expects real card data in your API response.

​
Next Steps

Token Replacement in Request

The forward direction: you send requests to a third party through PCI Booking.

File Transfer Token Replacement

Send card data via SFTP/FTPS.

Use Tokens Overview

All detokenization methods.