Using 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 network token information instead of card details:
    • pan—the token created in the specialised service of the card network
    • year—the year of the token's expiration date (in the YYYY format according to the Gregorian calendar)
    • month—the month of the token's expiration date (as a number without a leading zero)
    • card_holder—the name of the cardholder, passed if this parameter is required for the project (the name must be spelled as specified on the card; note that if you want to make this parameter optional instead of required, it can only be done upon consultation with your account manager which includes examination and assessment of associated risks)
    • cvv—card verification code (required in all cases except for processing on-demand and regular COF purchases)
  3. In the token_data object, pass the following parameters:
    • token_type—the type of the token with the value network_token (required for each payment)
    • cryptogram—the verification code of the network token such as the Token Authentication Verification Value (TAVV) received from the network tokenisation service (required for registering COF purchases and optional for other payment types)
    • eci—the Electronic Commerce Indicator that corresponds to the token, received from the network tokenisation service (required for registering COF purchases and optional for other payment types
    • trid—the identifier of the merchant assigned when the merchant registers in the network tokenisation service (optional)
  4. In the required stored_card_type parameter, pass 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

  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, which 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: