Enabling Network Tokenization
This page describes how to use the CreateOrUpdate Merchant request to enable or disable, and configure network tokenization.
The
CreateOrUpdate Merchant operation is available from API version 63 onwards.The gateway currently supports the following network tokenization providers:
- Mastercard Digital Enablement Service (MDES)
- Visa Token Service (VTS)
- American Express Token Service (AETS)
To enable and configure network tokenization for a scheme, you must have MDES, VTS, or AETS tokenization privilege. Provide the following fields specific to the network tokenization provider.
Network tokenization for Visa card scheme
merchant.tokenization.vtsSchemeTokenUsage: Provide this field to enable the use of VTS network tokens in transaction requests, for example, Authorize or Pay, from the selected token repository for this merchant. You can choose to enable them for Production and Test merchant profiles, or only Test.- ENABLE_FOR_PRODUCTION_AND_TEST_MERCHANT_PROFILE
- ENABLE_FOR_TEST_MERCHANT_PROFILE_ONLY
merchant.tokenization.tokenRepository.SchemeTokenization.vts.tokenRequesterId: Specifies the unique identifier assigned to the merchant by VTS. This identifier is used for all the merchants using a particular token repository. Once configured, you cannot update this value. If you want to use a new identifier, a new token repository must be assigned to the merchant.merchant.tokenization.tokenRepository.SchemeTokenization.vts.relationshipId: Specifies the unique identifier assigned to the merchant by VTS. This identifies the merchant in the request that the gateway submits to VTS. The same identifier is used for all the merchants using this token repository. Once configured, this value cannot be updated.merchant.tokenization.tokenRepository.schemeTokenization.vts.merchant: Specifies the details about the merchant that the gateway uses to register the merchant with VTS and enable the token repository for the Visa card tokenization scheme. Provide these details if you want to enable the scheme tokenization for Visa cards for the repository and the merchant has not yet received a TRID from VTS.merchant.tokenization.tokenRepository.schemeTokenization.vts.merchant.legalName: Specifies the registered or legal name of the merchant. Note that this may differ from the trading name that payers of the merchant are familiar with.merchant.tokenization.tokenRepository.schemeTokenization.vts.merchant.countryCode: Specifies the country of the merchant's primary address. Provide the ISO 3166-1 three-letter country code.merchant.tokenization.tokenRepository.schemeTokenization.vts.merchant.city: Specifies the city of the merchant's primary address.merchant.tokenization.tokenRepository.schemeTokenization.vts.merchant.businessIdentificationType: Specifies the type of the business identifier that you have provided in the fieldmerchant.tokenization.tokenRepository.schemeTokenization.vts.merchant.businessIdentifier. The business identifier type must be valid in the country that you provide in the fieldmerchant.tokenization.tokenRepository.schemeTokenization.vts.countryCode. For example, if the merchant is located in Canada, you can provide either the merchant's Business Identification Number(BID) or Business Number(BN).merchant.tokenization.tokenRepository.schemeTokenization.vts.merchant.businessIdentifier: Specifies the business identifier of the merchant, for example, their tax registration identifier. Provide the value of the identifier that you have provided in the fieldmerchant.tokenization.tokenRepository.schemeTokenization.vts.merchant.businessIdentificationType.merchant.tokenization.tokenRepository.schemeTokenization.vts.merchant.email: Specifies the email address that can be used to contact the merchant.merchant.tokenization.tokenRepository.schemeTokenization.vts.merchant.website: Specifies the URL of the merchant's website.
If you provide these fields and the repository is not yet enabled for the scheme tokenization, that is, the
merchant.tokenization.tokenRepository.schemeTokenization.mdes.tokenRequestorId and RelationshipID fields are not present, then the gateway attempts to enable the scheme tokenization with VTS by registering the merchant with MDES and retrieving a Token Requestor ID (TRID) and RelationshipID.If you do not provide the usage field, its value is set to the default 'ENABLE_FOR_TEST_MERCHANT_PROFILE_ONLY' value.
Once approved, the usage fields are displayed on the Tokenization Configuration page within the Manage Merchants section, in the Merchant Manager. The configuration fields, that is, tokenRequestorId and relationshipId are displayed on the Token Repository page in the Merchant Manager.
It is recommended that you set
merchant.tokenization.tokenRepository.tokenManagementStrategy to "UNIQUE_TOKEN" when enabled for network tokens. When merchant.tokenization.tokenRepository.tokenGeneration is set to PRESERVE_6_4, note that the gateway token may not represent the actual FPAN if the issuer updates the card, for example, expired card, lost or stolen card. Network tokenization for Mastercard card scheme
merchant.tokenization.scofSchemeTokenUsage: Provide this field to enable the use of Mastercard network tokens in transaction requests, for example, Authorize or Pay, from the selected token repository for this merchant. You can choose to enable them for Production and Test merchant profiles, or only Test.- ENABLE_FOR_PRODUCTION_AND_TEST_MERCHANT_PROFILE
- ENABLE_FOR_TEST_MERCHANT_PROFILE_ONLY
merchant.tokenization.tokenRepository.schemeTokenization.scof.merchantTradingName: Specifies the trading name of the merchant. If provided and the repository is not yet onboarded to SCOF for Mastercard scheme tokenization, that is,merchant.tokenization.tokenRepository.schemeTokenization.scof.statusis not ENABLED or REQUESTED, the gateway attempts to enable scheme tokenization with SCOF by registering the merchant with SCOF and retrieving the status of the registration.
If the registration was successful, the Retrieve Merchant response contains themerchant.tokenization.tokenRepository.schemeTokenization.scof.statusas ENABLED and the repository is enabled for Mastercard scheme tokenization.merchant.tokenization.tokenRepository.schemeTokenization.scof.status: Indicates whether Mastercard Secure Card on File (SCOF) tokenization functionality is enabled for the token repository assigned to the merchant as identified inmerchant.tokenization.tokenRepositoryId.
Do not provide this field in the request. If provided in the request, it will be ignored.
Once approved, the usage fields are displayed on the Tokenization Configuration page within the Manage Merchants section in the Merchant Manager. The configuration field, that is, merchantTradingName and status, are displayed on the Token Repository page in the Merchant Manager.
Network tokenization for American Express card scheme
merchant.tokenization.amexSchemeTokenUsage: Provide this field to enable the use of American Express network tokens in transaction requests, for example, Authorize or Pay, from the selected token repository for this merchant. You can choose to enable them for Production and Test merchant profiles, or only Test.- ENABLE_FOR_PRODUCTION_AND_TEST_MERCHANT_PROFILE
- ENABLE_FOR_TEST_MERCHANT_PROFILE_ONLY
-
merchant.tokenization.tokenRepository.SchemeTokenization.amex: Specifies the details about the merchant that the gateway uses to register the merchant with AETS and enable the token repository for the American Express scheme tokenization. Provide these details if you want to enable the scheme tokenization for American Express cards for the repository. -
merchant.tokenization.tokenRepository.SchemeTokenization.amex.businessName: Specifies the business name of the merchant that you are registering with American Express. -
merchant.tokenization.tokenRepository.SchemeTokenization.amex.bankMerchantId: Specifies the bank merchant ID, also known as service establishment identifier or SE ID, is a unique code assigned to the merchant by American Express when the merchant opens an account. If a merchant has multiple SE IDs, use the parent SE ID. You may need to contact the merchant to obtain the SE ID. -
merchant.tokenization.tokenRepository.SchemeTokenization.amex.email: Specifies the email address of the primary contact at the merchant, that can be used to contact the merchant. Ensure that the email address is longer than 3 characters and adheres to the RFC 5322 standard. -
merchant.tokenization.tokenRepository.SchemeTokenization.amex.address.countryCode: Specifies the country of the merchant's primary address. Provide the ISO 3166-1 three-letter country code. -
merchant.tokenization.tokenRepository.SchemeTokenization.amex.website: Specifies the URL of the merchant's website. Ensure that this is a valid URL according to RFC 1738. -
merchant.tokenization.tokenRepository.schemeTokenization.amex.status: Indicates whether American Express scheme tokenization functionality is enabled for the token repository assigned to the merchant. Do not provide this field in the request. If provided in the request, it will be ignored.
Once approved, the usage fields are displayed on the Tokenization Configuration page within the Manage Merchants section, in the Merchant Manager. The configuration fields are displayed on the Token Repository page in the Merchant Manager.