Network Tokenization

A network token (also known as card scheme token) is a token generated by 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 (on your behalf) can request existing account PANs on file to be tokenized and each PAN to be replaced with a unique network token. Note that this is subject to issuer participation in the network tokenization service and the enabled card account ranges. These tokens can then be used for e-commerce and in-app transactions similar to account PANs.

The Mastercard Payment Gateway currently supports processing network tokens obtained from the following network tokenization service providers:

  • Mastercard Digital Enablement Service (MDES)
  • Visa Token Service (VTS): Note that 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 currently limited to Network Token Payments only.

Key Benefits

  • Provides better security for payment information using dynamic cryptograms
  • Allows you to keep card information up to date
  • Can potentially deliver higher approval rates
  • Provides enhanced user experience

Adding Network Tokenization to your Integration

You can use network tokens via the Mastercard Payment Gateway in two ways:

  • Network Token Payments: You integrate directly with the network tokenization service 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, and uses the network token (where available) to process the transaction.

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 on a Authorization/Pay request to process payments.

Transaction Request

In addition to the standard fields, provide the following fields in an Authorization/Pay request to process payments using network tokens issued by the network tokenization service providers.

  • sourceOfFunds.type=SCHEME_TOKEN: Enables the gateway to identify the source of fund provided in the request as a network token. MDES, VTS, and AETS are supported from API v51, v53, v57 respectively.
  • sourceOfFunds.provided.card.number: The network token. Supply the value for the MDES "Token PAN" or the VTS "Token" or the AETS "Token".
    If you are storing the network token on file before providing it in the Authorization/Pay request, set sourceOfFunds.provided.card.storedOnFile=STORED in the request. For more information, see cardholder and merchant-initiated transactions.
  • sourceOfFunds.provided.card.expiry: The network token expiry.
  • sourceOfFunds.provided.card.devicePayment.onlinePaymentCryptogram: Use the value directly from the decrypted transaction credentials. Supply the MDES UCAF cryptogram (de48se43Data) or the VTS TAVV cryptogram.
  • The Electronic Commerce Indicator as issued by the tokenization service. This field is mandatory for network tokens obtained from VTS.
  • sourceOfFunds.provided.card.securityCode: The token verification code if issued by the tokenization service. Supply the MDES Dynamic Token Verification Code (DTVC) or the VTS Dynamic Token Verification Value (DTVV) or the AETS Dynamic Payment Credential (DCSC).
  • transaction.source: For cardholder-initiated transaction , set this field to MOTO, CALL_CENTRE, MAIL_ORDER, TELEPHONE_ORDER, and VOICE_RESPONSE. For merchant-initiated transaction, set this field to "INTERNET" or "MERCHANT".

Transaction Response

When a network token is provided in the Authorization/Pay request, the Retrieve Transaction response will return the following:

  • sourceOfFunds.type=SCHEME_TOKEN if a network token was used in the Authorization/Pay transaction.

If the acquirer returns an FPAN:

  • sourceOfFunds.provided.card.number: The masked FPAN (Funding PAN).
  • sourceOfFunds.provided.card.expiry fields: The FPAN expiry.
  • sourceOfFunds.provided.card.deviceSpecificNumber: The network token from MDES ("Token PAN") or VTS ("Token") or AETS ("Token").
  • sourceOfFunds.provided.card.deviceSpecificExpiry: The network token expiry.

If the acquirer does not return an FPAN:

  • sourceOfFunds.provided.card.number: The fully masked value.
  • sourceOfFunds.provided.card.deviceSpecificNumber: The network token from MDES ("Token PAN") or VTS ("Token") or AETS ("Token").
  • sourceOfFunds.provided.card.deviceSpecificExpiry: The network token expiry.

Network Tokenization for Gateway Tokens

The gateway provides support to act as a token requestor on your behalf. If you are enabled for gateway tokenization, then 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 will also attempt to generate a corresponding network token for enabled schemes, where supported by the card issuer. The Authorization/Pay request will use the network token if available else the Funding PAN (FPAN) stored against the gateway token will be used.

Network tokenization will also be attempted for any applicable cards already stored in the gateway token repository.

MDES and VTS tokens are currently supported using the network tokenization for gateway tokens model.

When you delete a gateway token, the corresponding network token is automatically deleted on the tokenization service.

It's important to note that if the card is updated by the issuer, for example, expired, lost or stolen cards, the existing FPAN details stored against the gateway token are flagged as invalid. In the event where an FPAN needs to be used in the payment request because the network token is unavailable, the gateway rejects the request. You receive an error "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 the transaction response where the network token was used in the payment. 

Transaction Response

When a network token is used in the Authorization/Pay request, the Retrieve Transaction response will return the following:

  • sourceOfFunds.provided.card.number: The masked FPAN (Funding PAN), where returned by the acquirer.
  • sourceOfFunds.provided.card.expiry fields: The FPAN expiry
  • sourceOfFunds.provided.card.deviceSpecificNumber: The network token from MDES or VTS. MDES and VTS call it "Token PAN" and "Token" respectively.
  • sourceOfFunds.provided.card.deviceSpecificExpiry: The network token expiry.
  • sourceOfFunds.type=SCHEME_TOKEN if a network token was used in the Authorization/Pay transaction.
  • sourceOfFunds.provided.card.paymentAccountReference : The unique identifier that links an FPAN for a card with all network tokens issued for the card.
Network tokenization for gateway tokens is supported in all API versions.
  • Support for 3DS is available in the transaction response from API v54.
  • Complete token specific information, i.e., token PAN (sourceOfFunds.provided.card.deviceSpecificNumber), token expiry (sourceOfFunds.provided.card.deviceSpecificExpiry), and sourceOfFunds.type is available in the transaction response from API v54
  • Partial token specific information in the transaction response is available in earlier versions
    • Token PAN from API v39 and token expiry from API v43
    • API v38 and earlier versions will not return any token specific information.

The Network Tokenization is not applicable for the device payments using DPAN or FPAN.


Are network tokens supported in 3-D Secure Authentication requests?

The gateway can process network tokens in the Initiate Authenticate 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 parameter group of the Pay or Authorize operation. For more information, see Submit a Pre-Authenticated Payment Operation.

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 tokens details for a transaction in Merchant Administration?

For an order or transaction where a network token was used, the field 'External Token Provider' is displayed in the Order and Transaction details page in Merchant Administration. This field may show either Mastercard (MDES) or Visa (VTS).

Testing Network Token Integration

You can test your integration with the gateway in production using your test merchant profile and a supported network token (see table below).

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> -

If the transactions are either APPROVED or DECLINED then the gateway was able to process your test transactions successfully.

Copyright © 2023 Mastercard