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.

The config of the Forward API describes the third-party destination: request encoding, HTTP method, and how to inject the payment data.

  • In production, you will send us a JSON file for each config, which we will review, approve, and load.
  • In sandbox, you may include a config object in-line with forwarding requests or send us a JSON file.

Identifying the config by name is supported in both sandbox and production after the config has been loaded.

Parameters

card_type_mapping object

Specify a mapping from the card_type returned from the vault to the destination's expectations. The vault $card_type is used if not present in the map. Example:

  • {"Apple Pay - American Express": "Amex"}
connect_timeout number

The connect timeout for the request to the destination, in milliseconds. Default 10,000 (10 seconds), 0 to disable.

keys array

Note: If your config requires cryptographic keys, they should be sent to Braintree securely. We suggest encrypting the values with the Forward API PGP public key.

An array of encoded keys which may be referenced by later cryptographic functions. See aes-gcm, hmac-sha1, hmac-sha256, hmac-sha512, rsa-pkcs15-sha256.

methods array

Required The supported HTTP methods for this endpoint.

name string

Required The name of the config for future usage in forwarding.

replacement_maps array

An array of JSON objects specifying string replacements for use with the replace function.

request_format object

Specify the encoding for the request headers, query, and body. (e.g. {"/body": "xml", "/body/content/some-xml": "xml", "/body/content/some-json": "json"})

Supported encodings:

  • json - the default encoding for /body, defaults Content-Type to "application/json" when set for /body.
  • xml - defaults Content-Type to "application/xml" when set for /body.
  • urlencode - the default encoding for /header and /urlparam, equivalent to a Content-Type of "application/x-www-form-urlencoded", compatible with "multipart/form-data". Does not default Content-Type.
/body(/path) string

The encoding used for the body.

/header(/path) string

The encoding used for the headers.

/urlparam(/path) string

The encoding used for the query parameters.

request_timeout number

The overarching timeout for the request to the destination, in milliseconds. This value does not take precedence over the connect_timeout or socket_timeout. Default 300,000 (5 minutes).

sanitize_response boolean

In the unlikely event the destination includes the card number in their response, this will replace the card number with "FILTERED" if true. If the request to the destination API included a CVV, any exact matches of the CVV as an isolated value based on the request_format will be replaced with "*".

Example: With a CVV of 123 and a request_format of XML,

XML
<body><exact>123</exact><partial>1234</partial></body>

would become:

XML
<body><exact>***</exact><partial>1234</partial></body>
socket_timeout number

The socket timeout for the request to the destination, in milliseconds. Default 10,000 (10 seconds), 0 to disable.

template object

A template of a request which will be filled in by the transformations. Used only for static data which should be included in every request.

body object

A representation of the body of the request.

header object

A map which will become the headers of the request.

urlparam object

The map which will become the query string of the request.

transformations object

Specify the encoding for the request headers, query, and body.

if_defined string

If present, requires the given value to be defined in order for the transformation to be applied. This will be a variable or template lookup.

path string

A / separated list of names specifying a specific part of the template.

sanitize_value? boolean

If true, any instances of the evaluated transformation value will be removed from Braintree's record of the destination's response. If used in conjunction with sanitize_response, the value will also be replaced with "FILTERED" in the API response.

value string

The value to include at this path in the third party request. Available variables include properties of the payment method specified by payment_method_nonce or payment_method_token and values set in the data and sensitive_data portions of the Forward API request.

A list of all available payment method values is available on the variables page.

In addition to variable substitutions, functions can be applied to variables.

types array

Required The payment instrument types the config should be used for.

Possible values:

  • "AndroidPayCard"
  • "ApplePayCard"
  • "CreditCard"
  • "UsBankAccount"
url string

Required The URL regex for this endpoint which will validate individual forwarding requests.

xml_prefix string

A string literal that will be prepended to the XML body constructed via transformations. XML document type declarations and markup declarations may be provided here.

Example

JSON
{                                                                           
  "methods": ["POST"],                                                      
  "name": "some-endpoint",                                        
  "request_format": {"/body": "json"},                                    
  "transformations": [                                              
    {
      "path": "/body/verify/credit_card/number",
      "value": "$number"
    }
  ],
  "types": ["CreditCard"],
  "url": "^https://some-endpoint\\.com/v1/verify$"
}