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

# Vault Forward card data to API endpoint

Once an API endpoint has been [enabled](/guides/features/vault-forwarding/enable), 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](./tokenize) 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-`.

<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: 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"
          }
      ]
  }
  ```

  ```http Forwarded request theme={"system"}
  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"
          }
      ]
  }
  ```
</CodeGroup>

### Request headers

| Header                                 | Required | Description                                                                                                                                                 |
| -------------------------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `x-vault-forward-url`                  | Yes      | HTTPS URL to forward the request to. The host must be [enabled](/guides/features/vault-forwarding/enable) 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](/guides/features/vault-forwarding/checkout-sessions). |
| `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](/guides/features/vault-forwarding/checkout-sessions). |

## Authentication

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

```http 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: 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](/guides/features/vault-forwarding/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

<CodeGroup>
  ```http Successful forward theme={"system"}
  HTTP 200
  content-type: application/json
  x-vault-forward-header-request-id: 123abc123abc

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

  ```json Invalid forward request theme={"system"}
  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 Successful forward, error response theme={"system"}
  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"
  }
  ```
</CodeGroup>

## Explore further

<CardGroup cols={2}>
  <Card title="CVV & Secure Fields" icon="lock" href="/guides/features/vault-forwarding/checkout-sessions">
    Forward a security code collected via Secure Fields or a checkout session
  </Card>

  <Card title="3DS forwarding" icon="shield-check" href="/guides/features/vault-forwarding/3ds">
    Forward 3DS authentication data alongside card details
  </Card>

  <Card title="Network token forwarding" icon="circle-nodes" href="/guides/features/vault-forwarding/network-tokens">
    Forward network tokens and cryptograms to third-party endpoints
  </Card>

  <Card title="Advanced authentication" icon="key" href="/guides/features/vault-forwarding/authentication">
    Configure request signing, mutual TLS, or payload encryption
  </Card>

  <Card title="Enable an endpoint" icon="gear" href="/guides/features/vault-forwarding/enable">
    Allow a specific host to receive forwarded PCI data in production
  </Card>
</CardGroup>