Token Replacement in Request

You should use this feature if you need to send credit card data to third party APIs.

The PCI Shield token replacement service lets e-commerce sites securely send multiple card-containing requests to third-party services using a card token, while the recipient gets the complete card details.


Relaying cards to payment gateways

While you can use the Token Replacement in Request method to relay cards to payment gateways, we strongly recommend that you consider using the Universal Payment Gateway method.
If you require any assistance with the Universal Payment Gateway, please contact our team.

The token replacement method has two modes of operation:

  1. Using target profiles
  2. Using place holders

Replacement using target profile


When should you use this mode?

  1. When sending card data in a XML or JSON - either in the message body or in the message form-data.
  2. When sending card data in the query string parameters of a URL
  3. When credit card data requires manipulation (for example, listing the expiration date in a particular format, mapping the card type from the standard to non-standard)

First, you will need to set up a Target Profile which will provide PCI Booking with instructions where the credit card details should be placed in the message.
Within the profile configuration you will define where the card data will be located .

Then, you will prepare the request to the third party as always with the values for the credit card data blank.
In the request URL to PCI Booking, you will provide the ID of the target profile in the parameter profileName.

Replacement using place holders


When should you use this mode?

  1. When the credit card data is not in XML or JSON format (for example, plain text messages).
  2. When the credit card data is sent in a non-valid XML or JSON format


Do not provide profileName in the request URL

If you provide a profileName in the URL, PCI Booking will ignore the placeholders and will perform token replacement according to the profile mentioned.
If using placeholders, make sure not to include the profileName.

Create the request as always and add specific placeholders in the message which, when passing through PCI Booking's API, will be replaced by PCI Booking with the actual card data.
Each placeholder will represent a different field value from the card details. The table below shows the different optional placeholder values that can be used.

The placeholder name should be listed in the message body is in the format: $~Name~$.

CardTypeOne of our supported card types.AMEX
ExpirationMMExpiration month, in 2-digit format08
ExpirationMExpiration month, in 1 or 2-digit format8
ExpirationYYYYExpiration year, in 4-digit format2018
ExpirationYYExpiration year, in 2-digit format18
IssueNumberIssue number1
NumberCard number4580458045804580
OwnerIDCard holder ID9987665432
OwnerNameName on cardMR J DOE
CVVSecurity code321
ThreeDS_AuthenticationValueThe authentication value (CAVV) that was returned after the owner was authenticated.AAACBDgxAnlENWNRSTECEwAAAAA=
ThreeDS_EciThe Electronic Commerce Indicator (ECI) is a value returned by the authentication process indicating the outcome of authentication .05
ThreeDS_XIDIf 3D Secure version 1 was used, the merchant will have the XID value and if version 2 was used, the merchant will have the 3DS_Trans_ID value. Both the XID and 3DS_trans_ID are stored in PCI Booking interchangeably under the same field.cnFwcXVLRjlKZ2pPeGpySzJieGQ=
ThreeDS_VersionThe version used for the authentication.1.0
ThreeDS_MerchantNameMerchant account used in the 3DS authentication process.The Best Hotel
ThreeDS_ACSUnique transaction identifier assigned by the ACS to identify a single 3D secure transaction.82d84974-31c8-4666-a434-73bde0c6efbb

If the card data should be sent in the form-data of the message, add the contentParam parameter to the request URL. The contentParam value should be the key name (either in query string or form-data) where the card data placeholders are located.

Token Replacement Flow

The request will go through the PCI Booking server and will be relayed to the third party.

  1. Based on your choice of operating mode, you may need to prepare a token replacement target profile.
  2. Authenticate PCI Booking via an "access token" or a "session token". Read more about our authentication methods.
  3. Prepare the request body that should be sent to the third party.
  • If you chose to use replacement by placeholders, make sure to list the placeholders (in the format $~Name~$) in the correct location within the message body.
  1. Follow the Token Replacement method documentation to create the request to the third party to be sent via PCI Booking.
  2. PCI Booking will receive the request and perform the token replacement of all details of the card into the message. The request is then relayed to the target URL provided.
  3. The third party receives the request, processes it and send back the response.
  4. PCI Booking relays the response as is.
  5. Process the response received from PCI Booking.
  6. Optionally, add business logic based on the current status of the CVV retention policy

Flow Charts

Below are two flow charts describing the process of sending credit card details to a third party without using PCI Booking and when using PCI Booking (the flow of using PCI Booking to send card data to a third party does not change based on the operating method you choose).