Forward API/
Config

Config

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.

ParametersAnchorIcon


card_type_mappingobject

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_timeoutnumber

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

keysarray

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.

methodsarray

Required

The supported HTTP methods for this endpoint.

nameString

Required

The name of the config for future usage in forwarding.

replacement_mapsarray

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

request_formatobject

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_timeoutnumber

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_responseboolean

Missing: ForwardConfigSanitizeResponse

socket_timeoutnumber

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

templateobject

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.

bodyobject

A representation of the body of the request.

headerobject

A map which will become the headers of the request.

urlparamobject

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

transformationsobject

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

if_definedString

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.

pathString

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.

valueString

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.

typesarray

Required

The payment instrument types the config should be used for.

Possible values:

  • "AndroidPayCard"
  • "ApplePayCard"
  • "CreditCard"
  • "UsBankAccount"

urlString

Required

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

To mitigate URL manipulation, URL regex must conform to the following requirements:

  • URL must begin with "^"
  • "." in URL must be escaped ("\.")

xml_prefixString

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.

ExampleAnchorIcon

  1. 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$"
}