Using Mastercard and Visa network tokens

An article about the capability of saving and using customer payment data for payment processing via Gate, with the use of Mastercard and Visa network tokens.

Overview

To improve convenience and security of card payments, global card networks offer network tokenisation solutions. A network token is created for a card of the respective card network and via a specialised service of this card network. Once created and collected, this token can be used in payment processing via any acquirer or provider that supports working with network tokens of the said card network.

The Ecommpay payment platform allows you to process payments with the use of network tokens created by the Mastercard Secure Card on File (SCOF) service and Visa Token Service (VTS). A network token is a sequence of 16 characters that can be used in requests instead of the card number. When the card associated with a specific token is reissued or replaced or its details are changed in any other way, the token remains valid because the data associated with the token is updated automatically in the originating tokenisation service.

When processing payments via the Ecommpay payment platform, you can use network tokens if such tokens have already been created in the third-party services and are being used on the side of the merchant web service. In other cases, you can use the capabilities of processing payments with tokens via Payment Page (details) and Gate (details) and migrating information about payment card tokens from other acquirers (details).

If you have questions regarding the terms and conditions of using network tokens and the steps of integrating this functionality, refer to your Ecommpay account manager. If you have questions regarding the technical aspects of using network tokens, refer to the information on the documentation portal and to the Ecommpay technical support.

Special aspects and limitations

When processing payments with the use of network tokens, you need to consider the following:

  • The capability of using network tokens (for all supported card networks) must be enabled for the specific project.

    When this capability is not enabled for the project, payments with network tokens are declined with the 318 error code.

  • The use of network tokens is limited to several payment workflows that include processing one-time one-step and two-step purchases, registering and processing COF purchases with saved data stored on the side of the web service (details), and payment card verification.

    In other cases, for example, processing payment link purchases, COF payments with saved data stored on the side of the platform, or issuing payouts, you can only use tokens created in the payment platform (details).

  • Managing network tokens (creating, updating, and receiving data required for their use) is carried out via specialised services.

    To learn more about working with them, refer to documentation and specialists of these services.

  • The merchant is responsible for appropriate use of network tokens and the network token information.

    If you have questions concerning the incorrect use of network tokens, contact your Ecommpay account manager.

Request format

When creating a request for processing a payment with the network token, consider the following:

  1. The request must be sent to one of the following endpoints with the use of the HTTP POST method:
  2. In the card object, specify the following information about the network token and the card:
    • pan—the token created in the specialised service of the card network. Mandatory in all cases without exception.
    • year—the year of the token's expiration date (in the YYYY format according to the Gregorian calendar). Mandatory in all cases without exception.
    • month—the month of the token's expiration date (as a number without a leading zero). Mandatory in all cases without exception.
    • card_holder—the name of the cardholder, spelled as specified on the card. Mandatory in all cases, with permitted exceptions. Can be made optional only upon consultation with your Ecommpay account manager following a thorough examination and assessment of associated risks for specific projects which are configured by the Ecommpay technical support.
    • cvv—card verification code. Mandatory in all cases, with permitted exceptions. Can be optional if one of the following conditions is met:
      • The request references an on-demand or regular COF purchase registered earlier, with saved data stored on the side of the web service.
      • The request contains an authenticated token (the customer was authenticated when the token was created in the third-party service).
      • Before the request is sent, the customer was authenticated with the use of the 3‑D Secure protocol without the involvement of Ecommpay and the authentication result is provided in the authentication_data object.
      • The 3‑D Secure authentication via the Ecommpay platform is available for this payment (based on project specifics and technical resource availability).

      In all other cases, cvv is required. If you do not provide it in the request, the payment is declined.

    • stored_card_type—the indicator specifying how to proceed with the provided card (or token) data. Mandatory in all cases without exception and can take one of the following values:
      • 1 to save payment data or register a one-click purchase
      • 2 to process a payment with saved payment data or a one-click purchase
      • 3 to register an on-demand COF purchase
      • 4 to process an on-demand COF purchase
      • 5 to register a regular COF purchase
      • 6 to process a regular COF purchase

      You can find more information about working with COF purchases in Credential-on-file (COF) purchases.

  3. In the token_data object, pass the token_type parameter with the value network_token. Mandatory in all cases without exception.
  4. To register a COF purchase, pass the following parameters in the token_data object:
    • cryptogram—the verification code of the network token such as the Token Authentication Verification Value (TAVV) received from the network tokenisation service.
    • eci—the Electronic Commerce Indicator that corresponds to the token, received from the network tokenisation service.

    It is also recommended that you pass the trid parameter in the token_data object. trid is the identifier of the merchant assigned when the merchant registers in the network tokenisation service.

  5. When processing a COF purchase (the stored_card_type contains values 2, 4, or 6) made with a card issued in the European Economic Area, pass the scheme_id parameter in the card object. scheme_id is an identifier of the initial operation within which the COF purchase was registered on the side of Mastercard or Visa.
  6. Additionally, you can use any other parameters from the API specification of the endpoint you need.

Useful links

When working with network tokens, you can also use the following articles: