Skip to main content
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:
  1. Send the request to POST /vault-forward instead of the downstream URL.
  2. Replace any PCI data in the body with template placeholders, for example {{ CARD_NUMBER_1 }}.
  3. Add control headers to specify which cards to forward and where to send the request.
  4. 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"
        }
    ]
}

​
Request headers

HeaderRequiredDescription
x-vault-forward-urlYesHTTPS URL to forward the request to. The host must be enabled in production.
x-vault-forward-http-methodYesHTTP method to use: POST, PUT, or PATCH.
x-vault-forward-payment-methodsYes*Comma-separated list of payment method IDs. At least 1, no duplicates. Only card payment methods are accepted.
x-vault-forward-checkout-sessionYes*Checkout session ID. If set, x-vault-forward-payment-methods can be omitted. Use to forward a CVV.
x-vault-forward-header-{HEADER_NAME}NoA header to forward to the downstream endpoint. For example, set x-vault-forward-header-authorization to forward an authorization header.
x-vault-forward-timeoutNoTimeout 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.
PlaceholderDescription
CARD_NUMBER_XThe card number (PAN).
CARD_EXPIRATION_DATE_XExpiration date in MM/YY format.
CARD_EXPIRATION_DATE_M_XExpiration month, non-zero-padded (1–12).
CARD_EXPIRATION_DATE_MM_XExpiration month, zero-padded (01–12).
CARD_EXPIRATION_DATE_YY_XExpiration year without century (00–99).
CARD_EXPIRATION_DATE_YYYY_XExpiration year with century (for example 2025).
CARD_SECURITY_CODE_XSecurity 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

HeaderDescription
content-typeContent type of the downstream response, forwarded as-is.
x-vault-forward-http-status-codeHTTP 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-errorError 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"
}

​
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