Configuring Gateway Tokenization
Gateway Tokenization allows merchants to securely store the payer's payment details into a gateway token within the gateway's secured environment. The merchant can store credit/debit card, gift card, or ACH details in a gateway token, which in turn is stored in a token repository.
A token repository is a collection of gateway tokens and the corresponding network tokens (where Network Tokenization is enabled). Each token repository on the gateway is identified using a unique Token Repository ID. A token repository that you create will have a corresponding test Token Repository, which only merchants with the corresponding test profiles can access. For example, if the repository ID is ABC, the test repository ID will be TestABC. Hence, the system displays an error if you specify a repository ID that starts with Test.
Token repositories can be shared across merchants within an MSO and across MSOs within a site. If you as an MSO know the ID of a token repository created by a different MSO, you can assign it to your merchants. Merchants can share gateway tokens with other merchants across token repositories. However, a merchant can be associated with only one Token Repository at a given time.
To enable Gateway Tokenization, provide the following fields in the Update Merchant Payment Details or Create or Update request.
This page describes a few scenarios on how the Update Merchant Payment Details or Create or Update request creates and assigns token repositories.
merchant.tokenization.tokenRepositoryId: A unique identifier of the token repository. If a token repository with this ID does not exist on the gateway, the Merchant Boarding API attempts to create a new token repository with this ID. If you have provided all the mandatory fields as listed below, the API successfully creates the token repository and assigns it to the merchant. If not, the request fails and the merchant configuration is not updated. This also applies to a merchant who currently has a token repository assigned.merchant.tokenization.tokenRepository.schemeTokenization.mdes.merchantTradingName: The trading name of the merchant. If you provide this field and the repository is not yet enabled for the scheme tokenization, that is, the merchant.tokenization.tokenRepository.schemeTokenization.mdes.tokenRequestorId field is not present, then the gateway attempts to enable the scheme tokenization with MDES by registering the merchant with MDES and retrieving a token requestor ID (TRID). If the registration was successful, the Retrieve Merchant response contains the TRID in the field merchant.tokenization.tokenRepository.schemeTokenization.mdes.tokenRequestorId and the repository is enabled for the scheme tokenization for the Mastercard cards.merchant.tokenization.tokenRepository.tokenGeneration: See Token Generation Strategy.merchant.tokenization.tokenRepository.tokenManagementStrategy: See Token Management Strategy.merchant.tokenization.verificationStrategy: This field is optional. See Token Verification Strategy.
merchant.tokenization.tokenRepositoryId field already exists on the gateway, then this token repository is assigned to the merchant. Any configuration details that you provide on the request will be ignored. The table below summarizes the various scenarios on how the Update Merchant Payment Details or Create or Update request creates and assigns token repositories.
| merchant.tokenization.tokenRepositoryId | merchant.tokenization.tokenRepository.tokenGeneration merchant.tokenization.tokenRepository.tokenManagementStrategy | Token Repository exists? | Result | Result Description |
|---|---|---|---|---|
| not provided | N/A | N/A | result=SUCCESS | Gateway Tokenization is not enabled for the merchant. |
| provided | not provided or value for only one field provided | Yes | result=SUCCESS |
|
| provided | not provided or value for only one field provided | No | result=ERROR |
|
| provided | both provided | No | result=SUCCESS |
|
| provided | both provided | Yes | result=SUCCESS |
|
Token Generation Strategy
Defines the strategy used to generate a token within this repository. Values can be:
| merchant.tokenization.tokenRepository.tokenGeneration | Description | ||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| RANDOM_WITH_LUHN | The generated token id is a random number. It begins with a '9', passes a Luhn (Mod-10) check, and excludes known card numbers. | ||||||||||||||||||||
| PRESERVE_6_4 | Attempts to preserve the first 6 and last 4 digits, and is not a valid card number. You cannot update the card number for a preserve 6.4 token; however, you may update the expiry date. Token properties are shown in the tables below:
|
||||||||||||||||||||
| MERCHANT_SUPPLIED | The token is supplied by the merchant. Any merchant-supplied token is validated to not be a valid card number. | ||||||||||||||||||||
| Acquirer Tokenization | Currently not supported via the Merchant Boarding API. |
Token Verification Strategy
Defines how the payment details are verified prior to being stored. Values can be:
| merchant.tokenization.verificationStrategy | Description |
|---|---|
| BASIC | This is the default value if you do not provide the field. Validates that the payment details provided conform to the gateway rules for processing a payment with these payment details. |
| ACQUIRER | Verifies the payment details by performing a Verify request, to verify the provided payment details with the acquirer. When you store a token, you must provide a currency. The transaction source will default to the value configured for the merchant-acquirer link. The
Enforce CSC setting for this transaction source will be ignored. |
| NONE | No verification is performed. |
Token Management Strategy
Defines how tokens within the repository are managed. Values can be:
| merchant.tokenization.tokenRepository.tokenManagementStrategy | Description |
|---|---|
| UNIQUE_TOKEN | Assigns a unique token every time you save an account identifier. This can be defined as a one-to-many relationship between an account identifier and tokens. |
| UNIQUE_ACCOUNT_IDENTIFIER | An account identifier can only be stored against a single token. If an attempt is made to store it against another token, it will result in an error. This can be defined as a one-to-one relationship between the account identifier and the token. |