Token Replacement in Request

Token Replacement in Request lets you send an HTTP request through PCI Booking as a transparent proxy. PCI Booking inserts the real card data into your request, forwards the request to the destination, and returns the response. Your systems never handle sensitive card details. 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.

Sending card data to a PSP to process a payment? We strongly recommend the Universal Payment Gateway instead: one standardized request for 100+ PSPs, no profile to maintain, normalized responses. See UPG vs Token Replacement for the full comparison.

How It Works

Your system builds the request exactly as the third party expects it, and sends it to the PCI Booking relay endpoint instead of to the third party. The query string names the card token (cardToken) and the destination (targetUri).
PCI Booking validates the destination against your account’s allowed endpoints (relay restrictions).
PCI Booking retrieves the card data for the token and inserts it into the request, either where you placed placeholders or where your target profile says.
The request is forwarded to the destination with the real card data.
The destination’s response is returned to your system.

What PCI Booking Changes in Your Request

PCI Booking relays the message you send as it is. The headers and body that reach the third party are the ones you sent. Only two things change:

The destination. The request goes to the URL in targetUri, including that URL’s own query string. PCI Booking’s parameters (cardToken, targetUri, profileName and so on) are not forwarded.
The card data. Card values are inserted at the locations you specify with placeholders or a profile.

You always send the relay call to PCI Booking as a POST. The third party receives the method you set in httpMethod (POST by default, or GET, PUT, PATCH, DELETE). With placeholders, the rest of the body is left exactly as you sent it. With a target profile, PCI Booking reads and rewrites the body to insert the card data, so the content stays the same but the formatting can change: JSON is re-indented, and form data is re-encoded. This means you can send any header the third party requires, for example its own Authorization header, a User-Agent, or custom X- headers, and any body format, including JSON for GraphQL APIs. A few technical headers are set by PCI Booking as part of relaying:

Header	What PCI Booking does
`Host`	Set to the host of `targetUri`.
`X-Forwarded-For`	Your system’s IP address is added.
`Accept-Encoding`	Set to `deflate`.
`Content-Type`	Sent as the media type you sent plus a `charset` (`utf-8` in placeholder mode). Other `Content-Type` parameters are dropped.
`Via` and `CloudFront-*`	Removed.

If the relayed method is GET, no body is sent.

Every header you send is forwarded to the third party. Authenticate to PCI Booking with the accessToken or sessionToken query parameter, as the relay endpoint requires, and never add your PCI Booking API key as a header on a relay request.

Choosing a Replacement Mode

There are two ways to tell PCI Booking where the card data goes in your message: placeholders in the message itself, or a target profile configured in advance.

	Placeholders	Target profile
Setup	None. Write $~Name~$ in your message where each card value belongs.	Create a target profile with a content filter once per message format.
Message formats	Any text format: JSON, XML, form data, plain text, or a value inside one parameter.	JSON, XML, form data or URL query string. The body format is detected from the `Content-Type` header.
Values in JSON and XML	Inserted exactly as stored. PCI Booking does not add quotes or escape characters.	Inserted as valid JSON or XML values, escaped where needed.
Changing the value	No. You choose from fixed formats, for example $~ExpirationMM~$ or $~ExpirationYY~$ .	Yes. Date formats, card type mapping, substrings.
Client certificates (mutual TLS)	Not available.	Available.
Custom encryption or signing of the message	Not available.	Available.
Tokenizing card data in the response	Not available.	Available.
Best for	Quick integrations, prototypes, simple messages you control.	Production integrations, strict schemas, third parties that need certificates or card data in a specific format.

If you send profileName, PCI Booking uses the profile and ignores any placeholders in the message.

Using placeholders

Place $~Name~$ placeholders in the message where each card value belongs and do not send profileName. See Token Replacement Placeholders for the full list, how to use them in JSON, XML and form data, and a worked GraphQL example.

Using a target profile

Create a target profile with a Retrieve Cards Content Filter that describes where each card field goes. See Content Filters.
Send your message with every card field the profile targets present, with an empty or dummy value, and pass the profile name in profileName. PCI Booking fills existing fields; it does not add missing ones. If the profile cannot find the card fields in your message, the request fails with Replacement of content failed.

PCI Booking chooses how to read your message from its Content-Type. If that does not match, it tries the first media type in your Accept header:

Content-Type	Handled as
Contains `json` (for example `application/json`)	JSON. Supports nested objects and arrays.
Contains `xml` (for example `text/xml`, `application/soap+xml`)	XML. Supports SOAP envelopes and namespaces.
`application/x-www-form-urlencoded`	Form data: key-value pairs, or XML or JSON inside a form field, depending on the profile type.

If neither header matches, PCI Booking returns an error (Content type is not supported) and does not relay the request.

If the profile has no Retrieve Cards Content Filter, PCI Booking relays the message without inserting any card data and does not return an error. Make sure the profile you name has this filter.

Bi-Directional: Tokenization on the Way Back

When you use a target profile, the same proxy call can also tokenize card data in the destination’s response. If your profile is configured for it, PCI Booking extracts card data from the response, tokenizes it, and returns tokens to you instead of raw card numbers. See Tokenization on Response for details on setting up profiles for this. When tokenization on response is active, the response includes:

Header	Description
`X-PciBooking-cardUri`	Token URI(s) for cards extracted from the response. Multiple tokens are semicolon-separated.
`X-PciBooking-Tokenization-Errors`	Error details if tokenization failed for any card.
`X-PciBooking-Tokenization-Warnings`	Warnings from the tokenization process.

Timeouts

The complete round trip, from your request reaching PCI Booking until the third party’s response is returned to you, must finish within 29 seconds. Requests that take longer fail.
The timeout parameter sets how long PCI Booking waits for the third party. Its default is 60 seconds, so in practice the 29-second limit applies unless you set a lower value.
If your third party regularly needs more than 29 seconds to respond, contact support@pcibooking.net. We can provide an alternative setup for these cases.

IP Whitelisting

If the third party only accepts traffic from known IP addresses, ask it to whitelist PCI Booking’s outbound IP addresses. Relayed requests from sandbox and live accounts come from the same addresses.

Security

Relay restrictions. Your account can be configured with an endpoint whitelist. Requests to destinations not on the list are rejected. Contact support or use the Admin portal to manage your allowed endpoints.
Client certificates. Target profiles can include client certificates for mutual TLS authentication with the destination.

Next Steps

Token Replacement Placeholders

The full placeholder list and how to use it in JSON, XML and form data.

Target Profiles

Configure where card data goes, once per message format.

Token Replacement in Response

The reverse direction: third parties send requests to your API through PCI Booking.