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:
Replacement using target profile
When should you use this mode?
- When sending card data in a XML or JSON - either in the message body or in the message form-data.
- When sending card data in the query string parameters of a URL
- 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?
- When the credit card data is not in XML or JSON format (for example, plain text messages).
- When the credit card data is sent in a non-valid XML or JSON format
Do not provide
profileNamein the request URLIf you provide a
profileNamein 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 theprofileName.
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~$.
| Name | Description | Examples |
|---|---|---|
| CardType | One of our supported card types. | AMEX |
| ExpirationMM | Expiration month, in 2-digit format | 08 |
| ExpirationM | Expiration month, in 1 or 2-digit format | 8 |
| ExpirationYYYY | Expiration year, in 4-digit format | 2018 |
| ExpirationYY | Expiration year, in 2-digit format | 18 |
| IssueNumber | Issue number | 1 |
| Number | Card number | 4580458045804580 |
| OwnerID | Card holder ID | 9987665432 |
| OwnerName | Name on card | MR J DOE |
| CVV | Security code | 321 |
| ThreeDS_AuthenticationValue | The authentication value (CAVV) that was returned after the owner was authenticated. | AAACBDgxAnlENWNRSTECEwAAAAA= |
| ThreeDS_Eci | The Electronic Commerce Indicator (ECI) is a value returned by the authentication process indicating the outcome of authentication . | 05 |
| ThreeDS_XID | If 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_Version | The version used for the authentication. | 1.0 |
| ThreeDS_MerchantName | Merchant account used in the 3DS authentication process. | The Best Hotel |
| ThreeDS_ACS | Unique 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.
- Based on your choice of operating mode, you may need to prepare a token replacement target profile.
- Authenticate PCI Booking via an "access token" or a "session token". Read more about our authentication methods.
- 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.
- Follow the Token Replacement method documentation to create the request to the third party to be sent via PCI Booking.
- 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.
- The third party receives the request, processes it and send back the response.
- PCI Booking relays the response as is.
- Process the response received from PCI Booking.
- 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).
Updated 8 months ago