Network Tokens

Pricing
Sandbox support

Process payments securely without exposing actual card details

Network tokens replace sensitive card details (like the 16-digit card number, expiration date, and security code) with unique identifiers generated by card networks (e.g., Visa or Mastercard). The network token is then used to process payments without exposing actual card details. This adds a layer of security, and for merchants, it can result in higher authorization rates and lower fees.

Network tokens are designed to look like real card numbers, complete with a similar length and an expiry date, making them compatible with existing payment infrastructure. Since network tokens are simple identifiers and not real card numbers, merchants can store them without expanding their compliance obligations, such as those required by PCI standards.

When network tokens are created, they're assigned Token Domain Restriction Controls. These define the context (channel, merchant, wallet, etc.) and rules for how that network token can be used. This includes something called a Token Requestor ID (TRID), which is assigned to the party requesting the network token to be created (when you use Evervault, this is you, which means you own the TRID). If a network token is used outside of its domain restrictions, the transaction is blocked. This leads to significant fraud reduction.

How network tokens work

• Tokenization process

  The tokenization process starts when card details are collected. After card details are captured, the merchant submits them to the card network. The card network first authorizes the tokenization request with the issuer of the card. This authorization step ensures that the token is linked accurately to the card with the issuer's approval. After tokenization is authorized, the card network generates a unique token associated with the merchant. The generated network token is then returned to the merchant and stored for future use.
• Processing payments using network tokens

  During a transaction, a network token is sent to the payment gateway or card network instead of the original card details. After a transaction reaches the network, the token is replaced by the original card details and then processed as usual by the card issuer. As a result, the card details are only handled by the card issuer and the card network, minimizing the number of points where card data is exposed.

The benefits of network tokens

Using network tokens to process payments offers a number of benefits compared to using raw card details.

• Improved authorization rate

  Because tokens are issued and recognized by the card networks and are specific to the merchant or transaction type, they often carry additional data that can assist in the authorization process. This data helps issuers more accurately verify the legitimacy of a transaction. As a result, legitimate transactions are less likely to be declined due to suspicion of fraud, improving the overall experience for both customers and merchants.

• Automatic updates

  Unlike traditional card numbers (which remain static until manually updated by the cardholder in the event of expiry or reissuance), network tokens are dynamically updated. Card networks ensure that tokens reflect the most up-to-date card information, including automatic updates for expiration dates or replacement card numbers. This automatic renewal feature removes the common friction point of transactions being declined due to outdated card details. You can listen for network token updates to be notified when there's a change to the network token or the underlying card.

• Reduced fraud risk

  Since tokens replace sensitive card information with a unique identifier, the actual card details are never exposed during the transaction process. This minimizes fraud exposure. If a token is compromised or if it's used for a purchase outside what it's scoped for, it can be suspended or invalidated by the issuing network without affecting the underlying card, or the cardholder's ability to make purchases through other channels.

• Lower interchange fees

  One of the lesser-known yet financially impactful benefits of adopting network tokens is the potential reduction in interchange fees. Interchange fees are the costs that merchants pay to card networks for the processing of credit and debit card transactions. Some card networks even offer incentives and reduced interchange rates for transactions that use network tokens.

• Reduced PCI compliance scope

  By using tokens instead of storing, processing, or transmitting card numbers directly, merchants handle less sensitive data. This can decrease the complexity and costs associated with maintaining PCI DSS compliance, as the stringent security requirements become applicable to a smaller portion of the merchant's payment ecosystem.

• Simplified payment orchestration

  Since the tokenization and de-tokenization processes are handled by the card networks, merchants can process payments across different payment gateways without depending on each gateway's proprietary tokenization system. Merchants therefore need only a single tokenization integration to work with various payment processors and gateways, significantly simplifying their payment infrastructure.

Getting started

Evervault's APIs let you create and use network tokens without having to integrate directly with the card networks. You can create network tokens for Visa, Mastercard, and Amex cards.

Create a merchant

You can create a merchant from the payments section in the Evervault Dashboard or with the Merchants API. When you create a merchant, Evervault manages the enrollment process with each supported card network (something most other providers don't do for you). As a part of the process, for each card network:

• A merchant is enrolled in their system.
• A Token Requestor ID (TRID) is issued. This is what gives you ownership of the network token. This is an important differentiator because it means the network token isn't tied to a single payment gateway, PSP, orchestrator, etc.

After the process completes, you get an Evervault-specific merchant ID back (e.g., merchant_eead1d640d7c), along with other metadata. This merchant ID represents your merchant within Evervault. You need it to create network tokens in the next step, but it's not the same thing as a merchant ID associated with an acquiring bank or payment processor. It's an Evervault abstraction that allows us to tie the different systems together, so you don't have to directly manage a merchant for every card network.

Create a network token

After enrolling the merchant, use the API to create a network token API. Both card and merchant are required. You can optionally include the cvc with the card, which increases the chances of successfully provisioning the token.

1fetch("https://api.evervault.com/payments/network-tokens", {
2  method: "POST",
3  headers: {
4    "Content-Type": "application/json",
5    Authorization: "Basic " + btoa("<app_id>:<api_key>"),
6  },
7  body: JSON.stringify({
8    card: {
9      number: "4242424242424242",
10      expiry: {
11        month: "09",
12        year: "29",
13      },
14      cvc: "123",
15    },
16    merchant: "merchant_ddsaJsda9d86",
17  }),
18});

Network tokens are issued synchronously. This ensures that the response to the creation request includes all details of the enrolled token, such as the token number and its expiration date. Since the card's issuer is involved in the token issuance process, requests may experience high latency and take several seconds to process. After tokenization, the network token becomes immediately available for use in processing transactions.

Process payments with network tokens

Network tokens can be used as payment credentials to process charges across several payment gateways for Customer Initiated Transactions (CITs) and Merchant Initiated Transactions (MITs).

To process an MIT, the only requirement is the token number and expiry date, both of which can be found in the Network Token object. CITs require a token cryptogram. This serves as a substitute for the traditional CVC code found on the back of a card. The token cryptogram is designed for in-memory use only, and must be disposed of after each payment attempt, regardless of whether the attempt succeeds or fails. Token cryptograms can be generated using the Network Token Cryptogram API.

1const response = await fetch("https://api.evervault.com/payments/network-tokens/network_token_123456789098/cryptograms", {
2  method: "POST",
3  headers: {
4    "Content-Type": "application/json",
5    Authorization: "Basic " + btoa("<app_id>:<api_key>"),
6  },
7});
8
9const { cryptogram } = await response.json();
10
11console.log(cryptogram);
12// NTk0ZjM5M2QyNDMwNDE1MjkzMjg1ZTg5Y2NiZjdmNjE=

Network token updates

You can set up the Network Tokens API to notify you when there's a change to a token or its underlying card. These updates cover token status changes and let you know when a card is reissued. The webhook doesn't return the card's full number (the PAN), so it's not a replacement for Card Account Updater or for implementing a PAN fallback.

To receive network token updates, create a webhook endpoint and listen for the payments.network-token.updated event. You can simulate an update in Sandbox mode to test the process. The event covers two types of changes.

• Token status changes: these reflect updates to the token itself (active, expired, etc.). These are reflected in the status field.
• Underlying card changes: the issuer has reissued the physical card. The network token itself doesn't change when this happens. The last four digits of the new number, as well as the new expiry, are returned in the event. If updateType is new-card-expiry-and-last-four, you know a new card was issued.

Retrieve card art

You can retrieve art for cards issued by Visa and Mastercard. This is a digital version of the art on the front of the card. It's often used during the checkout process to build trust with customers, or as a part of account management to create more personalized experiences for saved cards.

Error handling

When an issue occurs during the tokenization process, the API generates an error message with a distinct code. This feature enables the design of customized error handling strategies, streamlining the resolution of these issues.

Fallback to PANs

If a transaction is declined using a network token, you can retry the payment if you have access to the original PAN. If you use Evervault to collect card information, you can store the encrypted PAN and retry the payment with that.

If you're setting up PAN fallbacks, use Card Account Updater or Real-time Account Updater to keep PANs fresh. Network token updates only return the last four digits and the expiry, so they can't be used to implement a fallback strategy.

Testing your implementation

You can leverage Sandbox apps to test the full merchant enrollment and token creation process without affecting live data. When you're ready to use network tokens in production, contact our support team at support@evervault.com.

Test cards

In Sandbox mode, you can use specific test cards to simulate various real-life scenarios. These cards can be used in conjunction with any valid expiry date or CVC.