top image

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 provisioned 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 provisioned, the network token can continue to be used for recurring payments and help to reduce churn.

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

Activate network tokenization for your Primer account

To activate, speak to your Customer Success Manager or raise a ticket on our JIRA Service Desk.  If you don’t have access, please contact your account administrator for assistance.

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.

How to provision network tokens

Once activated for your Primer account, we will automatically try to provision a network token on any vaulting event i.e. if you set vaultOnSuccess or vaultOn3DS to True in POST/client-session or POST/payments. The provisioning of the token takes place after the first payment.

This means that a network token is not provisioned and used for the first payment, but only provisioned 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.

If a network token was successfully provisioned, this will be reflected in the paymentMethod object where isNetworkTokenized will be set to True.

Create payments with your network tokens

You don’t need to do anything in order to use your network tokens when processing payments.

Once provisioned, the network token will be linked to the vaulted Primer token. Every time this vaulted token is used for subsequent payments, whether a customer-initiated payment (CIT) using a saved card or a merchant-initiated payment (MIT), we will always try to use the network token to process the payment.

Not all processors support external token requestors, so please speak to your Customer Success Manager or our JIRA Service Desk to understand which of your processors are eligible for processing with your network tokens.

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.

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

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

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

Provisioning network tokens for existing vaulted tokens

If you have existing vaulted tokens that were migrated to Primer or were stored in Primer’s vault before network tokenization was activated on your Primer account, you’ll want to provision network tokens for these.

When your vaulted token is used for a new payment, a network token is provisioned and then used for that payment. It will be stored against the vaulted token as outlined above and be available for subsequent payments as well.

Managing card updates

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