This implementation for tokenization has been deprecated and replaced by the Global Token Vault tokenization solution. This information is here for vendors that have already integrated with our legacy tokenization solution. This approach should not be utilized for any new integrations. See the Understanding Card Tokens section for details on the Global Token Vault solution.
Current card association regulations specify that a merchant must encrypt all stored payment card numbers. Furthermore, these regulations do not allow the storing of card track information or card security codes (CSCs). Using Shift4’ tokenization eliminates the need for both encryption key management and encryption algorithm maintenance in your interface. Tokenization is not encryption, but works together with our True P2PE® solution to relieve the merchant and the interface from the burden of storing, processing, and transmitting sensitive cardholder data (CHD), greatly reducing the scope of PCI DSS assessments and nearly eliminating the risk of a data breach.
A card token is a unique, 16-character value created by Shift4's Gateway to reference CHD. In and of itself, a card token has no meaning and no decipherable relationship to CHD. A card token is the last four digits of a payment card number followed by a random 12-character alphanumeric code.
Whenever the payment card number is used in a request, a card token will be returned in the corresponding response in the card.token.value field. Your interface should be designed to store this card token for future use. The latest card token received should be used in any subsequent request that references the same card data.
Sending both the payment card number and a card token in a request will result in an error.
Short-term data, including the full track data, CSC and PIN, or P2PE PIN block, is stored with the card token until it is consumed – either when a transaction is processed or if it expires (whichever comes first). The length of time during which short-term data is held is configurable to 24, 48, 72, or a maximum duration of 96 hours for pre-authorization to remain PCI compliant.
A card token will remain valid for 3 days, 7 days, 14 days, 1 month, 3 months, 6 months, 9 months, 12 months, 18 months, 24 months, or until the card’s expiration date. If a payment card expires prior to the card token’s expiration date, then the card token will expire regardless of the expiration date configured in Lighthouse Transaction Manager.
Tip: If you want to determine if a card token’s expiration date exceeds the card’s expiration date before storing a card token, you can support use of the RETURNEXPDATE API Option.
Short-term data storage and the expiration of card tokens are configured within the merchant’s Lighthouse Transaction Manager account’s Token Store Settings. More information about TokenStore® is in the Utilizing TokenStore section of this document.
By default, each merchant account has a TokenStore, a secure repository for all of their tokens in Shift4’ PCI-compliant data centers. Shift4’ TokenStore allows merchants to process refunds, card-on-file payments, incremental authorizations, and more without relying on actual CHD.
Many enterprise and multi-location merchants want to share tokens across different revenue centers and properties. Shift4 offers two ways to do this: TokenShare® and Global TokenStore. There are a few main differences between how TokenShare and Global TokenStore work:
- TokenShare allows merchants to share tokens among accounts. Merchants can use the tokens stored in their own account as well as the tokens stored in other merchants’ accounts when permission has been granted to do so.
- A Global TokenStore is an account that acts as a centralized repository for multiple merchants’ tokens. Its sole purpose is to act as a shared TokenStore for permitted merchant accounts.
Whether you choose to support TokenShare, Global TokenStore, or both depends on your interface requirements and the merchant’s preference. Examples of how your interface can support them are explained in detail below.
To support TokenShare, your interface must store the (correlated) Shift4 serial number of the merchant account where a given token was created. When a merchant needs to use a token that resides in another merchant’s TokenStore, your application will send the token and populate the serial number of the account where the token is located in the card.token.serialNumber field in a request. This will enable Shift4's Gateway to locate that token for use.
An example of this process is given below.
The example provided below is a simplified scenario intended to help illustrate the TokenShare process. Please note that other implementations may work differently depending on the transaction(s) being performed and the merchant’s account setup. Also, card tokens are made up of 16 alphanumeric characters, but letters are used in this example to represent the tokens. The serial numbers used are also simplified for the purpose of this example only.
- Stores 1 and 2 each have tokens in their respective TokenStore accounts in Shift4’ data centers.
- A customer comes into Store 1 (serial 123) and uses a credit card ending with 1119 to purchase a pair of shoes. When the transaction is approved, Token C is generated by Shift4's Gateway and stored in Store 1’s TokenStore.
- The customer later returns the pair of shoes at Store 2 (serial 124). Store 2 doesn’t have Token C in their TokenStore; therefore, the interface must provide Token C and specify “123” in the
card.token.serialNumberfield in the return request. This allows Shift4's Gateway to locate Token C in Store 1’s TokenStore to process the return. - When Store 2 completes the refund transaction, Token Z is created by Shift4's Gateway and added to Store 2’s TokenStore.
If a merchant is processing a transaction with a payment card or using a token from their TokenStore, the transaction will be processed as usual and no serial number needs to be referenced.
To support Global TokenStore, your interface will need to keep track of the Global TokenStore’s serial number for use in certain requests. When a merchant needs to use a token that resides in the Global TokenStore, your interface will send the token and populate the Global TokenStore’s serial number in the card.token.serialNumber field in a request. This will cause Shift4's Gateway to locate the token in the Global TokenStore account for that merchant’s use.
An example of this process is given below.
The example provided below is a simplified scenario intended to help illustrate the Global TokenStore process. Please note that other implementations may work differently depending on the transaction(s) being performed and the merchant’s account setup.
Also, card tokens are made up of 16 alphanumeric characters, but letters are used in this example to represent the tokens. The serial numbers used are also simplified for the purpose of this example only
- Store 1 (serial 123) and Store 2 (serial 124) each have tokens in their respective TokenStore accounts in Shift4’ data centers. The Global TokenStore holds tokens that Store 1 and Store 2 have deposited into it.
- A customer comes into Store 1 (serial 123) and uses a credit card ending with 1119 to purchase a pair of shoes. When the transaction is approved, Token C is generated by Shift4's Gateway and stored in Store 1’s TokenStore.
- To make this card available for use by other parts of the business, the interface must deposit Token C, which is stored in Store 1’s TokenStore, into the Global TokenStore account. This is accomplished by sending a TokenStore Duplicate request along with serial ‘123’ in the
card.token.serialNumberfield (as that is the current location of the token) using the Access Token for the Global TokenStore account (as that is the account where Token C will be deposited). This causes Shift4's Gateway to create a new token, Token G, in the Global TokenStore. - The customer later returns the pair of shoes at Store 2 (serial 124). Store 2 doesn’t have the correct token to process the refund because it is not stored in their TokenStore. Therefore, the interface must provide Token G and specify “789” in the
card.token.serialNumberfield in the return request. This allows Shift4's Gateway to locate Token G in the Global TokenStore to process the return. - When Store 2 completes the refund transaction, Token Z is created by Shift4's Gateway and added to Store 2’s TokenStore.
If a merchant is processing a transaction with a payment card or using a token from their TokenStore, the transaction will be processed as usual and no serial number needs to be referenced.
Shift4 has two functions associated with the TokenStore: TokenStore Add and TokenStore Duplicate.
TokenStore Add is used to add CHD to a local or Global TokenStore and receive a card token. Common uses of TokenStore Add are card-on-file processing or collecting CHD when an order or reservation is placed but not billed right away. TokenStore Add is sent when a purchase is not immediately processed and CHD needs to be tokenized for later use. When using TokenStore Add, short-term data will not be consumed during the tokenization process; instead, the short-term data will remain with the card token for the amount of time configured by the merchant in their Token Store Settings in Lighthouse Transaction Manager.
TokenStore Duplicate](/apis/payments-platform-rest/openapi/tokens/tokensduplicate) is used to generate a new card token using an existing card token. When the TokenStore Duplicate request is sent, a new card token will be returned to be used in place of the original token. The TokenStore Duplicate request will store short-term data if sent by the interface until it is used or for the period configured in the merchant’s Lighthouse Transaction Manager account. When a merchant has a card token that is going to expire and wants to replace it, TokenStore Duplicate can also be used to generate a new card token. The TokenStore Duplicate request can also be used to deposit a card token into a Global TokenStore.
- The interface sends the TokenStore Add request using the merchant’s Access Token to store CHD locally.
- Shift4 returns a response with a card token in the
card.token.valuefield. - The interface vendor stores the card token instead of CHD in its database for use in subsequent transactions.
A Verify Card request is sent using the resultant card token.
A response with no errors is received.
The interface interrogates the
transaction.responseCode,transaction.avs.valid, andcard.securityCode.validfields (where applicable), and stores the card token if valid.
- The interface sends the TokenStore Duplicate](/apis/payments-platform-rest/openapi/tokens/tokensduplicate) request using the Global TokenStore’s Access Token.
- Shift4 returns a response with a new card token in the
card.token.valuefield. - The interface vendor stores the new card token in its database (instead of the old card token) for use in subsequent transactions.