Skip to main content
Vault Forward supports forwarding network tokens 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.
The value X references the index of the payment method in the list of x-vault-forward-payment-methods (starting with 1).

​
Request

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

​
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:
See or-logic for more details on the or operator.

​
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.
Network token provisioning failure