> ## 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.

# Forward network tokens via Vault Forward

Vault Forward supports forwarding [network tokens](/guides/features/network-tokens/overview) and
their associated cryptograms to third-party endpoints. If a network token has not yet been
provisioned for a payment method, it is automatically provisioned before forwarding.

Network token placeholders work with both `x-vault-forward-payment-methods` and
`x-vault-forward-checkout-session`. When using a checkout session, it must reference a stored
payment method (not inline card data). The CVV collected in that session is used to provision
the network token.

Cryptograms are generated for network token requests. To control whether a cryptogram is
generated as a customer-initiated transaction (`false`) or a merchant-initiated transaction
(`true`, the default), set the `x-vault-forward-merchant-initiated` header.

## Placeholders

The following placeholders are available for forwarding network token data.

* `CARD_NETWORK_TOKEN_X`: The network token for a card. Auto-provisioned if not yet available.
* `CARD_NETWORK_TOKEN_EXPIRATION_DATE_X`: The network token's expiration date.
* `CARD_NETWORK_TOKEN_EXPIRATION_DATE_M_X`: The expiration month as a non-zero-padded number. Example: `1, 2, ..., 12`.
* `CARD_NETWORK_TOKEN_EXPIRATION_DATE_MM_X`: The expiration month as a zero-padded number. Example: `01, 02, ..., 12`.
* `CARD_NETWORK_TOKEN_EXPIRATION_DATE_YY_X`: The expiration year without century. Example: `00, 01, ..., 99`.
* `CARD_NETWORK_TOKEN_EXPIRATION_DATE_YYYY_X`: The expiration year with century. Example: `2025, 2026`.
* `CARD_NETWORK_TOKEN_EXPIRATION_DATE_MMYY_X`: The expiration month and year combined. Example: `1225`.
* `CARD_CRYPTOGRAM_X`: The cryptogram for the network token. A new cryptogram is generated for each request.

<Note>
  The value `X` references the index of the payment method in the list of `x-vault-forward-payment-methods` (starting with 1).
</Note>

## Request

Use these placeholders in the request body the same way as other card data placeholders.

<CodeGroup>
  ```http Original request theme={"system"}
  POST /vault-forward
  host: api.acme.gr4vy.app
  content-type: application/json
  x-vault-forward-url: https://example.com/endpoint
  x-vault-forward-http-method: POST
  x-vault-forward-header-authorization: Bearer 123
  x-vault-forward-payment-methods: b77fef6d-c360-4b42-8f70-d884f4a6852a
  x-vault-forward-timeout: 10

  {
      "card": {
          "number": "{{ CARD_NETWORK_TOKEN_1 }}",
          "expiry": "{{ CARD_NETWORK_TOKEN_EXPIRATION_DATE_MM_1 }}/{{ CARD_NETWORK_TOKEN_EXPIRATION_DATE_YY_1 }}",
          "cryptogram": "{{ CARD_CRYPTOGRAM_1 }}"
      }
  }
  ```

  ```http Forwarded request theme={"system"}
  POST /endpoint
  host: example.com
  content-type: application/json
  authorization: Bearer 123

  {
      "card": {
          "number": "4895370015293468",
          "expiry": "12/25",
          "cryptogram": "AgAAAAAAAAAAAAAQEAAAAAAAAAA="
      }
  }
  ```
</CodeGroup>

## Fallback placeholders

If you use a standard network token placeholder and provisioning fails, the request returns a `400`
error. Each placeholder above has an `_OR_EMPTY_STRING` variant that returns an empty string
(`""`) instead of failing. Use these placeholders when the downstream endpoint accepts—but does not
require—a network token.

* `CARD_NETWORK_TOKEN_OR_EMPTY_STRING_X`
* `CARD_NETWORK_TOKEN_EXPIRATION_DATE_OR_EMPTY_STRING_X`
* `CARD_NETWORK_TOKEN_EXPIRATION_DATE_M_OR_EMPTY_STRING_X`
* `CARD_NETWORK_TOKEN_EXPIRATION_DATE_MM_OR_EMPTY_STRING_X`
* `CARD_NETWORK_TOKEN_EXPIRATION_DATE_YY_OR_EMPTY_STRING_X`
* `CARD_NETWORK_TOKEN_EXPIRATION_DATE_YYYY_OR_EMPTY_STRING_X`
* `CARD_NETWORK_TOKEN_EXPIRATION_DATE_MMYY_OR_EMPTY_STRING_X`
* `CARD_CRYPTOGRAM_OR_EMPTY_STRING_X`

The `_OR_EMPTY_STRING` variants can also be combined with the `or` template operator to fall back
to a specific value, such as the raw PAN:

```json theme={"system"}
{
    "number": "{{ CARD_NETWORK_TOKEN_OR_EMPTY_STRING_1 or CARD_NUMBER_1 }}"
}
```

See [or-logic](./3ds#or) for more details on the `or` operator.

<CodeGroup>
  ```http With empty string fallback theme={"system"}
  POST /vault-forward
  host: api.acme.gr4vy.app
  content-type: application/json
  x-vault-forward-url: https://example.com/endpoint
  x-vault-forward-http-method: POST
  x-vault-forward-header-authorization: Bearer 123
  x-vault-forward-payment-methods: b77fef6d-c360-4b42-8f70-d884f4a6852a

  {
      "card": {
          "number": "{{ CARD_NETWORK_TOKEN_OR_EMPTY_STRING_1 }}",
          "expiry": "{{ CARD_NETWORK_TOKEN_EXPIRATION_DATE_MM_OR_EMPTY_STRING_1 }}/{{ CARD_NETWORK_TOKEN_EXPIRATION_DATE_YY_OR_EMPTY_STRING_1 }}",
          "cryptogram": "{{ CARD_CRYPTOGRAM_OR_EMPTY_STRING_1 }}"
      }
  }
  ```
</CodeGroup>

## Errors

If you use a standard network token placeholder that does not include the
`_OR_EMPTY_STRING` fallback and the network token cannot be provisioned, the API returns a `400`
error before the request is forwarded to the third-party endpoint.

```json Network token provisioning failure theme={"system"}
HTTP 400

{
  "type": "error",
  "code": "network_token_provisioning_failed",
  "status": 400,
  "message": "Could not provision a network token for the provided payment method",
  "details": []
}
```