DocsGuidesSDKsAPI
Dashboard

Create a Network Token

The Evervault API enables you to tokenize cards with the Card Networks (e.g. Visa, Mastercard, American Express, etc.). This guide is designed to walk you through the procedure for creating a Network Token, which consists of 2 simple steps:

  1. Enrolling a merchant with the Card Networks to get started with tokenization
  2. Converting traditional card details into a Network Token

Enroll a Merchant with the Card Networks

Network Tokens are unique to individual merchants, meaning a token can only be utilized by the merchant for whom it was issued. To create Network Tokens, you first need to enroll a merchant with the Card Networks.

Use the Merchants API to onboard a merchant onto the Network Tokens API:

It can take up to 48 hours to enroll a merchant with each of the card networks. If you are still unable to provision network tokens after this period, please contact support@evervault.com

This step initiates the enrollment process with each supported card network. A merchant object is returned, including:

  • The merchant id which can be used to reference the enrolled merchant in subsequent token creation requests
  • The Network Tokens enrollment status for each card network
  • The Token Requestor Identifier (TRID) for each card network. Please note TRIDs may take up to two hours to provision.

To enable Network Tokens for American Express, please email your Evervault Merchant id and American Express Service Enablement (SE) number to support@evervault.com. Currently, enrolling a merchant with American Express for Network Tokens is a manual process.

Create a Network Token

After successfully enrolling the merchant, you can create Network Tokens via the Network Token API, making sure to include the ID of the previously enrolled merchant:

This API endpoint is designed to accept both Evervault encrypted values and plaintext values for the card number and the CVC. If card details have been obtained through UI Components or Relay, these values should be used as received.

The procedure initiates a token enrollment with the Card Network. During this stage, the Card Network conducts verification checks with the Card Issuer and subsequently issues a token.

Network Tokenization Process

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 Issuer is involved in the token issuance process, requests may experience high latency and take several seconds to process.

Upon successful tokenization, the Network Token becomes immediately available for use in processing transactions.

Error Handling

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

Error codeReasonResolution path
payments/network-tokens/ineligible-cardThe card is not eligible for tokenization. This may be due to the card issuer not supporting tokenization.A Network Token cannot be issued for that card, the underlying card number and expiry must be stored on file.
payments/network-tokens/invalid-cardThe provided card details did not pass verification checks. This may be due to an invalid card number, an incorrect CVC, or a discrepancy between the provided and actual card expiry date.If network tokenization occurs while the cardholder is still present, an error message should be displayed. This ensures immediate feedback for correction or verification.
payments/network-tokens/expired-cardThe card has expired.If network tokenization occurs while the cardholder is still present, an error message should be displayed. This ensures immediate feedback for correction or verification.
payments/network-tokens/declined-tokenizationTokenization for the given card was declined by the card issuer. This may be due to restrictions related to the card type, issuer policies, or the card's current status.A Network Token cannot be issued for that card, the underlying card number and expiry must be stored on file.
payments/network-tokens/unavailable-token-serviceThe Token Service Provider is unavailable.Retrying tokenization at a later stage may succeed.
payments/network-tokens/token-service-provider-provisioningThe Token Service Provider is provisioning.Retrying tokenization at a later stage may succeed.

Card Schemes Support

Evervault supports issuing Network Tokens for Visa, Mastercard and American Express cards. Discover and Diners Club support is coming soon.