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. 
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 }}"
    }
}

​
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: 
{
    "number": "{{ CARD_NETWORK_TOKEN_OR_EMPTY_STRING_1 or CARD_NUMBER_1 }}"
}
See or-logic for more details on the or operator. 
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 }}"
    }
}

​
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
HTTP 400

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