Create a Network Token

The Evervault API enables you to tokenize cards with the Card Networks (e.g. Visa and Mastercard). 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:

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 enrollment of a merchant with the networks can take up to 48 hours to complete. During this period, the creation of Network Tokens is not possible until the merchant has successfully enrolled. To stay updated on the enrollment status, you have the option to subscribe to the payments.merchant.updated Webhook Event, which will notify you once a merchant is enrolled. Alternatively, you can verify the enrollment status for each card network by retrieving the merchant's details through the API.

Create a Network Token

After successfully enrolling the merchant, you can generate 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 generated token.

Network Tokenization Process

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.

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.

Card Schemes Support

Currently, Evervault supports issuing Network Tokens for Visa and Mastercard cards. Support for American Express is coming soon. To inquire about support for other card schemes, please contact support@evervault.com.