Forward vaulted cards to any PCI endpoint

Cloud Vault offers the capability to forward stored card information directly from the vault with third-party services. These external parties do not have to be directly integrated into our platform but they do need to be PCI-compliant to receive raw payment data.

POST /vault-forward
host: api.vault.gr4vy.app
content-type: application/json
x-vault-forward-url: https://example.com/endpoint
x-vault-forward-http-method: PUT
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"
        }
    ]
}

Typical examples would be external processing services, such as booking systems, reservation systems, order management systems, or any other systems that need card details to fulfill a business process. Other examples include loyalty and rewards programs that need full card numbers for card-linked offers.

​

Enabling Vault Forward Endpoints

To use Vault Forward the host name of the API you want to make an API request to needs to be explicitly enabled in an environment. There is a list of -approved hosts to which we can forward raw vaulted PCI data. To enable a host in an environment please put in a request with the support team.

​

Supported API endpoints

We currently support the following PCI endpoints in production environments. Each of these need to be explicitly enabled for your account.

• ACI Worldwide
• Adyen
• Amadeus
• Authorize.net
• Bank of Ireland Payment Acceptance
• Braintree
• Chase Orbital
• Checkout.com
• Cybersource
• dLocal
• EBANX
• Fiserv
• Nuvei
• Razorpay
• Sabre
• Stripe
• USAePay

​

Forwarding

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.

​

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 us
2. In the body of the request, any PCI data is replaced with a template tag, e.g. {{ CARD_NUMBER_1 }}
3. Some additional headers are sent to indicate the exact cards to forward PCI data for
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 headers include some additional data

POST /vault-forward
host: api.vault.gr4vy.app
content-type: application/json
x-vault-forward-url: https://example.com/endpoint
x-vault-forward-http-method: PUT
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-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.

Note: The value X references the index of the payment method in the list of x-vault-forward-payment-methods (starting with 1)

​

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.