> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gr4vy.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Network token implementation

> How to use scheme tokens with or without payment orchestration

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.

<Info>
  Before you start processing payments with network tokens, make sure you have
  enabled processing with network tokens. Please contact the support team to get set up.
</Info>

## 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](/guides/features/cards/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](/guides/dashboard/flow/card-transactions#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](/guides/dashboard/flow/card-transactions#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.

<Info>
  Asynchronous network tokenization is an opt-in feature that is currently configured per merchant by the support team. Contact support to enable asynchronous provisioning for your account if you require faster initial transaction processing.
</Info>

## 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][endpoints] to obtain network tokens and their cryptograms
for use in your own system.

<Warning>
  Network token provisioning via the API is not enabled by default in production.
  Please contact support for further guidance.
</Warning>

[endpoints]: /reference/network-tokens/


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.