> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mattildapayments.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](./enable) any vaulted data can be forwarded
to that endpoint using the Vault Forward API. To forward card data, you need to have some
card data stored in our vault. You can use any of our SDK, e-commerce plugins, and even our
API to store the card data in our Cloud Vault. Once stored, you can forward any stored card
(payment method) in our vault to your enabled API endpoint.
## Request
Vault Forward acts as a proxy to the API endpoint of your third-party service. You make the same request to
our API as you'd normally make to this endpoint with some minor changes.
1. Instead of sending the request to the endpoint, you send the data to our system.
2. In the body of the request, any PCI data is replaced with a template value, e.g. `{{ CARD_NUMBER_1 }}`.
3. Additional headers are required to specify for what cards to forward PCI data.
4. Any headers that need to be forwarded to the third-party endpoint will need to be changed to include the `x-vault-forward-header-` prefix.
5. The response, including the headers, will be returned to you for processing.
```http Original request theme={"dark"}
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={"dark"}
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"
}
]
}
```
### Headers
Vault Forward uses request headers to select the payment method to forward data for,
what endpoint to send the request to, and any additional other settings.
* `x-vault-forward-url` - the HTTPS URL to forward the request to. Its host must have been enabled if the request is in a production environment.
* `x-vault-forward-http-method` - the HTTP method to use when forwarding the request. The accepted values are `POST`, `PUT` and `PATCH`.
* `x-vault-forward-payment-methods` - a comma-separated list of IDs for **payment method**. At least 1 ID must be provided and they cannot be duplicates. Only card payment methods are accepted.
* `x-vault-forward-checkout-session` - the ID for a **checkout session**. At most 1 ID can be provided and if set `x-vault-forward-payment-methods` can be omitted. This can be used to [forward the security code of a card](./checkout-sessions).
* `x-vault-forward-header-{HEADER_NAME}` - each header value to forward in the request. For example, to forward an `authorization` header to the endpoints, it should be set as `x-vault-forward-header-authorization`.
* `x-vault-forward-timeout` (optional) - a timeout for the forwarded request. The default is 30 seconds.
### Payload
The request payload should contain the body which you want to forward to the third-party endpoint. It could be constructed in any format, for example JSON, or XML.
To forward vaulted data there are a set of placeholders that can be used as placeholders, using the `{{ PLACEHOLDER }}` syntax.
* `CARD_NUMBER_X`: The number for a card to forward.
* `CARD_EXPIRATION_DATE_X`: The expiration date for a card to forward.
* `CARD_EXPIRATION_DATE_M_X`: The expiration date's month as a non-zero-padded decimal number. Example: 1, 2, ..., 12.
* `CARD_EXPIRATION_DATE_MM_X`: The expiration date's month as zero-padded decimal number. Example: 01, 02, ..., 12.
* `CARD_EXPIRATION_DATE_YY_X`: The expiration date's year without century as a zero-padded decimal number. Example: 00, 01, ..., 99.
* `CARD_EXPIRATION_DATE_YYYY_X`: The expiration date's year with century as a decimal number. Example: 2013, 2014, ..., 9998, 9999.
* `CARD_SECURITY_CODE_X`: The security code for the card. This can only be forwarded when using [Secure Fields and checkout sessions](./checkout-sessions).
Note: The value `X` references the index of the payment method in the list of `x-vault-forward-payment-methods` (starting with 1)
## Authentication
To handle authentication to the downstream API, you will need to pass your own API keys and credentials through the body
or headers. For example, when using a bearer token, it needs to be passed in the Vault Forward request as a `x-vault-forward-header-authorization` header.
```http theme={"dark"}
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
...
```
In some situations, passing through the authentication is not technically possible.
* The downstream service requires the request to be signed
* The downstream service requires two-way SSL / mutual TLS authentication
* The downstream service requires the entire payload to be encrypted
For these services, we have added support for [advanced authentication](./authentication) to Vault Forward.
## Response
The response will contain the raw data received from the third-party endpoint and some additional information in the headers.
### HTTP status code
If there is some validation error before the request is sent to the third-party endpoint, the status code of
the `POST /vault-forward` API will be set to 4XX. In all other cases a `200` status will be returned
### Headers
When we receive a response from the third-party endpoint we will treat the headers in that response as follows.
* `content-type` - the content type of the response. This is transparently forwarded as received without any changes.
* `x-vault-forward-http-status-code` (optional) - the HTTP status code received from the third-party endpoint.
* `x-vault-forward-header-{HEADER_NAME}` - each header value received from the third-party endpoint, except for `content-type` which is returned as-is.
For example, if the API responded with `x-frame-options: SAMEORIGIN`, then our API will return a `x-vault-forward-header-x-frame-options: SAMEORIGIN` header.
* `x-vault-forward-error` (optional) - the error string of the request error. This is returned if we could not receive a response from the third party system, i.e. in case of a timeout or network error.
### Payload
The raw payload as received from the third party is returned as-is. Unless we did not receive a response from the third party, in
which case the payload will be empty.
### Example
```http Successful forward theme={"dark"}
HTTP 200
x-vault-forward-header-content-type: application/json
x-vault-forward-header-request-id: 123abc123abc
{
"status": "OK",
"transactionId": "123456789"
}
```
```json Invalid forward request theme={"dark"}
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={"dark"}
HTTP 200
x-vault-forward-http-status-code: 401
x-vault-forward-header-content-type: application/json
x-vault-forward-header-request-id: 123abc123abc
{
"status": "FAILURE",
"error": "Invalid authentication"
}
```