Most strings evaluate to themselves, but strings beginning with $
perform either variable lookups or template lookups.
Global variable lookups are of the form $variable_name
. When they are evaluated they return the result of looking up the named variable. Global variables may come from a couple
different sources (in increasing order of precedence): the Forward API itself, anything specified in data
of the forwarding request, and anything specified in the
sensitive_data
section of the forwarding request. If the same variable name appears in different sources, the variable from the source with the highest level of precedence will be chosen.
Template lookups are of the form $/section/nested_section/etc
Template lookups allow transformations to reference part of the partially constructed request (the template). When
template lookups are evaluated the relevant section of the template is fetched, serialized accoring to the rules in request_format
, and returned as a string.
There are also local variable lookups, which are of the form $/var/name
. They are references to a special section of the template (var
) which is not serialized and which may not be provided by either the config or the forwarding request.
To define a local variable, write to the var
section just as you would any other part of the template:
{"path": "/var/aes-nonce", "value": ["aes-gcm-nonce"]}
To use that variable, just refer to it by its path:
{"path": "/body/aes-nonce", "value": ["hex", "$/var/aes-nonce"]}
When using an Apple Pay card, you do not have access to the underlying card information. The card number will be the DPAN, and the expiration date will correspond to the DPAN, not the underlying card.
Variable suffixes
When forwarding multiple payment methods, variables for each payment method are bound based on their token's position in the array of payment_method_tokens
, 1-indexed. Unsuffixed variables reference the first payment method: $variable
and $variable_1
have the same value.
When forwarding both a payment method and a payment method nonce, the nonce's variables are _2
suffixed.
Available Global Variables
$card_type
The card network, e.g. "Visa" or "Apple Pay - American Express". Possible Values:
- "American Express"
- "Android Pay Card - American Express"
- "Android Pay Card - Discover"
- "Android Pay Card - MasterCard"
- "Android Pay Card - Visa"
- "Apple Pay - American Express"
- "Apple Pay - Discover"
- "Apple Pay - MasterCard"
- "Apple Pay - Visa"
- "Discover"
- "JCB"
- "Maestro"
- "MasterCard"
- "Solo"
- "Switch"
- "UK Maestro"
- "UnionPay"
- "Visa"
$eci_flag
The value of the electronic commerce indicator (ECI) flag, which indicates the outcome of the 3DS authentication.
Accepted values for Mastercard:
00
= Failed or not attempted01
= Attempted02
= Success
Accepted values for all other card brands:
07
= Failed or not attempted06
= Attempted05
= Success
$cavv
Cardholder authentication verification value or CAVV. The main
encrypted message issuers and card networks use to verify authentication
has occurred. Mastercard uses an AVV message and American Express uses an
AEVV message, each of which should also be passed in the cavv
parameter.
$ds_transaction_id
Transaction identifier resulting from 3D Secure 2 authentication. This field must be supplied for Mastercard Identity Check.
$pares_status
Payment Authentication Response Status. This indicates the outcome of the authentication portion of the 3DS verification. Possible values:
Y
= Successful AuthenticationN
= Failed AuthenticationB
= Bypassed AuthenticationU
= Unable to Complete AuthenticationA
= Successful Attempts Transaction
$signature_verification
Indicates whether or not the 3DS verification messages passed all security validations. Possible values:
Y
= YesN
= No
$three_d_secure_version
The version of 3D Secure authentication used for the transaction. Required
on Visa and Mastercard authentications. Must be composed of digits separated
by periods (e.g. 1.0.2
).
$xid
Transaction identifier resulting from 3D Secure authentication. Uniquely identifies the transaction and sometimes required in the authorization message. Must be base64-encoded. This field will no longer be used in 3D Secure 2 authentications.
$google_transaction_id
A unique identifier provided by Google to track the payment method's transactions.
$cvv
The credit card verification value, only provided for requests featuring a payment_method_nonce
that contains a CVV. Use $cvv_2
when forwarding both a payment_method_token
and payment_method_nonce
.
$ach_mandate_accepted_at
The ISO 8601 date and time at which the account holder agreed to the ACH mandate.