---
title: "Network tokenization"
description: "Use network tokens to process payments with Adyen for better authorization rates."
url: "https://docs.adyen.com/online-payments/network-tokenization"
source_url: "https://docs.adyen.com/online-payments/network-tokenization.md"
canonical: "https://docs.adyen.com/online-payments/network-tokenization"
last_modified: "2023-06-21T22:37:00+02:00"
language: "en"
---

# Network tokenization

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

[View source](/online-payments/network-tokenization.md)

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](https://www.emvco.com/emv-technologies/payment-tokenisation/).
* Better payment security because each transaction is protected with a single-use cryptogram.

This page describes how you can implement network tokenization.

## Requirements

| Requirement                                                               | Description                                                                                                                        |
| ------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| **Integration type**                                                      | An [online payments integration](/online-payments/build-your-integration/) that supports [card payments](/payment-methods/cards/). |
| **[API credential roles](/development-resources/api-credentials/roles/)** | Make sure that you have the following role(s):- **Checkout webservice role**
- **Merchant Recurring role**                         |
| **[Webhooks](/development-resources/webhooks)**                           | Subscribe to the Standard webhooks.                                                                                                |
| **Limitations**                                                           | Network tokenization is only applicable for payments acquired by Adyen. It cannot be used with external acquirer connections.      |

## How it works

Network tokenization is different from [Adyen tokenization](/online-payments/tokenization). With **tokenization**, Adyen swaps the shopper's card details from your payment request for a token. You receive this token in a webhook 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:

* **[Let Adyen manage network tokens](#network-tokens-collected-by-Adyen) on your behalf.**\
  This option 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 use our tokenization feature together with network tokenization. When your payment request contains a `storedPaymentMethodId` token, we automatically swap that for a network token. We recommend combining these features because that limits your PCI scope and further increases authorization rates.

* **[Manage network tokens yourself](#existing-network-tokens).**\
  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.

### Sharing network tokens

If you use multiple merchant accounts, you can share network tokens between them. This allows a shopper to use their saved card seamlessly across all of your websites or apps. To enable this feature, contact our [Support Team](https://ca-test.adyen.com/ca/ca/contactUs/support.shtml?form=other).

### Forward network tokens

You can [forward network tokens](/online-payments/tokenization/forward-payment-details) to a PCI-compliant third party, such as another payment service provider.

## Co-badged network tokens in the US

Regardless of the [implementation option](#how-it-works) you choose, you can benefit from routing [co-badged network tokens](#co-badged-in-us) to the optimal network 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.

### Force the route for an individual payment

You can force the route for an individual payment:

1. Make a POST [/cardDetails](https://docs.adyen.com/api-explorer/Checkout/latest/post/cardDetails) request for a list of brands on the network token or card.
2. In your [/payments](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments) request, use the `paymentMethod.brand` parameter to specify the network over which you want to route the payment.

## Let Adyen manage network tokens

To manage network tokens yourself, ask our [Support Team](https://ca-test.adyen.com/ca/ca/contactUs/support.shtml?form=other) to enable payments with network tokens.

If Adyen manages your network tokens, you can benefit from network tokenization without changing anything in your [card payment integration](/payment-methods/cards). You continue using your regular payment flow, and Adyen swaps card details or the `storedPaymentMethodId` token for a network token.

Optionally, you can set up receiving the following additional data in your payment responses:

* [Data about attempts to use a network token](#attempts-data).
* [Data about the network token itself](#optional-collect-bin-and-summary-of-the-network-token).

### Collect attempts data

If you want to analyze network token usage, you can set up receiving additional information in your [/payments](https://docs.adyen.com/api-explorer/Checkout/latest/post/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](https://ca-test.adyen.com/).
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](https://docs.adyen.com/api-explorer/Checkout/latest/post/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](/development-resources/raw-acquirer-responses#visa-and-mastercard-raw-responses) from the card network. |
| `retry.attempt.rawResponse`         | The details of the [raw unmodified response from the acquirer](/development-resources/raw-acquirer-responses).                               |
| `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.

**Successful first attempt with a network token**

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

If a payment attempt with a network token fails (`attempt1`), we automatically retry the payment. In the second attempt (`attempt2`), we do not swap the card details or the `storedPaymentMethodId` token for a network token.

**First attempt with network token failed, second attempt without network token succeeded**

```json
{
   ...
   "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"
   }
}
```

The **AUTHORISATION** webhook contains the same additional information as the `additionalData` object from the [/payments](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments) response.

### Collect data about network tokens

You can set up receiving the following additional information in your [/payments](https://docs.adyen.com/api-explorer/Checkout/latest/post/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](https://ca-test.adyen.com/) 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](https://docs.adyen.com/api-explorer/Checkout/latest/post/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.                            |

**Additional data for the BIN and summary of the network token**

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

## 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.

To manage network tokens yourself:

1. [Enable receiving relevant data](#enable-receiving-relevant-data) in your Customer Area to receive card details and network token information in the payment response.
2. [Make the initial payment with a network token](#make-the-initial-payment-with-a-network-token), using the network token you collect from the card network.
3. You receive the `networkTxReference` that you need to use for subsequent payments in the payment response. Save this value.
4. [Make a subsequent payment using the same network token](#make-a-subsequent-payment-with-a-network-token).

### Enable receiving relevant data

To enable the relevant fields:

1. Log in to your [Customer Area](https://ca-test.adyen.com/).

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](https://docs.adyen.com/api-explorer/Checkout/latest/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](#co-badged-in-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](/online-payments/tokenization#recurring-payment-types).                                                                                                              |
   | `shopperInteraction`                           | **Ecommerce**                                                                                                                                                                                                                                                           |

   **Initial one-off /payments request with a network token**

   ```json
   {
      "merchantAccount": "YOUR_MERCHANT_ACCOUNT",
      "reference": "YOUR_PAYMENT_REFERENCE",
      "amount": {
         "currency": "USD",
         "value": 1000
      },
      "paymentMethod": {
         "type": "networkToken",
         "brand": "visa",
         "expiryMonth": "08",
         "expiryYear": "2028",
         "cvc": "737",
         "holderName": "CARDHOLDER_NAME",
         "number": "666666xxxxxx6666"
      },
      "mpiData":{
         "directoryResponse":"Y",
         "authenticationResponse":"Y",
         "tokenAuthenticationVerificationValue":"AAEBAwQjSQAAXXXXXXXJYe0BbQA=",
         "eci":"07"
      },
      "returnUrl": "https://your-company.example.com/",
      "shopperReference": "YOUR_SHOPPER_REFERENCE",
      "recurringProcessingModel":"CardOnFile",
      "shopperInteraction": "Ecommerce"
   }
   ```

2. In the [/payments](https://docs.adyen.com/api-explorer/Checkout/latest/post/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

Make a subsequent payment, using the `networkTxReference` you received in the payment response.

### Tab: One-off payments

1. Make a POST [/payments](https://docs.adyen.com/api-explorer/Checkout/latest/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](#co-badged-in-us), this is the card network that you want to route the transaction to. This may be different compared to the initial payment. 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`                     | The value must match the value of the `recurringProcessingModel` from the initial payment. For a one-off payment, that is **CardOnFile**.                                                                                                                                                                                      |
   | `shopperInteraction`                           | **ContAuth**                                                                                                                                                                                                                                                                                                                   |

   **Recurring one-off /payments request with a network token**

   ```json
   {
      "merchantAccount": "YOUR_MERCHANT_ACCOUNT",
      "reference": "YOUR_PAYMENT_REFERENCE",
      "amount": {
         "currency": "USD",
         "value": 1000
      },
      "paymentMethod": {
         "type": "networkToken",
         "brand": "visa",
         "expiryMonth": "08",
         "expiryYear": "2028",
         "cvc": "737",
         "holderName": "CARDHOLDER_NAME",
         "number": "666666xxxxxx6666",
      },
      "mpiData":{
         "directoryResponse":"Y",
         "authenticationResponse":"Y",
         "tokenAuthenticationVerificationValue":"AAEBAwQjSQAAXXXXXXXJYe0BbQA=",
         "eci":"07"
      },
      "returnUrl": "https://your-company.example.com/",
      "shopperReference": "YOUR_SHOPPER_REFERENCE",
      "recurringProcessingModel": "CardOnFile",
      "shopperInteraction": "ContAuth"
   }
   ```

2. In the response, note the `additionalData` object. This has information such as the BIN and summary of the card that was charged.

   **Additional data object in /payments response**

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

### Tab: Subscriptions or automatic top-offs

1. Make a POST [/payments](https://docs.adyen.com/api-explorer/Checkout/latest/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](#co-badged-in-us), this is the card network that you want to route the transaction to. This may be different compared to the initial payment. Allowed values:- **visa**
   - **mc**
   - **amex**
   - **discover**
   - **accel**
   - **maestro\_usa**
   - **nyce**
   - **pulse**
   - **star** |
   | `paymentMethod.networkPaymentReference` | The network transaction reference. This is the value of the `networkTxReference` field that you received in the response of the initial payment.                                                                                                                                                                               |
   | `recurringProcessingModel`              | This value must match the value of the `recurringProcessingModel` from the first payment, either **Subscription**, or **UnscheduledCardOnFile**.                                                                                                                                                                               |
   | `shopperInteraction`                    | **ContAuth**                                                                                                                                                                                                                                                                                                                   |

   **Recurring subscription /payments request with a network token**

   ```json
   {
      "merchantAccount": "YOUR_MERCHANT_ACCOUNT",
      "reference": "YOUR_PAYMENT_REFERENCE",
      "amount": {
         "currency": "USD",
         "value": 1000
      },
      "paymentMethod": {
         "type": "networkToken",
         "brand": "visa",
         "expiryMonth": "08",
         "expiryYear": "2028",
         "holderName": "CARDHOLDER_NAME",
         "number": "666666xxxxxx6666",
         "networkPaymentReference": "MCC123456789012"
      },
      "returnUrl": "https://your-company.example.com/",
      "shopperReference": "YOUR_SHOPPER_REFERENCE",
      "recurringProcessingModel": "Subscription",
      "shopperInteraction": "ContAuth"
   }
   ```

2. In the response, note the `additionalData` object. This has information such as the BIN and summary of the card that was charged.

   **Additional data object in /payments response**

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

## Troubleshooting

When you make a request to create or pay with a network token, the API response informs you of the outcome of the request. If an error occurs, the response includes the `status`, `errorCode`, and `errorMessage` parameters.

**Example response for a network token failure**

```json
{
    "status": 500,
    "errorCode": "26_002",
    "message": "The network token is suspended/deactivated",
    "errorType": "internal"
}
```

Use the [error code and message](/development-resources/error-codes#network-token-error-codes) to learn about the issue and troubleshoot.

## See also

* [Tokenization](/online-payments/tokenization)
* [EMVCo's Payment Tokenization Specification](https://www.emvco.com/emv-technologies/payment-tokenisation/)
* [Webhooks](/development-resources/webhooks)
