Checkout icon

Network tokenization

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

Card networks, like Visa, Mastercard, and American Express, offer services that create a network token for a card. A network token is 16-digit alternative for the Primary Account Number (PAN), and is unique per combination of shopper and merchant. When making a payment, the card details can be swapped for the network token.

Making payments with network tokens has important benefits:

  • Reduced shopper friction and declines because card networks maintain network tokens to ensure tokens remain valid when the card details change. For example, if the shopper receives a new card because the old one expired or was lost, the network token remains the same.
  • Higher authorization 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 single-use cryptogram.

This page describes how you can implement network tokenization.

Implementation options

Network tokenization is different from Adyen's tokenization feature.

  • With our tokenization feature, we swap the shopper's card details from your payment request for a recurringDetailReference token. You receive this token in the payment response so that you can use the token instead of the card details in later recurring payment requests for that same shopper.
  • With network tokenization, the shopper's card details are swapped for a network token. How this is done, depends on the implementation option you choose.

You can choose from the following two implementation options for making payments with network tokens:

  • Let Adyen manage network tokens on your behalf. This does not require any additional integration. We collect and store network tokens from the card schemes. When you send a payment request, we automatically swap the card details from your payment request for the network token and then forward the payment for authorization.
    You can still use our tokenization feature: when your payment request contains a recurringDetailReference token, we automatically swap that for a network token. In fact, we recommend combining network tokenization with our tokenization feature because that limits your PCI scope and further increases authorization rates.

  • Manage network tokens yourself. This requires additional steps, but you can keep your existing network tokens and use them in the payment requests that you send to Adyen. It is not possible to combine this with our tokenization feature.

In the US, both these options let you benefit from routing co-badged network tokens to the optimal network.

Co-badged network tokens in the US

In the US, some Visa, Mastercard, and Discover network tokens are co-badged with one or more US Debit networks: Accel, Maestro USA, NYCE, PULSE, or STAR. This means that it is possible to route the payment over the network with the lowest costs and/or the best authorization rate.

To enable routing co-badged network tokens, you need to add the US Debit payment methods to your merchant account.

Payment routing is based on:

  • Any routing priorities set for your merchant account. For example, 1: PULSE and 2: Visa.
  • Optimized routing determined by Adyen, provided this does not contradict any routing priorities for your account.

In addition, you can force the route for an individual payment:

  1. Make a POST /cardDetails request for a list of brands on the network token or card.
  2. In your /payments request, use the paymentMethod.brand parameter to specify the network over which you want to route the payment.

Let Adyen manage network tokens

If Adyen manages your network tokens, you can benefit from network tokenization without changing anything in your card payment integration. You continue using your regular payment flow, and Adyen does the rest by swapping card details or the recurringDetailReference token for a network token.

All you need to do is:

  1. Ask our Support Team to enable payments with network tokens.
  2. Optionally set up receiving additional information in your payment responses about the network tokens. You can collect:

Optional: Collect attempts data

If you want to analyze network token usage, you can set up receiving additional information in your /payments response about attempts to get a payment authorized with or without a network token.

To set up receiving attempts data:

  1. Log in to your Customer Area.
  2. Go to Developers > Additional data.
  3. In the Acquirer section, select Include the retry attempts.
  4. Select Save configuration.

The additionalData object in the /payments response will then contain the following parameters:

Parameter name Description
retry.attempt.acquirer The 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.
retry.attempt.rawResponse The details of the raw unmodified response from the acquirer.
retry.attempt.networkTokenOffered Indicates if the transaction was attempted with or without a network token.

In the following example, the additionalData object shows that the payment was approved on the first attempt (attempt1) and that a network token was used.

As shown in the next example, if a payment attempt with a network token fails (attempt1), we automatically retry the payment. But in this attempt (attempt2) we do not swap the card details or the recurringDetailReference token for a network token.

The AUTHORISATION webhook contains the same additional information as the additionalData object from the /payments response.

Optional: Collect data about network tokens

You can set up receiving the following additional information in your /payments response:

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

To set up receiving data about the network token:

  1. Log in to your Customer Area and switch to your merchant account.
  2. Go to Developers > Additional data.
  3. In the Card section, select Network token bin and summary for tokenised payments.
  4. Select Save configuration.

The additionalData object in the /payments response will then contain the following parameters:

Parameter name Description
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 The last four digits of the card.
latestCard.expiryDate The expiry month and year of the card.

Manage network tokens yourself

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 those network tokens to make payments with Adyen.

In this case, you need to send the network token in your /payments request, both in the initial payment and in any subsequent recurring payments.

Enable receiving relevant data

Before you start making payments with network tokens, you need to set up receiving 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 > Additional data.
  3. Select the following fields:
    • In the Acquirer section: Network Transaction Reference
    • In the Card section: Card bin and Card summary
  4. Select Save configuration.

Make the initial payment with a network token

Make a one-off payment, the first payment in a subscription, or the first payment for automatic top-ups.

  1. Make a POST /payments request, specifying:

    Parameter name Description
    paymentMethod.type networkToken
    paymentMethod.expiryMonth The expiry month of the network token.
    paymentMethod.expiryYear The expiry year of the network token.
    paymentMethod.cvc Optional. The card verification code or security code.
    paymentMethod.holderName The name of the cardholder associated with the network token.
    paymentMethod.number The network token you get from the card networks.
    paymentMethod.brand Optional. For co-badged network tokens in the US, this is the card network that you want to route the transaction to. Allowed values:
    • visa
    • mc
    • amex
    • discover
    • accel
    • maestro_usa
    • nyce
    • pulse
    • star
    mpiData.directoryResponse Y
    mpiData.authenticationResponse Y
    mpiData.tokenAuthenticationVerificationValue The network token authentication verification value (TAVV). This is the network token cryptogram.
    If using Checkout API v67 and earlier, use the parameter mpiData.cavv instead. This is the cardholder authentication value (CAVV) received 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

  2. In the /payments response, note the networkTxReference field. You need this value to make subsequent subscription or automatic top-up payments.

Make a subsequent payment with a network token

See also