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:

  1. json
{"path": "/var/aes-nonce", "value": ["aes-gcm-nonce"]}

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

  1. 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 suffixesanchor

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

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"

The cardholder name.

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
  • 04 = Data-Only (Applies to limited processors)

Accepted values for all other card brands:

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

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

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

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

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

Fields relating to 3D Secure.

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.

Transaction identifier resulting from 3D Secure 2 authentication. This field must be supplied for Mastercard Identity Check.

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

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

  • Y= Yes
  • N= No

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).

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.

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

Online payment cryptogram, as defined by 3D Secure.

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

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

The type of the card tokenized by the network.

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

The transaction amount associated with the cryptogram.

Online payment cryptogram, as defined by 3D Secure.

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

Hex-encoded device manufacturer identifier.

A hexadecimal transaction identifier, generated on the device.

Payment methods may have an associated billing address.

The company name.

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

The first name.

The last name.

The locality/city.

The postal code.

The state or province.

The street address.

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

The first 6 digits of the credit card, known as the bank identification number (BIN).

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.

The last 4 digits of the credit card number.

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

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

A 8-10 digit number identifying the individual account.

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

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

The text that the account holder consented to.

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

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

The 9-digit number identifying the financial institution.