availability

Use of the production Forward API is subject to eligibility.

Contact your Account Manager for more information or submit an inquiry to our Business Development team.

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:

JSON 
{"path": "/var/aes-nonce", "value": ["aes-gcm-nonce"]}

To use that variable, just refer to it by its path:

JSON 
{"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"
$cardholder_name

The cardholder name.
$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 attempted
  • 01 = Attempted
  • 02 = Success

Accepted values for all other card brands:

  • 07 = Failed or not attempted
  • 06 = Attempted
  • 05 = Success
$expiration_month

For Android/Apple Pay, this will be the DPAN expiration month.
$expiration_year

For Android/Apple Pay, this will be the DPAN expiration year.
$number

The credit card number (DPAN for Android/Apple Pay).
$type

The type of payment instrument, e.g. "CreditCard" or "ApplePayCard".
3D Secure

Fields relating to 3D Secure.
$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 Authentication
  • N= Failed Authentication
  • B= Bypassed Authentication
  • U= Unable to Complete Authentication
  • A= Successful Attempts Transaction
$signature_verification

Indicates whether or not the 3DS verification messages passed all security validations. Possible values:

  • Y= Yes
  • N= 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.
android_pay

The following variables will only be defined for requests using Android Pay.
$android_pay_cryptogram

Online payment cryptogram, as defined by 3D Secure.
$google_transaction_id

A unique identifier provided by Google to track the payment method's transactions.
$source_card_last_four

The last 4 digits of the payment method tokenized by the network.
$source_card_type

The type of the card tokenized by the network.
apple_pay

The following variables will only be defined for requests using Apple Pay.
$apple_pay_amount

The transaction amount associated with the cryptogram.
$apple_pay_cryptogram

Online payment cryptogram, as defined by 3D Secure.
$apple_pay_currency_code

The ISO 4217 numeric currency code, as a string to preserve leading zeros.
$apple_pay_device_manufacturer_id

Hex-encoded device manufacturer identifier.
$apple_pay_transaction_id

A hexadecimal transaction identifier, generated on the device.
billing_address

Payment methods may have an associated billing address.
$company

The company name.
$country_code_alpha2

The ISO 3166-1 alpha-2 country code.
$country_name

The country name.
$extended_address

The extended address information — such as apartment or suite number.
$first_name

The first name.
$last_name

The last name.
$locality

The locality/city.
$postal_code

The postal code.
$region

The state or province.
$street_address

The street address.
credit_card

The following variables will only be defined for requests using credit cards.
$bin

The first 6 digits of the credit card, known as the bank identification number (BIN).
$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.
$last_4

The last 4 digits of the credit card number.
us_bank_account

The following variables will only be defined for requests using ACH.
$account_holder_name

The name of the individual or business associated to the account.
$account_number

A 8-10 digit number identifying the individual account.
$account_type

Indicates whether the ownership type is a "checking" or "savings".
$ach_mandate_accepted_at

The ISO 8601 date and time at which the account holder agreed to the ACH mandate.
$ach_mandate_text

The text that the account holder consented to.
$bank_name

The name of the financial institution (e.g. "Wells Fargo").
$ownership_type

Indicates whether it is a "business" or "personal" account.
$routing_number

The 9-digit number identifying the financial institution.