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.

When 3D Secure runs as part of Secure Fields or the mobile SDKs, the resulting authentication data is available as payload placeholders in a Vault Forward request. This lets you pass 3DS data alongside card details to downstream endpoints that require it. 3DS forwarding requires a checkout session — use x-vault-forward-checkout-session instead of x-vault-forward-payment-methods. See CVV & Secure Fields for how to set up the checkout session.

​
Placeholders

The following 3DS placeholders are available when 3DS authentication has run via a checkout session:
PlaceholderDescription
CARD_3DS_CAVV_1Cardholder Authentication Verification Value (CAVV) generated by the issuer.
CARD_3DS_ECI_1Electronic Commerce Indicator (ECI) — the security level of the transaction.
CARD_3DS_VERSION_13D Secure protocol version used (for example 2.1.0).
CARD_3DS_DIRECTORY_RESPONSE_1Status returned by the directory server (for example C for Challenge Required).
CARD_3DS_AUTHENTICATION_RESPONSE_1Final result of the authentication challenge (for example Y for Successful).
CARD_3DS_SERVER_TRANSACTION_ID_1UUID assigned to this transaction by the 3DS server.
CARD_3DS_DS_TRANSACTION_ID_1UUID assigned by the Directory Server (dsTransID).
CARD_3DS_SCHEME_1Card scheme used during 3DS (for example visa, mastercard).
All 3DS placeholders use _1 because you can only provide one checkout session per Vault Forward request.

​
Example

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: POST
x-vault-forward-header-authorization: Bearer 123
x-vault-forward-checkout-session: b77fef6d-c360-4b42-8f70-d884f4a6852a

{
    "card": {
        "number": "{{ CARD_NUMBER_1 }}",
        "expiry": "{{ CARD_EXPIRATION_DATE_1 }}",
        "cvv": "{{ CARD_SECURITY_CODE_1 }}"
    },
    "authentication": {
        "cavv": "{{ CARD_3DS_CAVV_1 }}",
        "eci": "{{ CARD_3DS_ECI_1 }}",
        "version": "{{ CARD_3DS_VERSION_1 }}"
    }
}

​
Conditional logic

3DS values may not always be present — for example, when authentication was not required or the transaction was frictionless. Use template logic to handle missing values gracefully.

​
If/else

{
    "authentication_response": {% if CARD_3DS_AUTHENTICATION_RESPONSE_1 %}"{{ CARD_3DS_AUTHENTICATION_RESPONSE_1 }}"{% else %}null{% endif %}
}

​
Or

The or operator outputs the first non-empty value: 
{
    "authentication_response": "{{ CARD_3DS_AUTHENTICATION_RESPONSE_1 or CARD_3DS_DIRECTORY_RESPONSE_1 }}",
    "scheme": "{{ CARD_3DS_SCHEME_1 or "unknown" }}"
}