Token Replacement Placeholders

Placeholders are the quickest way to use Token Replacement in Request. You build the message exactly as the third party expects it, and wherever a card value belongs you write a placeholder. PCI Booking replaces each placeholder with the card data from the token before it forwards the message. Not sure whether placeholders or a target profile suit your integration better? See Choosing a Replacement Mode.

How Placeholders Work

Write each placeholder as $~Name~$ , for example $~Number~$ . Names are not case-sensitive.
Do not send profileName. If you do, PCI Booking uses the profile and ignores the placeholders.
PCI Booking finds placeholders by searching the text of the message. The message does not need to be valid JSON or XML, and placeholders can sit at any depth in a nested structure.
Each value is inserted exactly as it is stored. PCI Booking does not add quotes, remove characters or escape anything.
If the token has no value for a field, for example no 3D Secure data, the placeholder is replaced with an empty string.

Available Placeholders

Placeholder	Replaced with	Example
$~Number~$	Card number (PAN)	`4580458045804580`
$~CardType~$	Card brand, one of our card types	`Visa`
$~ExpirationMM~$	Expiration month, two digits	`07`
$~ExpirationM~$	Expiration month, no leading zero	`7`
$~ExpirationYYYY~$	Expiration year, four digits	`2029`
$~ExpirationYY~$	Expiration year, two digits	`29`
$~CVV~$	Security code, subject to the token’s CVV retention policy	`321`
$~OwnerName~$	Name on card	`MR J DOE`
$~OwnerID~$	Cardholder ID	`9987665432`
$~IssueNumber~$	Card issue number	`1`
$~ThreeDS_AuthenticationValue~$	3D Secure authentication value (CAVV/AAV)	`AAACBDgxAnlENWNRSTECEwAAAAA=`
$~ThreeDS_Eci~$	3D Secure Electronic Commerce Indicator	`05`
$~ThreeDS_XID~$	3D Secure XID, as stored with the token	`cnFwcXVLRjlKZ2pPeGpySzJieGQ=`
$~ThreeDS_ACS~$	3D Secure v2 ACS transaction ID	`82d84974-31c8-4666-a434-73bde0c6efbb`
$~ThreeDS_Universal_TransactionId~$	3D Secure universal transaction ID
$~ThreeDS_Version~$	3D Secure protocol version	`2.2.0`
$~ThreeDS_MerchantName~$	Merchant name used in the 3D Secure authentication	`The Best Hotel`
$~ThreeDS_SLI~$	3D Secure Security Level Indicator
$~ThreeDS_EWallet~$	3D Secure eWallet indicator

The 3D Secure placeholders are filled only when 3D Secure data is stored for the token. See 3DS Auth Management.

Where Placeholders Can Go

In the body. This is the usual case. The body can be in any text format: JSON, XML, SOAP, form data or plain text. A Content-Type header is required. Inside one parameter. Some third parties expect the card data inside a single parameter, for example an XML document posted in a form field. Pass that parameter’s name in contentParam. PCI Booking first looks for the parameter in the query string of targetUri, then in the form body, and replaces placeholders only inside that parameter’s value.

Placeholders in JSON

Because values are inserted as they are, you decide in your message whether each value is a JSON string or a JSON number:

For a string, put the placeholder inside quotes: "number": "$~Number~$".
For a number, leave the placeholder without quotes and use a format without a leading zero: "expiryMonth": $~ExpirationM~$ and "expiryYear": $~ExpirationYYYY~$.
Do not use $~ExpirationMM~$ without quotes. A value such as 07 is not a valid JSON number.

PCI Booking does not escape inserted values. If the name on the card contains a double quote (") or a backslash (\), the resulting JSON is invalid and the third party rejects it. If your cards can contain these characters, use a target profile, which inserts correctly escaped values.

The same applies to XML: a name that contains & or < produces invalid XML unless you use a target profile.

Example: a GraphQL API

GraphQL APIs take a JSON body with a query and a variables object. Put the placeholders inside variables. Headers the third party needs, such as its own Authorization and a User-Agent, are sent as normal and forwarded unchanged.

curl -X POST "https://service.pcibooking.net/api/payments/paycard/relay?accessToken=your-access-token&cardToken=https%3A%2F%2Fservice.pcibooking.net%2Fapi%2Fpayments%2Fpaycard%2F555fd7b49f134b42a5dbe4d576b2e527&targetUri=https%3A%2F%2Fapi.example-crs.com%2Fgraphql" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your-crs-token" \
  -H "User-Agent: MyBookingEngine/1.0" \
  -d '{
    "query": "mutation AddGuarantee($reservationId: ID!, $card: CardInput!) { addGuarantee(reservationId: $reservationId, card: $card) { status } }",
    "variables": {
      "reservationId": "RES-10293",
      "card": {
        "number": "$~Number~$",
        "holderName": "$~OwnerName~$",
        "expiryMonth": $~ExpirationM~$,
        "expiryYear": $~ExpirationYYYY~$,
        "cvv": "$~CVV~$"
      }
    }
  }'

The third party receives the same request with the card values in variables.card, sent to https://api.example-crs.com/graphql with the same headers. The Authorization header here is the third party’s own. You authenticate to PCI Booking with the accessToken query parameter.

Token Replacement in Request: how the relay works and what it changes in your request.
Token Replacement API reference: all parameters and errors.
Target Profiles: the alternative to placeholders.

Start Here

Getting Started

Concepts

Guides

Capture Cards

Payments Library

Manage Tokens

Use Tokens

Account Configuration

Additional Functions

Reference

Support

Token Replacement Placeholders

How Placeholders Work

Available Placeholders

Where Placeholders Can Go

Placeholders in JSON

Example: a GraphQL API

​How Placeholders Work

​Available Placeholders

​Where Placeholders Can Go

​Placeholders in JSON

​Example: a GraphQL API

​Related

How Placeholders Work

Available Placeholders

Where Placeholders Can Go

Placeholders in JSON

Example: a GraphQL API

Related