Once an API endpoint has been enabled 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.
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"
        }
    ]
}

​
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.
  • 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.

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.

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 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 200
x-vault-forward-header-content-type: application/json
x-vault-forward-header-request-id: 123abc123abc

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