Vault Forward card data to API endpoint

Once an API endpoint has been enabled, any vaulted card data can be forwarded to it using the Vault Forward API. The card must already be stored in the vault as a payment method — see Tokenize a card for how to store one.

Request

Vault Forward acts as a proxy to your third-party endpoint. You send the request to the Gr4vy API instead of directly to the downstream service, with a few adjustments:

Send the request to POST /vault-forward instead of the downstream URL.
Replace any PCI data in the body with template placeholders, for example {{ CARD_NUMBER_1 }}.
Add control headers to specify which cards to forward and where to send the request.
Prefix any downstream headers with x-vault-forward-header-.

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: PUT
x-vault-forward-header-authorization: Bearer 123
x-vault-forward-payment-methods: b77fef6d-c360-4b42-8f70-d884f4a6852a,1ca3fe71-7782-4f00-9b0e-c250b365bef1
x-vault-forward-timeout: 10

{
    "cards": [
        {
            "number": "{{ CARD_NUMBER_1 }}",
            "expiry": "{{ CARD_EXPIRATION_DATE_1 }}",
            "cvv": "123"
        },
        {
            "number": "{{ CARD_NUMBER_2 }}",
            "expiry": "{{ CARD_EXPIRATION_DATE_2 }}",
            "cvv": "234"
        }
    ]
}

PUT /endpoint
host: example.com
content-type: application/json
authorization: Bearer 123

{
    "cards": [
        {
            "number": "4111111111111111",
            "expiry": "12/25",
            "cvv": "123"
        },
        {
            "number": "4242424242424242",
            "expiry": "03/26",
            "cvv": "234"
        }
    ]
}

Request headers

Header	Required	Description
`x-vault-forward-url`	Yes	HTTPS URL to forward the request to. The host must be enabled in production.
`x-vault-forward-http-method`	Yes	HTTP method to use: `POST`, `PUT`, or `PATCH`.
`x-vault-forward-payment-methods`	Yes*	Comma-separated list of payment method IDs. At least 1, no duplicates. Only card payment methods are accepted.
`x-vault-forward-checkout-session`	Yes*	Checkout session ID. If set, `x-vault-forward-payment-methods` can be omitted. Use to forward a CVV.
`x-vault-forward-header-{HEADER_NAME}`	No	A header to forward to the downstream endpoint. For example, set `x-vault-forward-header-authorization` to forward an `authorization` header.
`x-vault-forward-timeout`	No	Timeout for the forwarded request in seconds. Defaults to 30.

*Provide either x-vault-forward-payment-methods or x-vault-forward-checkout-session — at least one is required.

Payload placeholders

Replace PCI data in the request body with placeholders using {{ PLACEHOLDER }} syntax. The X suffix is the 1-based index of the payment method in the x-vault-forward-payment-methods list.

Placeholder	Description
`CARD_NUMBER_X`	The card number (PAN).
`CARD_EXPIRATION_DATE_X`	Expiration date in `MM/YY` format.
`CARD_EXPIRATION_DATE_M_X`	Expiration month, non-zero-padded (`1`–`12`).
`CARD_EXPIRATION_DATE_MM_X`	Expiration month, zero-padded (`01`–`12`).
`CARD_EXPIRATION_DATE_YY_X`	Expiration year without century (`00`–`99`).
`CARD_EXPIRATION_DATE_YYYY_X`	Expiration year with century (for example `2025`).
`CARD_SECURITY_CODE_X`	Security code (CVV). Only available via Secure Fields and checkout sessions.

Authentication

Pass your downstream API credentials through headers using the x-vault-forward-header- prefix:

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: PUT
x-vault-forward-header-authorization: Bearer 123
...

For services that require request signing, mutual TLS, or payload encryption — where passing credentials through headers is not possible — see Advanced authentication.

Response

HTTP status code

Any validation error before forwarding returns a 4XX status. In all other cases — including when the downstream service returns an error — the status is 200.

Response headers

Header	Description
`content-type`	Content type of the downstream response, forwarded as-is.
`x-vault-forward-http-status-code`	HTTP status code returned by the downstream endpoint.
`x-vault-forward-header-{HEADER_NAME}`	Response headers from the downstream endpoint (except `content-type`). For example, `x-vault-forward-header-x-frame-options`.
`x-vault-forward-error`	Error string if no response was received, for example on timeout or network failure.

Payload

The raw downstream response body is returned as-is. Empty if no response was received.

Examples

HTTP 200
content-type: application/json
x-vault-forward-header-request-id: 123abc123abc

{
    "status": "OK",
    "transactionId": "123456789"
}

HTTP 400

{
  "type": "error", 
  "code": "bad_request",
  "status": 400,
  "message": "Request failed validation",
  "details": [
    {
      "type": "invalid",
      "pointer": "x-vault-forward-http-method",
      "message": "x-vault-forward-http-method is not a valid value (PUT/POST/PATCH)",
      "location": "header"
    }
  ]
}

HTTP 200
x-vault-forward-http-status-code: 401
content-type: application/json
x-vault-forward-header-request-id: 123abc123abc

{
    "status": "FAILURE",
    "error": "Invalid authentication"
}

Explore further

CVV & Secure Fields

Forward a security code collected via Secure Fields or a checkout session

3DS forwarding

Forward 3DS authentication data alongside card details

Network token forwarding

Forward network tokens and cryptograms to third-party endpoints

Advanced authentication

Configure request signing, mutual TLS, or payload encryption

Enable an endpoint

Allow a specific host to receive forwarded PCI data in production

Get started

Integration guides

Best Practices

Resources

Features

Other

Vault Forward card data to API endpoint

Request

Request headers

Payload placeholders

Authentication

Response

HTTP status code

Response headers

Payload

Examples

Explore further

CVV & Secure Fields

3DS forwarding

Network token forwarding

Advanced authentication

Enable an endpoint

​Request

​Request headers

​Payload placeholders

​Authentication

​Response

​HTTP status code

​Response headers

​Payload

​Examples

​Explore further

CVV & Secure Fields

3DS forwarding

Network token forwarding

Advanced authentication

Enable an endpoint

Request

Request headers

Payload placeholders

Authentication

Response

HTTP status code

Response headers

Payload

Examples

Explore further