Network Tokenization Overview

​
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.
Learn more about network tokens by reading this blog post on how to optimize payments using network tokenization.

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

Network Tokenization Flow

Primer currently only supports network tokens for Visa and Mastercard.
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. 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.
This can take up to 48 hours to become active due to back-office operations on the card network side.

​
Create network tokens

Once network tokenization is fully activated for your account, go to the Network Tokenization section of your Dashboard to start creating network tokens.

Network Token Creation Configuration

Three strategies are available for creating network tokens:
StrategyDescriptionRecommendation
for newly-vaulted cardsAttempts 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 cardsAttempts 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 or
  • 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.
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.

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

​
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 of your Dashboard to activate and configure when network tokens should be used.

Network Token Processing Configuration

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 VolumeDescriptionWhen 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.
⚠️ 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.
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 to understand which of your processors are able to process network tokens created by Primer.

​
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 and the webhook body.
    This is only available on API and Webhook version 2.2 or greater.
    See below for an example:
    JSON
    {
  "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:

    Payment Timeline Example

  3. The payment appears when you set the filter Card Token Type Used to NETWORK_TOKEN.
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.

​
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

Read the detailed guide on how to test network tokens on Primer.

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