Network tokenization

Card networks, like Visa, Mastercard and American Express, offer network tokenization services. A network token is 16-digit Primary Account Number (PAN) alternative, which is unique for each shopper-merchant pairing.

Here are the benefits of making payments with network tokens:

• Reduced shopper friction and declines because network tokens are maintained and automatically updated by card networks.
• Higher authorisation rates compared to payments made without network tokens.
• Minimal integration efforts for adopting EMVCo's network token standards.
• Better payment security because each transaction is protected with a one-time use cryptogram.

Because network tokens are managed by card networks, any update to the associated card doesn't require the token update. For example, if the card expires or the shopper loses the card and then re-issues it, you can still use the same token for transactions.

Network tokenization vs Adyen tokenization

Note that network tokenization is different from Adyen tokenization.

• With Adyen tokenization, we swap card details for a recurringDetailReference token which you can then use to make payments.
• With Network tokenization, card networks (schemes) provide a service which creates a network token for a card. This network token is stored by Adyen and can be then used in place of the card during the authorisation. In this case, you continue using your regular payments flow and Adyen takes care of automatically swapping card details for a network token when necessary.

We recommend that you use both features—Network tokenization and Adyen tokenization—together when you let Adyen provision and collect network tokens. This limits your PCI scope and potentially increases authorization rates.

Implementation options

To make payments with network tokens, you can choose between two options:

• Let Adyen provision and collect network tokens. This doesn't require any additional integration, make payments as you normally do.
• Use your existing network tokens. This requires additional steps but allows using your existing network tokens.

Let Adyen provision and collect network tokens

We collect network tokens from Visa, Mastercard, and American Express. These tokens are securely stored with Adyen and are used instead of the card in the authorisation process.

You don't need to do any additional integration to get the benefits of network tokenization if Adyen requests and collects tokens on your behalf. Follow the regular payment flow corresponding to your type of card payment integration. Adyen does the rest by swapping card details or the recurringDetailReference token for a network token for better authorisation rates.

To enable payments with network tokens, contact our Support Team.

Optional: Collect attempts data

When you let Adyen provision and collect network tokens, you can optionally choose to get additional information about attempts to try a payment with or without a network token in your /payments response. This is useful when you want to analyze network token results.

To get information about attempts:

1. Log in to your Customer Area.
2. Go to Developers > API URLs > Additional data setting.
3. Under the Acquirer section, select Include the retry attempts.

After you enable this option, the additionalData object in the /payments response will contain the following parameters:

• retry.attempt.acquirer: Name of the acquirer that processed the payment.
• retry.attempt.acquirerAccount: The acquirer account that was used for the transaction.
• 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 /payments response.

Here is an example response where a payment was attempted (attempt1) with a network token, and was approved.

{
   ...
   "additionalData": {
      "retry.attempt1.acquirer": "Acquirer",
      "retry.attempt1.acquirerAccount": "AcquirerAccount",
      "retry.attempt1.responseCode": "00",
      "retry.attempt1.rawResponse": "Approved or completed successfully",
      "retry.attempt1.networkTokenOffered": "true"
   }
}

Here is an example with an unsuccessful attempt (attempt1) with a network token followed immediately by another successful attempt (attempt2) with raw card details or the recurringDetailReference token.

{
   ...
   "additionalData": {
      "retry.attempt2.acquirer": "Acquirer",
      "retry.attempt2.acquirerAccount": "AcquirerAccount",
      "retry.attempt2.responseCode": "00",
      "retry.attempt2.rawResponse": "Approved or completed successfully",
      "retry.attempt2.networkTokenOffered": "false",
      "retry.attempt1.acquirer": "Acquirer",
      "retry.attempt1.acquirerAccount": "AcquirerAccount",
      "retry.attempt1.responseCode": "05",
      "retry.attempt1.rawResponse": "Refused",
      "retry.attempt1.networkTokenOffered": "true"
   }
}

As part of the AUTHORISATION notification, the same additionalData object from the /payments response is present as additional information. The results of both payment attempts are included in the same notification.

Optional: Collect more information about network tokens

When you let Adyen provision and collect network tokens, you can optionally receive:

• The BIN and summary of the network token used.
• The BIN, last four digits, and expiry date of the card associated with the network token.

To get the additional information about the network token in your payment response:

1. Log in to your Customer Area.
2. Switch to your merchant account.
3. Go to Developers > API URLs.
4. In the Additional data settings tab, select Network token bin and summary for tokenised payments.
5. Select Save configuration.

The additionalData object in the payment response will then contain:

• networkToken.bin: The BIN of the network token.
• networkToken.tokenSummary: The last four digits of the network token.
• latestCard.bin: The BIN of the card. This is only returned for Mastercard tokens.
• latestCard.summary: Last four digits of the card.
• latestCard.expiryDate: The expiry month and year of the card.

{
  ...
  "additionalData": {
    "latestCard.bin": "557703",
    "latestCard.summary": "4309", 
    "latestCard.expiryDate": "03/2030",
    "networkToken.available": "true",
    "networkToken.bin": "489537",
    "networkToken.tokenSummary": "3500"
  }
}

Use existing network tokens without tokenizing with Adyen

Because network tokens are non-sensitive, you can also choose to collect and store them yourself. If you are already collecting network tokens from card networks like Visa, Mastercard and American Express, you can use them to make payments with Adyen. In this case, 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. Log in to your Customer Area.
2. Go to Developers > API URLs > Additional data settings.
3. Select the following fields:
   • Network Transaction Reference
   • Card bin
   • Card summary
4. Select Save configuration.

Make a one-off payment, the first payment in a subscription, or an automatic top-up

Make a POST request to /payments, specifying the following parameters:

• paymentMethod.type: networkToken.
• paymentMethod.brand: visa, mc, or amex.
• 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.
• 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.

{
    "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 the following details:

• paymentMethod.type: networkToken.
• paymentMethod.brand: visa, mc, or amex.
• 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.
• 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.

{
    "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.

{
   ...
   "additionalData":{
      "cardBin":"541333",
      "cardSummary":"1111",
      "networkTxReference":"MCC123456789012",
      ...
   }
}

See also