Skip to main content

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.

It is possible to use a Vault Forward directly with a checkout session and Secure Fields. This is especially useful when you don’t want to create a payment method, or when you want to collect a CVV for a payment method.

​
Forward CVV for a stored card

To forward a security code (CVV) for a stored card, create a checkout session and use it with Secure Fields to collect the security code. More information on this can be found in the Secure Fields guide on this topic. Once you’ve collected the security code, you can forward all the card details using the checkout session as described below.

​
Forward a Checkout Session

To forward a checkout session, set the x-vault-forward-checkout-session instead of the x-vault-forward-payment-methods 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-checkout-session: b77fef6d-c360-4b42-8f70-d884f4a6852a
x-vault-forward-timeout: 10

{
    "cards": [
        {
            "number": "{{ CARD_NUMBER_1 }}",
            "expiry": "{{ CARD_EXPIRATION_DATE_1 }}",
            "cvv": "{{ CARD_SECURITY_CODE_1 }}"
        }
    ]
}

​
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-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_1: The number for a card to forward.
  • CARD_EXPIRATION_DATE_1: The expiration date for a card to forward.
  • CARD_EXPIRATION_DATE_M_1: The expiration date’s month as a non-zero-padded decimal number. Example: 1, 2, ..., 12.
  • CARD_EXPIRATION_DATE_MM_1: The expiration date’s month as zero-padded decimal number. Example: 01, 02, ..., 12.
  • CARD_EXPIRATION_DATE_YY_1: The expiration date’s year without century as a zero-padded decimal number. Example: 00, 01, ..., 99.
  • CARD_EXPIRATION_DATE_YYYY_1: The expiration date’s year with century as a decimal number. Example: 2013, 2014, ..., 9998, 9999.
  • CARD_SECURITY_CODE_1: The security code for the card. This can only be forwarded when using Secure Fields and checkout sessions.
Additionally, the following 3DS data can be forwarded when 3DS runs as part of Secure Fields or the mobile SDKs.
  • CARD_3DS_CAVV_1: The Cardholder Authentication Verification Value (CAVV) generated by the issuer to prove authentication occurred.
  • CARD_3DS_ECI_1: The Electronic Commerce Indicator (ECI), a flag indicating the security level of the transaction.
  • CARD_3DS_VERSION_1: The version number of the 3D Secure protocol used for the transaction (for example 2.1.0).
  • CARD_3DS_DIRECTORY_RESPONSE_1: The status returned by the directory server. For example C (Challenge Required).
  • CARD_3DS_AUTHENTICATION_RESPONSE_1: The final result of the authentication challenge. For example Y (Authentication Successful).
  • CARD_3DS_SERVER_TRANSACTION_ID_1: The universally unique identifier (UUID) assigned to this transaction by the 3DS server.
  • CARD_3DS_DS_TRANSACTION_ID_1: The universally unique identifier (UUID) assigned to this transaction by the Directory Server (dsTransID).
  • CARD_3DS_SCHEME_1: The specific card scheme (for example visa, mastercard) used during the 3DS process.
Please note you can only ever provide one checkout session to vault forward, and therefore all payload placeholders include _1.

​
Conditional logic

​
If/else-logic

The if/else template statement applies simple conditional logic to your template. This is particularly useful when you need to handle empty values, such as setting them to null within a JSON template. 
{
    "authentication_response": {% if CARD_3DS_AUTHENTICATION_RESPONSE_1 %}"{{CARD_3DS_AUTHENTICATION_RESPONSE_1}}" {% else %} null {% endif %} }
}

​
Or-logic

The or template statement outputs one value, or falls back to another if the first one is empty. 
{
    "authentication_response": "{{CARD_3DS_AUTHENTICATION_RESPONSE_1 or CARD_3DS_DIRECTORY_RESPONSE_1}}",
    "scheme": "{{CARD_3DS_SCHEME_1 or "No scheme"}}"
}
This is useful when prioritizing a specific value but providing a default or alternative if the primary value is missing.