Network Tokenization
A network token, also known as a card scheme token, is a token generated by the network tokenization service providers, such as Mastercard Digital Enablement Service (MDES), in exchange for the payer's Primary Account Number (PAN).
You or your payment service provider can request the network tokenization service provider to tokenize the existing account PANs on file and replace each PAN with a unique network token.
This is subject to issuer participation in the network tokenization service and the enabled card account ranges. You can use these tokens for e-commerce and in-app transactions like account PANs.
Supported methods and operations
These tokens are supported for the following purpose.
| Integration Methods | Payment methods | Operations |
|---|---|---|
In the Hosted Checkout, neither the payer nor the merchant can submit a network token directly. However, the merchant can gateway-tokenize a card obtained through the Hosted Checkout, which can lead to a network token being generated by the gateway.
|
|
In network token payments:
|
Benefits of network tokenization
Network tokenization provides the following benefits.
- Provides better security for payment information using dynamic cryptograms.
- Allows you to keep card information up to date.
- Delivers higher approval rates.
- Provides an enhanced user experience.
Supported network tokenization service providers
The Mastercard Gateway currently supports processing network tokens obtained from the following network tokenization service providers:
- Mastercard Digital Enablement Service (MDES)
- Visa Token Service (VTS)
U.S. based merchants cannot process VTS tokens for debit or prepaid cards transactions routed to domestic debit networks.
- American Express Token Service (AETS)
Support is currently limited to network token payments only.
To view examples of the API requests and responses used in network tokenization, download the Postman collection.
Network tokenization integration
You can use network tokens through the Mastercard Gateway in following ways:
- Network token payments: You integrate directly with the network tokenization service provider, request new tokens for your payers from the provider, and submit the token details in a transaction request to the gateway.
- Network tokenization for gateway tokens: The gateway integrates with the network tokenization service provider on your behalf. It automatically requests network tokens to match all the gateway tokens you create and uses the network token where available to process the transaction.
- Network tokenization for Hosted Checkout: Network tokenization represents the creation of tokens by payment network schemes, serving as secure substitutes for sensitive payment information. Hosted Checkout, as part of its robust feature set, extends support for the integration and utilization of thesenetwork tokens, ensuring enhanced security and seamless transaction processes for users and merchants alike.
Network token payments
When you integrate directly with the network token service provider, you must obtain the token details from the provider and provide these details to the gateway in any of the following requests to process payments:
Network token payment transaction request fields
In addition to the standard fields, provide the following fields in the request to process payments using network tokens issued by the network tokenization Service Providers.
| Field name | Valid values | Description |
|---|---|---|
| sourceOfFunds.type | SCHEME_TOKEN
The Scheme Token, such as, MDES, VTS, and AETS are supported from API v51, v53, and v57 onwards. |
Payment method used for this payment. Enables the gateway to identify the source of funds provided in the request as a network token. |
| sourceOfFunds.provided.card.number | Supply any of the following values:
|
Network token
If you are providing a network token where the credentials, that is the network token or the corresponding FPAN, were stored during a previous payment, set the sourceOfFunds.provided.card.storedOnFile = STORED in the request. Otherwise, set the value to TO_BE_STORED. For more information, see Credential on File Transactions.
|
| sourceOfFunds.provided.card.expiry | - | Network token expiry |
| sourceOfFunds.provided.card.devicePayment.onlinePaymentCryptogram | Supply the MDES UCAF cryptogram (de48se43Data) or the VTS TAVV cryptogram. | Cryptogram used to authenticate the transaction. Use the value directly from the decrypted transaction credentials. |
| sourceOfFunds.provided.card.devicePayment.eciIndicator | - | Electronic Commerce Indicator (ECI) as issued by the tokenization service. This field is mandatory for network tokens obtained from VTS. |
| sourceOfFunds.provided.card.securityCode | Provide any one from the following values:
|
Token verification code if issued by the tokenization service. |
| transaction.source | For a cardholder-initiated transaction, set this field to any of the following values:
|
Network token payment transaction response fields
When a network token is provided, for example, the AUTHORIZE/PAY request, the RETRIEVE TRANSACTION response returns the following fields:
| Field Name | Description |
|---|---|
| sourceOfFunds.type = SCHEME_TOKEN | Network token used in the transaction. |
If the acquirer returns an FPAN, the RETRIEVE TRANSACTION response returns the following fields:
| Field Name | Description |
|---|---|
| sourceOfFunds.provided.card.number | Masked FPAN or Funding PAN. |
| sourceOfFunds.provided.card.expiry | FPAN expiry. |
| sourceOfFunds.provided.card.deviceSpecificNumber | Network token from MDES (Token PAN), VTS (Token), or AETS (Token). |
| sourceOfFunds.provided.card.deviceSpecificExpiry | Network token expiry. |
If the acquirer does not return an FPAN, the RETRIEVE TRANSACTION response returns the following fields:
| Field Name | Description |
|---|---|
| sourceOfFunds.provided.card.number | Fully masked value. |
| sourceOfFunds.provided.card.deviceSpecificNumber | Network token from MDES (Token PAN), VTS (Token), or AETS (Token). |
| sourceOfFunds.provided.card.deviceSpecificExpiry | Network token expiry. |
Test network token integration details
For general details on testing your integration, see the testing instructions within each applicable integration method. To test network tokenization specifically, use your test merchant profile and a test network token.
| Token Provider | Token | Token Expiry | Cryptogram | ECI Indicator |
|---|---|---|---|---|
| MDES | 5204 2477 5000 1497 | 11/22 | <any> | - |
| VTS | 4111 1111 1111 1111 | 06/29 | <any> | 05 |
| AETS | 3456 7890 1234 564 | 05/21 | <any> | - |
Network tokenization for gateway tokens
The gateway provides support to act as a token requestor on your behalf. If your merchant profile is enabled for gateway tokenization, your payment service provider can also enable and configure network tokenization on your merchant profile
When enabled, any request to the gateway for a gateway token also attempts to generate a corresponding network token for enabled schemes, if supported by the card issuer.
The token creation request for a gateway token returns a gateway token, and in the background, the token service provider generates a network token, asynchronously, for the FPAN that you submit while creating a gateway token.
The gateway internally stores the FPAN and network token, both of which are associated with the gateway token that the gateway returns to the merchant.
In this model, the merchant always supplies a gateway token, and based on the situation, the gateway either uses the network token, or, if not available, the Funding PAN (FPAN) stored against that gateway token.
The gateway attempts network tokenization for any applicable cards already stored in the gateway token repository. This refers to a situation where,
- Your payment service provider enables Gateway tokens
- Gateway tokens are generated for several payers
- Your payment service provider enables network tokens for you
The gateway then automatically generates network tokens for all your existing gateway tokens.
When you delete a gateway token, the corresponding network token is automatically deleted in the gateway and with the network token service provider.
The token provided in the request is marked as unusable. The card details stored against the token must be updated before they can be used, because the gateway has been informed that the card details are no longer valid.
To keep your records up to date, you can retrieve the masked FPAN details of the updated FPAN from an earlier transaction response where the network token was used in the payment.
Retrieve transaction response fields
When a network token is used in, for example, the AUTHORIZE or PAY request, the RETRIEVE TRANSACTION response returns the following fields:
| Field | Description |
|---|---|
| sourceOfFunds.provided.card.number | Masked FPAN, where returned by the acquirer. |
| sourceOfFunds.provided.card.expiry | FPAN expiry |
| sourceOfFunds.provided.card.deviceSpecificNumber | Network token from MDES (Token PAN) or VTS (Token) |
| sourceOfFunds.provided.card.deviceSpecificExpiry | Network token expiry |
| sourceOfFunds.type = SCHEME_TOKEN | If a network token was used in the transaction. |
| sourceOfFunds.provided.card.paymentAccountReference | Unique identifier that links an FPAN for a card with all network tokens issued for the card. |
- Support for 3D Secure authentication is available from API v54 onwards.
- Complete token-specific information, that is, token PAN sourceOfFunds.provided.card.deviceSpecificNumber, token expiry sourceOfFunds.provided.card.deviceSpecificExpiry, and sourceOfFunds.type are available in the transaction response from API v54 onwards.
- Earlier versions include partial token-specific information in the transaction response:
- Token PAN, that is, the value in the sourceOfFunds.provided.card.deviceSpecificNumber field from API v39 onwards and token expiry from API v43 onwards.
- The API v38 and earlier versions do not return any token-specific information.
Network tokenization is not applicable for device payments using DPAN or FPAN.
Test network tokenization for gateway tokens
You can test your integration to the gateway by using the emulator. To access the emulator, use your test merchant profile with the "TEST" prefix that your payment service provider provides.
Test the functionality
Perform the following steps to test the supported functionality:
- Create a token for a test card by sending a TOKENIZE request and receive a gateway token in response in the
tokenfield. The gateway token is generated dynamically, or you can provide your own token instead if your token repository is configured to support merchant-supplied tokens. - Complete a payment by submitting an AUTHORIZE or PAY request with the
sourceOfFunds.tokenfield populated with the gateway token. Depending on the expiry date used during tokenization, you will receive either an APPROVED or DECLINED response in theresponse.gatewayCodefield. If a network token was used in the transaction, the response will contain thesourceOfFunds.type=SCHEME_TOKENfield. - Submit RETRIEVE TOKEN request with the gateway token to receive token details.
If you tokenize a 3-D Secure enrolled card, you can also test the following authentication scenarios:
- Submit the INITIATE AUTHENTICATION request with the
sourceOfFunds.tokenfield populated with the gateway token.
The response containsresponse.gatewayCode=AUTHENTICATION_IN_PROGRESSandauthentication.version=3DS2, indicating that authentication is available. - Submit an AUTHENTICATE PAYER request with the
sourceOfFunds.tokenfield.
The response containsorder.authenticationStatus=AUTHENTICATION_SUCCESSFULandsourceOfFunds.type=SCHEME_TOKEN, indicating that the authentication is completed using the network token. - Use the transaction ID for this 3DS authentication in the
authentication.transactionIdfield of subsequent AUTHORIZE or PAY transaction request.
Test cards
| Card Number | 3-D Secure Enrolled |
|---|---|
| 5123450000000008 | Y |
| 2223000000000007 | Y |
| 5111111111111118 | N |
| 2223000000000023 | N |
Transaction responses
| Expiry Date | Transaction Response Gateway Code |
|---|---|
| 01/39 | APPROVED |
| 05/39 | DECLINED |
Network tokenization for Hosted Checkout
Prerequisites
- Ensure that your merchant profile is enabled for Hosted Payments. Please ensure both Hosted Checkout and Pay with Token and the relevant tokenization service are enabled. If Hosted Payments and its features are not currently enabled, please reach out to your payment service provider for assistance. To activate Hosted Payments and any associated features for your merchant profile, see the Merchant Manager portal and consult the Merchant Manager User Guide for detailed instructions.
- To use Network Tokenization for Gateway Token, please ensure that they are both enabled.
- Please ensure Secure Remote Commerce (Click to Pay) is not enabled.
- Please ensure that you follow and utilize the Credential on File integration. You can find detailed instructions and guidelines for implementing this integration over here:
- Currently,
interaction.operation=AUTHORIZEis supported for this functionality. Additional support forinteraction.operation=PURCHASEis coming soon. - WS API v74 or later must be used.
- Currently,
Frequently asked questions
Are network tokens supported in 3D Secure authentication requests?
The gateway can process network tokens in the INITIATE AUTHENTICATION request. For more information, see Initiate Authentication.
If you have authenticated the payer externally using a network token, you can pass information about the authentication in the authentication object of, for example, the PAY or AUTHORIZE operation. For more information, see How do I submit a pre-authenticated payment request?
Can I use network tokens in merchant-initiated transactions?
The gateway allows you to use network tokens stored on file to perform cardholder-initiated and merchant-initiated transactions.
Can I view network token details for a transaction in the Merchant Administration?
For an order or transaction where a network token was used, the External Token Provider field is displayed in the Order and Transaction details page in the Merchant Administration portal. This field displays either Mastercard (MDES) or Visa (VTS). The system does not support gateway tokenization of AETS tokens.