Search

Are you looking for test card numbers?

Would you like to contact support?

Online-payment icon

Network tokenization

Use network tokens to process payments with Adyen for better authorisation rates.

Card networks, like Visa and Mastercard, offer network tokenization services. Network tokens are 16 digit numbers just like raw card numbers. They are unique for each shopper-company pairing, but are different from the shopper's actual card number. Network tokens are different from tokens provided by Adyen to store your shopper's recurring payment details.

This page is about network tokens from card networks like Visa and Mastercard. To learn more about Adyen tokens, go to Tokenization.

We recommend that you use both features (Adyen tokens and network tokens from card networks) together. This limits your PCI scope and takes advantage of the potentially increased authorization rates.

Benefits of using network tokens

When you make payments with network tokens, you can:

  • Give shoppers a better shopping experience, as network tokens are maintained and automatically updated by card networks.
  • Have higher authorisation rates, compared to payments made without network tokens.
  • Adopt EMVCo's network token standards with minimal integration efforts.
  • Increase payment security as network tokens are protected with a cryptogram.

Implementation options

To make payments with network tokens, you can either:

Collect and use new network tokens

You don't need to do any additional integration to get the benefits of network tokens if Adyen requests them on your behalf. Contact Support Team to pay with network tokens that we collect from Visa and Mastercard for you.

Optional: Collect retry data

You can optionally choose to get information about attempts to retry payments in your payment response. To do so, contact Support Team.

If you chose to include the retry attempts in your /payments response, the additionalData object will contain:

  • retry.attempt.acquirer: The acquirer processing payments on your behalf.
  • retry.attempt.acquirerAccount: The acquirer account specific to you.
  • retry.attempt.responseCode: The numeric acquirer response code from the card network for a refused or cancelled payment.
  • retry.attempt.rawResponse: The details of the raw unmodified response from the acquirer for refused or cancelled transactions.
  • retry.attempt.networkTokenOffered: Whether the transaction was attempted with or without a network token.

    The following examples show the additionalData object in the payment response that provides the details of an attempt (attempt1) with a network token, followed immediately by another attempt (attempt2) with the raw card details or the recurringDetailReference.

    Additional data for the first attempt at the payment with network tokens
    {
       ...
       "additionalData": {
          "retry.attempt1.acquirer": "Acquirer",
          "retry.attempt1.acquirerAccount": "AcquirerAccount",
          "retry.attempt1.responseCode": "7",
          "retry.attempt1.rawResponse": "Pickup card, special condition",
          "retry.attempt1.networkTokenOffered": "true"
       }
    }
    Additional data for the second attempt at the payment without network tokens
    {
       ...
       "additionalData": {
          "retry.attempt2.acquirer": "Acquirer",
          "retry.attempt2.acquirerAccount": "AcquirerAccount",
          "retry.attempt2.responseCode": "7",
          "retry.attempt2.rawResponse": "Pickup card, special condition",
          "retry.attempt2.networkTokenOffered": "false"
       }
    }

As part of the AUTHORISATION notification, the same additionalData object from the payment response is present as additional information. The result of both payment attempts will be included in the same notification.

Pay with existing network tokens

If you're already collecting network tokens from card networks like Mastercard and Visa, you can use them to make payments with Adyen. You need to send the network token in your /payments request.

Before you begin

Before you start processing payments with network tokens, make sure you enable the relevant fields that will provide you with card details and network token information in the payment response.

To enable the relevant fields:

  1. Go to Customer Area > Account > API URLs > Additional data settings.
  2. Enable the following fields:
    • Network Transaction Reference
    • Card bin
    • Card summary
  3. Click Save configuration.

Make a one-off payment or the first payment in a subscription

  • Make a POST request to /payments, specifying:

    • paymentMethod.type: networkToken
    • paymentMethod.brand: visa or mc
    • paymentMethod.expiryMonth: The expiry month of the network token
    • paymentMethod.expiryYear: The expiry year of the network token
    • paymentMethod.holderName: The name of the cardholder associated with the network token.
    • paymentMethod.number: The network token you get from the card networks (for example, from Mastercard and Visa).
    • mpiData.directoryResponse: Y
    • mpiData.authenticationResponse: Y
    • mpiData.cavv: The cryptogram value. This is the cardholder authentication value you get from the issuer.
    • mpiData.eci: The electronic commerce indicator you get from the issuer.
    • recurringProcessingModel: CardOnFile, Subscription, or UnscheduledCardOnFile, depending on your business model.
    • shopperInteraction: Ecommerce.
    /payments request for one-off payment
    {
        "merchantAccount": "YOUR_MERCHANT_ACCOUNT",
        "reference": "YOUR_PAYMENT_REFERENCE",
        "amount": {
            "currency": "USD",
            "value": 1000
        },
        "paymentMethod": {
            "type": "networkToken",
            "brand": "visa",
            "expiryMonth": "08",
            "expiryYear": "2020",
            "holderName": "CARDHOLDER_NAME",
            "number": "666666xxxxxx6666",
        },
        "mpiData":{
            "directoryResponse":"Y",
            "authenticationResponse":"Y",
            "cavv":"AAEBAwQjSQAAXXXXXXXJYe0BbQA=",
            "eci":"05"
        },
        "returnUrl": "https://your-company.com/",
        "shopperReference": "YOUR_SHOPPER_REFERENCE",
        "recurringProcessingModel":"CardOnFile",
        "shopperInteraction": "Ecommerce"
    }

In the /payments response, you can find the networkTxReference field. You need this value to make subsequent payments.

Make a subsequent payment with a network token

  • Make a POST request to /payments, specifying:

    • paymentMethod.type: networkToken
    • paymentMethod.brand: visa or mc
    • paymentMethod.expiryMonth: The expiry month of the network token
    • paymentMethod.expiryYear: The expiry year of the network token
    • paymentMethod.holderName: The name of the cardholder associated with the network token.
    • paymentMethod.number: The network token you get from the card networks (for example, from Mastercard and Visa).
    • paymentMethod.networkPaymentReference: The network token reference. This is the value of the networkTxReference field that you can find in the response of the first payment.
    • recurringProcessingModel: CardOnFile, Subscription, or UnscheduledCardOnFile. This value must match the value of the recurringProcessingModel from the first payment.
    • shopperInteraction: ContAuth.
    /payments request for recurring payments
    {
        "merchantAccount": "YOUR_MERCHANT_ACCOUNT",
        "reference": "YOUR_PAYMENT_REFERENCE",
        "amount": {
            "currency": "USD",
            "value": 1000
        },
        "paymentMethod": {
            "type": "networkToken",
            "brand": "visa",
            "expiryMonth": "08",
            "expiryYear": "2020",
            "holderName": "CARDHOLDER_NAME",
            "number": "666666xxxxxx6666",
            "networkPaymentReference": "MCC123456789012"
        },
        "returnUrl": "https://your-company.com/",
        "shopperReference": "YOUR_SHOPPER_REFERENCE",
        "recurringProcessingModel": "CardOnFile",
        "shopperInteraction": "ContAuth"
    }

    The additionalData object of the payment response has information such as the BIN and summary of the card that was actually charged.

    Additional data object in /payments response
    {
       ...
       "additionalData":{
          "cardBin":"541333",
          "cardSummary":"1111",
          "networkTxReference":"MCC123456789012",
          ...
       }
    }

See also