Network token implementation

To process payments with network tokens you can choose between either of the following options.

• The automatic provisioning of tokens for use with the orchestration platform.
• The standalone tokenization endpoints for using the network tokens directly with the PSPs.

​

Automatic provisioning of network tokens

Although network tokens are agnostic tokens, not every payment service or acquirer support the usage of network tokens that were provisioned outside of their own environment. When you use the system to orchestrate your payment, the routing behavior is optimized to take into consideration the limitations of the payment services you’re connecting to. A payment service that supports externally obtained data is generally considered an open loop connection, while one that doesn’t is considered closed loop. In the orchestration platform, network tokens can be supported across any open-loop payment services. You don’t have to perform any additional integrations to use network tokens besides storing the original card data (PAN) in the vault. You can follow the regular flow of card integrations, and the original card details are automatically swapped out with the network token when possible. Gr4vy only provisions and uses its own network tokens for stored cards. It provisions a network token when a transaction stores the card with store: true, or when a transaction uses a card that’s already stored. A transaction that sends card details without storing them is processed with the PAN. Gr4vy doesn’t match new card details against cards that are already stored. Each transaction that sends card details with store: true stores a new payment method, which gets its own network token. To reuse a network token, store the card once and charge later payments with the payment method id. You can use card fingerprints to find cards that are stored more than once.

​

Cryptograms

A cryptogram authenticates a single use of the network token. Gr4vy requests a cryptogram in the following cases:

• The transaction is the first one on a newly provisioned network token, including a merchant-initiated transaction (MIT). For example, when you move an existing billing sequence to Gr4vy, the first payment on each new token has a cryptogram.
• The transaction is a customer-initiated transaction (CIT), including the first payment of a recurring or installment series.
• The transaction is an MIT with payment_source set to card_on_file on a Mastercard card.
• The transaction is an MIT on a network token that the card network has replaced.

Other MITs, such as later payments in a recurring or installment series, use the network token without a cryptogram. Gr4vy requests a new cryptogram for each authorization attempt that needs one, and doesn’t store cryptograms. If Gr4vy can’t get a cryptogram, it skips the network token outcome and tries the next outcome in the routing rule. The token and cryptogram are provisioned as “on file” and therefore the buyer does not have to be present for the provisioning of either the token or the cryptogram. The usage of network tokens has been optimized by implementing scheme best practices regarding cryptogram usage, as well as the correct payment flagging towards the payment services. Using Flow, it is possible to choose the instrument (PAN or Network token) in your routing rules, allowing you to optimize your routing behavior. For best practices and advice on routing optimizations, please reach out to the support team. If Gr4vy can’t provision a network token, for example because the card isn’t eligible or the issuer declines tokenization, it skips the network token outcome without contacting the payment service and tries the next outcome. Gr4vy doesn’t switch to the PAN by itself, so add a PAN outcome after each network token outcome. See Instruments in the Flow guide.

​

Already stored cards

You don’t need to migrate cards that are already stored in the vault. Keep charging them with the payment method id.

• Don’t send store: true when you charge a stored payment method by id. The API rejects the request with a validation error, because the card is already stored.
• Gr4vy provisions the network token during the next transaction that Flow routes to a network token outcome. With synchronous provisioning, that same transaction is authorized with the new token and its cryptogram, even when it’s an MIT.
• Keep a PAN outcome after the network token outcome, so that cards that can’t be tokenized are still processed.
• To see which instrument processed a transaction, check its instrument_type, which is network_token or pan for card transactions.

​

Network token provisioning modes

Network token provisioning can be configured in two different modes: synchronous (default) and asynchronous. The mode you use depends on your performance requirements and tolerance for processing latency.

​

Synchronous provisioning

In synchronous mode, the network token is created before the first transaction is processed. This ensures the token is ready for immediate use:

• Initial Customer Initiated Transaction (CIT): The network token and cryptogram are created first, then the transaction is processed with the token and cryptogram.
• Subsequent CIT: The transaction is processed with the network token and cryptogram.
• Subsequent MIT: The transaction is processed with the network token only (cryptogram optional).

This is the default mode and ensures tokens are used from the start.

​

Asynchronous provisioning

In asynchronous mode, network token creation is deferred to a background process, allowing faster initial transaction processing. This mode is useful when network token/cryptogram generation latency would negatively impact the customer experience:

• Initial CIT: Gr4vy skips the network token outcome and creates the network token in the background. The transaction is processed with the PAN and CVV only if a PAN outcome follows in the routing rule.
• Subsequent CIT: The transaction is processed with the network token and cryptogram (which were created in the background).
• Subsequent MIT: The transaction is processed with the network token only.

This mode provides the best user experience for initial transactions at the cost of a slightly delayed token creation window. In this mode, Gr4vy skips the network token outcome for the transaction that triggers provisioning, so that transaction uses the next outcome in the routing rule. Add a PAN outcome after the network token outcome, as described in Instruments. Provisioning starts once that transaction succeeds:

• If the transaction is still in progress, for example while the buyer completes 3-D Secure, Gr4vy retries provisioning automatically for a limited time.
• If the transaction is declined or fails, Gr4vy doesn’t provision a network token.
• If the payment method already has a network token, Gr4vy doesn’t provision another one.

​

Standalone tokenization endpoints

The API allows you to provision network tokens and cryptograms for use in your own system. Please note that network tokens can be considered PCI sensitive data depending on your interpretation of PCI guidelines, and therefore these API’s are not enabled in production by default. You can use the network token endpoints to obtain network tokens and their cryptograms for use in your own system.