Network Tokenization

​

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.

​

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

​

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. Three strategies are available for creating network tokens: 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.

​

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

​

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:

   

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

​

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

​

PAN retries

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

​

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.