> ## Documentation Index
> Fetch the complete documentation index at: https://primer.io/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Network Tokenization

export const ApiEndpoint = ({method, path}) => {
  const getMethodColor = method => {
    switch (method?.toUpperCase()) {
      case "GET":
        return "#0285c7";
      case "POST":
        return "#008d71";
      case "PUT":
        return "#16a34a";
      case "PATCH":
        return "#808080";
      case "DELETE":
        return "#dc2626";
      default:
        return "#6b7280";
    }
  };
  const getEndpointUrl = (method, path) => {
    const endpoints = {
      "POST /client-session": "/api-reference/v2.4/api-reference/client-session-api/create-a-client-session",
      "PATCH /client-session": "/api-reference/v2.4/api-reference/client-session-api/update-client-session",
      "POST /payments": "/api-reference/v2.4/api-reference/payments-api/create-a-payment",
      "POST /payments/<YOUR-PAYMENT-ID>/resume": "/api-reference/v2.4/api-reference/payments-api/resume-payment",
      "POST /payments/<YOUR-PAYMENT-ID>/adjust-authorization": "/api-reference/v2.4/api-reference/payments-api/adjust-authorized-amount",
      "POST /payments/<PAYMENT_ID>/cancel": "/api-reference/v2.4/api-reference/payments-api/cancel-payment",
      "POST /payments/<PAYMENT_ID>/refund": "/api-reference/v2.4/api-reference/payments-api/refund-payment",
      "GET /payments/<PAYMENT_ID>": "/api-reference/v2.4/api-reference/payments-api/get-a-payment",
      "GET /payment-instruments": "/api-reference/v2.4/api-reference/payment-methods-api/list-saved-payment-methods",
      "DELETE /payment-instruments/<PAYMENT_METHOD_TOKEN>": "/api-reference/v2.4/api-reference/payment-methods-api/delete-payment-method-payment-methods-token-delete"
    };
    const key = `${method?.toUpperCase()} ${path}`;
    return endpoints[key] || "#";
  };
  const getPrettyPath = (method, path) => {
    const pathMapping = {
      "POST /payments/<YOUR-PAYMENT-ID>/resume": "/payments/{paymentId}/resume",
      "POST /payments/<YOUR-PAYMENT-ID>/adjust-authorization": "/payments/{paymentId}/adjust-authorization",
      "POST /payments/<PAYMENT_ID>/cancel": "/payments/{paymentId}/cancel",
      "POST /payments/<PAYMENT_ID>/refund": "/payments/{paymentId}/refund",
      "GET /payments/<PAYMENT_ID>": "/payments/{paymentId}",
      "DELETE /payment-instruments/<PAYMENT_METHOD_TOKEN>": "/payment-instruments/{paymentMethodToken}"
    };
    const key = `${method?.toUpperCase()} ${path}`;
    return pathMapping[key] || path;
  };
  const methodColor = getMethodColor(method);
  const url = getEndpointUrl(method, path);
  const displayPath = getPrettyPath(method, path);
  return <div style={{
    display: "inline-flex",
    alignItems: "center",
    cursor: "pointer",
    margin: "2px 0",
    padding: "4px",
    paddingRight: "6px",
    background: "rgb(245, 245, 245)",
    borderRadius: "6px",
    whiteSpace: "nowrap",
    textDecoration: "none"
  }}>
      <a href={url} target="_blank" rel="noopener noreferrer" style={{
    textDecoration: "none",
    border: "none"
  }}>
        <span style={{
    display: "inline-block",
    whiteSpace: "nowrap",
    padding: "0 8px",
    fontSize: "13px",
    lineHeight: "23px",
    borderRadius: "6px",
    fontWeight: 400,
    backgroundColor: methodColor,
    color: "white",
    border: "none"
  }}>
          {method.toUpperCase()}
        </span>
        <code style={{
    padding: "0",
    marginLeft: "4px",
    fontFamily: "monospace",
    color: methodColor,
    border: "none",
    textDecorationColor: methodColor
  }}>
          {displayPath}
        </code>
      </a>
    </div>;
};

<Frame caption="Network Tokenization Overview">
  <img src="https://goat-assets.production.core.primer.io/marketing/payment-capabilities/external-docs/network-tokenization/network-tokenization-concept.png" />
</Frame>

## What is Network Tokenization?

Network tokenization is a service provided by card networks, such as Visa and Mastercard, where they directly provide a token as a substitute for the 14 to 19 digit primary account number (PAN).

A network token can be used instead of the PAN when processing payments and is more secure because:

* It minimizes the risk of exposing customers' sensitive information because a token is exchanged instead of the raw card details.
* The token is unique to the customer and merchant pairing, and can't be used by a bad actor for any merchant online like they could with the PAN.
* For customer-initiated payments, a one-time cryptogram called the Token Authentication Verification Value (TAVV) needs to be generated which acts as the equivalent of the CVV. This can only be generated by the token requestor who created the network token.

As well as being secure, network tokens aren't impacted by updates to a card. This means that if a card expires but a network token is already created, the network token can continue to be used for recurring payments and help to reduce churn.

<Note>
  Learn more about network tokens by [reading this blog post on how to optimize payments using network tokenization.](https://primer.io/blog/how-to-optimise-payments-using-network-tokenization/)
</Note>

## Get Started with Primer

As your unified payments infrastructure, Primer acts as your centralized Technical Service Provider (TSP), giving you all the powerful capabilities of using network tokens without you having to do any engineering work.

<Frame caption="Network Tokenization Flow">
  <img src="https://goat-assets.production.core.primer.io/marketing/payment-capabilities/external-docs/network-tokenization/network-tokenization-diagram.png" />
</Frame>

<Note>
  Primer currently only supports network tokens for Visa and Mastercard.
</Note>

Creating network tokens and processing payments with them requires three steps:

1. Activate network tokenization for your Primer account
2. Create network tokens
3. Process payments with network tokens

### Activate network tokenization for your Primer account

To activate network tokenization, speak to your Customer Success Manager or raise a ticket on our [Support Portal](https://primerapi.atlassian.net/servicedesk/customer/portal/11).

As part of enrolling, we will register your company as a token requestor and generate a token requestor ID (TRID) directly with the card networks on your behalf.

<Warning>
  This can take up to 48 hours to become active due to back-office operations on the card network side.
</Warning>

### Create network tokens

Once network tokenization is fully activated for your account, go to the [Network Tokenization section](https://dashboard.primer.io/payment-services/network-tokenization/configuration) of your Dashboard to start creating network tokens.

<Frame caption="Network Token Creation Configuration">
  <img src="https://goat-assets.production.core.primer.io/marketing/payment-capabilities/external-docs/network-tokenization/creation-configuration.png" />
</Frame>

Three strategies are available for creating network tokens:

| Strategy                                | Description                                                                                                                                   | Recommendation                                                                                                                                                                                                                                                                                                   |
| --------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **for newly-vaulted cards**             | Attempts to create a network token after a new card is vaulted.                                                                               | This strategy is the cheapest but also the slowest at increasing the pool of available network tokens to make payments.                                                                                                                                                                                          |
| **for previously-vaulted cards**        | Attempts to create a network token after an already-vaulted card is used.                                                                     | This strategy can greatly increase the number of available network tokens in the short term to speed up your experiment. ⚠️ As this strategy does not create network tokens for new cards added to your vault, the pool of available network tokens will reduce over time. We recommend using the next strategy. |
| **for all vaulted cards** (Recommended) | A combination of the above two strategies. Attempts to create a network token after a new card is vaulted or an already-vaulted card is used. | This strategy ensures the highest number of available network tokens at all time.                                                                                                                                                                                                                                |

Based on the selected strategy, we will automatically try to create a network token on:

* vaulting events i.e. if you set `vaultOnSuccess` or `vaultOn3DS` to `True` in <ApiEndpoint method="POST" path="/client-session" /> or <ApiEndpoint method="POST" path="/payments" />
* new payments i.e. if you make a payment with an already-vaulted card

Once created, the network token will be linked to the vaulted Primer token so that it can be used for processing.

<Note>
  In any case, the network token is **not** created and used for the first payment, but only created after the first payment and then used for processing on subsequent payments.

  This is the advice from card networks due to the additional latency that would be caused during the first payment flow and the negative impact it would have on the checkout.
</Note>

#### Check the creation of network tokens

If a network token was successfully created, this will be reflected in the `paymentMethod` object of subsequent payments where `isNetworkTokenized` will be set to `True`.

The number of created Network Tokens is also visible in the

[Network Tokenization's Reporting section](https://dashboard.primer.io/payment-services/network-tokenization/reporting").

### Process payments with your network tokens

By default, Primer ignores the created network tokens and uses the PAN to process card payments. When you are ready to process payments with your network tokens, go to the [Network Tokenization section](https://dashboard.primer.io/payment-services/network-tokenization/configuration) of your Dashboard to activate and configure when network tokens should be used.

<Frame caption="Network Token Processing Configuration">
  <img src="https://goat-assets.production.core.primer.io/marketing/payment-capabilities/external-docs/network-tokenization/processing-configuration.png" />
</Frame>

There, select which processor merchant accounts should use a network token if it's available when processing payments. You can also set the processing volume for each merchant account based on your rollout or experiment strategy:

| Processing Volume | Description                                                                                                                                    | When to use?                                                                                                                                  |
| ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| 10%               | 10% of the payments initiated with a network tokenized card will be processed using the network token. The other 90% will use the PAN instead. | When you want to start slow and validate that everything is ready to process network tokens at scale.                                         |
| 50%               | 50% of the payments initiated with a network tokenized card will be processed using the network token. The other 50% will use the PAN instead. | When you want to run an A/B test that compares the performance of network token vs. PAN.                                                      |
| 90%               | 90% of the payments initiated with a network tokenized card will be processed using the network token. The other 10% will use the PAN instead. | When you want to fully rollout network tokens but you still want to compare the performance of network token vs. PAN.                         |
| 100%              | This merchant account will always use the network token if it is available. The PAN will be ignored.                                           | When you want to fully rollout network tokens. <br />⚠️ You will not be able to accurately compare the performance of network tokens vs. PAN. |

The processing volume applies to both customer-initiated payments (CIT) using a saved card and merchant-initiated payments (MIT).

For CITs, in the background, a one-time cryptogram (TAVV) is generated directly from the card network which acts as the equivalent of the CVV. If the TAVV generation fails for whatever reason, we will fall back to using the PAN as usual.

<Note>
  Not all processors support external network tokens and some processors, such as Stripe, require your account to be gated in on their side before allowing external network tokens.

  Please speak to your Customer Success Manager or our [Support Portal](https://primerapi.atlassian.net/servicedesk/customer/portal/11) to understand which of your processors are able to process network tokens created by Primer.
</Note>

#### Check that a payment was processed with a network token

There are two ways to see if a network token was used for a payment:

1. In the payment object, the `cardTokenType` field is set to `NETWORK_TOKEN`. It is set at the payment level and transaction level.

   This field is available in both the [API response](/api-reference/v2.4/api-reference/payments-api/get-a-payment#response.body.cardTokenType) and the [webhook body](/api-reference/endpoints/v2.4/payment-webhooks/payment-status-update).

   <Note>
     This is only available on API and Webhook version 2.2 or greater.
   </Note>

   See below for an example:

   ```json JSON theme={"dark"}
   {
     "id": "kHdEw9EG",
     "date": "2021-02-21T15:36:16.367687",
     "status": "AUTHORIZED",
     "orderId": "order-abc",
     "customerId": "customer-123",
     "currencyCode": "EUR",
     "amount": 42,
     "cardTokenType": "NETWORK_TOKEN",
   	...
     "transactions": [
       {
         "type": "SALE",
         "processorStatus": "AUTHORIZED",
         "processorName": "STRIPE",
         "processorMerchantId": "acct_stripe_1234",
         "processorTransactionId": "54c4eb5b3ef8a",
         "cardTokenType": "NETWORK_TOKEN"
       }
     ]
   }
   ```

2. In the payment timeline, you can see the raw processor requests and responses. When a network token is used, you'll see `{{NETWORK_TOKEN_*}}` fields in the request instead of `{{PRIMER_*}}` fields.

   See below for an example:

   <Frame caption="Payment Timeline Example">
     <img src="https://goat-assets.production.core.primer.io/marketing/payment-capabilities/external-docs/network-tokenization/payment-timeline-example.png" />
   </Frame>

3. The payment appears when you set the filter `Card Token Type Used` to `NETWORK_TOKEN`.

<Note>
  If the payment falls back to a merchant account that is not configured for network tokens, the payment will be processed using the PAN and will be not considered to be a Network Token payment anymore.
</Note>

### Managing card updates

You don't have to do anything here - Primer handles this for you and will update the records accordingly.

## Testing network tokens

<Note>
  [Read the detailed guide on how to test network tokens on Primer.](/testing/network-tokenization)
</Note>

## PAN retries

<Note>
  PAN retries are deactivated by default. Contact us to activate it on your account.
</Note>

Primer can automatically retry a declined network token transaction with the underlying PAN to maximize the overall chances of payment success.

When this capability is activated, network token transactions declined with one of the following reasons will be automatically retried by sending the PAN to the same processor:

| **Status** | **Error Decision Type** | **Error Decline Type** | **Error Decline Reason**       |
| :--------- | :---------------------- | :--------------------- | :----------------------------- |
| Declined   | Gateway Rejected        | N/A                    | N/A                            |
| Declined   | Issuer Declined         | Soft Decline           | Declined                       |
| Declined   | Issuer Declined         | Soft Decline           | Refer to Card Issuer           |
| Declined   | Issuer Declined         | Soft Decline           | Issuer Temporarily Unavailable |
| Declined   | Issuer Declined         | Soft Decline           | Do Not Honor                   |
| Declined   | Issuer Declined         | Soft Decline           | Suspected Fraud                |
| Declined   | Issuer Declined         | Soft Decline           | Expired Card                   |
| Declined   | Issuer Declined         | Soft Decline           | Error                          |
| Failed     | Application Error       | N/A                    | N/A                            |

The performance of the Network Token strategy, including and excluding the performance of the "PAN retry" logic, is visible in your Dashboard.

## Caveats

### Activate external network tokens with Stripe

Although Stripe can process the network tokens created by a third-party like Primer, Stripe disables this capability by default.

Before processing Primer network tokens with Stripe, please contact your Account Manager at Stripe and ask them to gate all your accounts in for *Bring Your Own Token (BYOT)*.

If you need support, speak to your Solution Engineer, Customer Success Manager or our [Support Portal](https://primerapi.atlassian.net/servicedesk/customer/portal/11).

### Activate external network tokens with Nuvei

By default, Nuvei does not expose the Network Transaction ID after customer-initiated payments. This identifier is required in order to:

* Use Nuvei to process Primer network tokens for merchant-initiated payments
* Use another payment processor to perform merchant-initiated payments with cards that were originally saved through Nuvei

Before processing Primer network tokens with Nuvei, confirm that Nuvei returns the field `externalSchemeTransactionId` in the authorization response. If this field is empty, contact your Nuvei Account Manager and request that they enable the setting `ShouldReturnSchemeReference` on all your accounts.

If you need support, speak to your Solution Engineer, Customer Success Manager or our [Support Portal](https://primerapi.atlassian.net/servicedesk/customer/portal/11).