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 functions available in the Forward API domain-specific language (DSL). The DSL has been kept intentionally minimal, fill out this form if you find yourself needing a new function.

aes-gcm bytes

["aes-gcm", keyid, nonce, data] Encrypts data using the key referenced by keyid (an integer) and a nonce created by aes-gcm-nonce. Returns a byte array. keyid is a 0-indexed reference into the keys array of keys provided by the config. The key must be 16, 24, or 32 bytes in length, hex-encoded.

Examples:

  • ["aes-gcm", 0, ["aes-gcm-nonce"], "$number"] ⇒ Some byte array (In a real example you would want to store the result of calling aes-gcm-nonce in an intermediate variable so it can be included in the body of the destination request)
aes-gcm-nonce bytes

["aes-gcm-nonce"] Returns a byte array filled with 12 random bytes.

Examples:

  • ["hex", ["aes-gcm-nonce"]] ⇒ "s8tIW/oPqPkkN1OY"
array array

JSON arrays form the s-expressions of the Forward API DSL. array allows you to create literal arrays.

Examples:

  • ["array", "braintree", "payments"] ⇒ ["braintree", "payments"]
  • ["array", ["base64", "braintree"], "payments"] ⇒ ["YnJhaW50cmVl", "payments"]
base64 string

["base64", value] base 64 encodes the result of evaluating value.

Examples:

  • ["base64", "braintree"] ⇒ "YnJhaW50cmVl"
  • ["base64", ["md5", "braintree"]] ⇒ "cC5vUPvGgxD8+vLvjq7GIQ=="
concat bytes

Given some number of byte array args, returns the byte array result of concatenating each of those args.

encode bytes

["encode", charset, input] returns the byte array result of applying the encoding charset to the input. The default charset is UTF-8.

Examples:

  • ["base64", ["encode", "UTF-16", "braintree"]]⇒ "/v8AYgByAGEAaQBuAHQAcgBlAGU="
  • ["hex", ["encode", "UTF-32", "abc"]] ⇒ "000000610000006200000063"
format_expiration string

["format_expiration", format_string] the format string may include any combination of the following: %Y, %y, %m, %-m, %%.

Directives:

  • %Y - Year with century
  • %y - Year modulo 100
  • %m - Month of the year, zero-padded (01..12)
  • %-m - Month of the year, no padding (1..12)
  • %% - Literal "%"

Examples:

  • ["format_expiration", "%m/%Y"] ⇒ "10/2015" (assuming an expiration month of October in the year 2015)
  • ["format_expiration", "%m/%y"] ⇒ "07/15" (assuming an expiration month of July in the year 2015)
hex string

["hex", value] hexadecimal encodes the result of evaluating value.

Examples:

  • ["hex", "braintree"] ⇒ "627261696e74726565"
  • ["hex", ["md5", "braintree"]] ⇒ "702e6f50fbc68310fcfaf2ef8eaec621"
hmac-sha1 bytes

["hmac-sha1", keyid, data] generates the keyed-hash message authentication code of data using the key referenced by keyid in the (0-indexed) array of keys provided by the config. Returns a byte array; wrap in hex or base64 to make a string.

Examples:

  • ["hex", ["hmac-sha1", 0, "The quick brown fox jumps over the lazy dog"]]"de7c9b85b8b78aa6bc8a7a36f70a90701c9db4d9", with "keys": ["6b6579"] (the hex encoding of the ASCII string "key").
hmac-sha256 bytes

["hmac-sha256", keyid, data] generates the keyed-hash message authentication code of data using the key referenced by keyid in the (0-indexed) array of keys provided by the config. Returns a byte array; wrap in hex or base64 to make a string.

Examples:

  • ["hex", ["hmac-sha256", 0, "The quick brown fox jumps over the lazy dog"]]"f7bc83f430538424b13298e6aa6fb143ef4d59a14946175997479dbc2d1a3cd8", with "keys": ["6b6579"] (the hex encoding of the ASCII string "key").
hmac-sha512 bytes

["hmac-sha512", keyid, data] generates the keyed-hash message authentication code of data using the key referenced by keyid in the (0-indexed) array of keys provided by the config. Returns a byte array; wrap in hex or base64 to make a string.

Examples:

  • ["hex", ["hmac-sha512", 0, "The quick brown fox jumps over the lazy dog"]]"b42af09057bac1e2d41708e48a902e09b5ff7f12ab428a4fe86653c73dd248fb82f948a549f7b791a5b41915ee4d1ec3935357e4e2317250d0372afa2ebeeb3a", with "keys": ["6b6579"] (the hex encoding of the ASCII string "key").
integer string

["integer", value] attempts to cast value to an integer. Returns transformation error if string can't be cast.

Examples:

  • ["integer", "1"] ⇒ 1
join string

["join", separator, value] returns a string created by converting each element of the evaluated expression value to a string, separated by the result of evaluating separator.

Examples:

  • ["join", ":", ["array", "braintree", "payments"]] ⇒ "braintree:payments"
last_n string or array

["last_n", n, value] returns the last n characters of the string resulting from evaluating value, or the last n elements if value is an array.

Examples:

  • ["last_n", 4, "braintree"] ⇒ "tree"
  • ["last_n", 1, ["array", "braintree", "payments"]] ⇒ "payments"
md5 bytes

["md5", value] MD5 the result of evaluating value. Returns a byte array; use hex or base64 to make a string.

Examples:

  • ["hex", ["md5", "braintree"]] "702e6f50fbc68310fcfaf2ef8eaec621"
percent-encode string

["percent-encode", value] returns the result of applying percent-encoding replacements on the specified value.

Examples:

  • ["percent-encode", "braintree payments"] ⇒ "braintree%20payments"
replace string

["replace", replacement_map_index, value] returns the result of applying the string replacements specified by the (0-indexed) config's replacement_map.

Examples with replacement_maps: [{"a": "@", "e": "$!"}, {"e": "3"}]:

* `["replace", 0, "braintree"]` ⇒ "br@intr$!$!"
  * `["replace", 1, "braintree"]` ⇒ "braintr33"
rsa-oaep-sha1 bytes

["rsa-oaep-sha1", ["rsa-public-key", "$PEM_encoded_public_key"], "value to encrypt"] encrypts the specified value using a given RSA public key, with OAEP padding (using a SHA1 message digest and MGF1 mask generation function). Returns a byte array; wrap in hex or base64 to make a string.

rsa-pkcs1 bytes

["rsa-pkcs1", ["rsa-public-key", "$PEM_encoded_public_key"], "value to encrypt"] encrypts the specified value using a given RSA public key, with PKCS1 padding. Returns a byte array; wrap in hex or base64 to make a string.

Examples:

  • ["base64", ["rsa-pkcs1", ["rsa-public-key", "$public_key"], "value to encrypt"]]"dA0KkYFXykS5L2bPPecFBmXuEMxst+E6gQ6/i+w2+PYxCBserUIc21gW5eCXcca6kjhevo5371OfOivy+pIoY0HOgThB3DTQV+cEqxN9tb0U7ZJXXsMOVuIKXzkGofKeAI1CJVzwVh6lK5Cy7EDtYd8dUPLt+QuozWGtm7zaWfn6HWycRS0WG7GMbON2A+BiWv+fehv1jFB4nArHMiXbR1tdY10hLXsNrXHhwuft99LyCx0sIE7R6fdXi/WckdTeyVDeCmBiSX41CEjjgqGFj0KibjMYkzSNY+XO4k5Amvge4ha0YLv5bx38GhooshU0QqjzKRiz6dbJVP1ikzd49w==" Using the example RSA public key
rsa-pkcs15-sha256 bytes

["rsa-pkcs15-sha256", keyid, data] encrypts the SHA256 digest using a given (PEM encoded) RSA private key in the config's keys array, with PKCS1 v1.5 padding. Returns a byte array; wrap in hex or base64 to make a string.

Examples:

  • ["base64", ["rsa-pkcs16-sha256", 0, "Data to digest and encrypt"]]"zyhOjvWCcTxf1CtBVK2BdS1Djfv8FReCuRhQ7WPd3qUp2Hw89A2oj1oQr43THGcD+i0dWiVlcObEshPwKEXqns0bNRbKoBRVKNWCFUfmoJuNLuqOBDQMMeRxFwf91zbeYSAz6x3FwY7BcD713422jYRvTcawezKCB8QKGP9LUs4nJNZ9B5VGC0L9fTzsWJbv6ra7KNSQRGPYug9kK1/Y5dcTozaTiBJvYj22TBd2L4Gfr7pazQgGjiLzAA+qAg4/YPLHGv9EL39yJQZ2FM5Uuds6PhJAT3KjzKmqGkZr/QK0tIlax/3SZ3pnQ/LSHWRnczMdBC/FN0gVFl/FcxNlxw==" Using the example RSA private key
rsa-public-key bytes

["rsa-public-key", "$PEM_encoded_public_key"] reads the provided PEM-encoded RSA public key.

sha1 bytes

["sha1", value] SHA1 the result of evaluating value. Returns a byte array; use hex or base64 to make a string.

Examples:

  • ["hex", ["sha1", "braintree"]] ⇒ "984214838d0fc4b1eab0dbca61160867c9878041"
  • ["base64", ["sha1", "braintree"]] ⇒ "mEIUg40PxLHqsNvKYRYIZ8mHgEE="
sha256 bytes

["sha256", value] SHA256 the result of evaluating value. Returns a byte array; use hex or base64 to make a string.

Examples:

  • ["hex", ["sha256", "braintree"]]"e2d67f41fee239d12faf598242412e25b357740b9a20a5b14c9795dcae320bf5"
  • ["base64", ["sha256", "braintree"]]"4tZ/Qf7iOdEvr1mCQkEuJbNXdAuaIKWxTJeV3K4yC/U="
sha512 bytes

["sha512", value] SHA512 the result of evaluating value. Returns a byte array; use hex or base64 to make a string.

Examples:

  • ["hex", ["sha512", "braintree"]]"4bdd950f340870714a8c6b58209e2a3b2b7df78c995835e34a66e7de2c213040a1ba0ad5d7e0342db8411467b3051a1470ec9ac13569cd5b8a47e7030b60d63b"
  • ["base64", ["sha512", "braintree"]]""S92VDzQIcHFKjGtYIJ4qOyt994yZWDXjSmbn3iwhMEChugrV1+A0LbhBFGezBRoUcOyawTVpzVuKR+cDC2DWOw=="

Example RSA keypair

-----BEGIN PUBLIC KEY-----
MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA4c/yKBAkD8wbX7nNfDXL
hL9pMKwBZhEnbPprRjeAX/lelso424gFSZtq4X3LFamrDN59cN2RHqj7so/aK7rW
JJzj9y+lYxocJaNbyFXlZ9ctC0OcoqyqaTlKT0VmAa7EyQXtOsUy0r3nT1emdKTs
vpz/3sFZPyWVIQ2oG/ea+QjzQvUTt8njp3l7D1txGJ+XdtGKrxJ0EuhLJNirDjlY
et33agZOQJTnUzhYA2TJsZNo9zCj9b6DyIfNVeCN0o00r/Hm5d6zlKemKbOKWtSS
dY0wGqSZB+sew+tMZaWfSzij1FzGsfkVaG/VEeMgxZq7fYu+hCcFDDQlElwf1SwJ
qwIDAQAB
-----END PUBLIC KEY-----
-----BEGIN RSA PRIVATE KEY-----
MIIEpQIBAAKCAQEA4c/yKBAkD8wbX7nNfDXLhL9pMKwBZhEnbPprRjeAX/lelso4
24gFSZtq4X3LFamrDN59cN2RHqj7so/aK7rWJJzj9y+lYxocJaNbyFXlZ9ctC0Oc
oqyqaTlKT0VmAa7EyQXtOsUy0r3nT1emdKTsvpz/3sFZPyWVIQ2oG/ea+QjzQvUT
t8njp3l7D1txGJ+XdtGKrxJ0EuhLJNirDjlYet33agZOQJTnUzhYA2TJsZNo9zCj
9b6DyIfNVeCN0o00r/Hm5d6zlKemKbOKWtSSdY0wGqSZB+sew+tMZaWfSzij1FzG
sfkVaG/VEeMgxZq7fYu+hCcFDDQlElwf1SwJqwIDAQABAoIBAQCLAg/4SbdpYiSX
0TGF/TfECHEg3UIfKwAyPhY7q38Dled8vBA0VI+suFgbZ+zU8RWzXmOqTzs+vJf1
XEjaErIw58QOLu6JC1G4ec/Oi9IlEnlQLdcG7XQaQoJUOkyJTKUnetaHD04yHWV/
ml2GAOEcllmNL0lZbjFXn6iVTt+/3XIz+PieA600+0pkqffkbDhfkLPjM4j49vrC
fZvtHliGTPqSJrZJg1mgUJTcROC5evKXNrffA+QBzbCIPWmdc5mdtj42OH+2lzGW
jVqxSkcZS/WxQqGSj3LQQ96ixR1jCrMLyzSuVT1EuQAAwZ/DzbOnfyCgS7yGStKi
4cNB40eBAoGBAP14CAkwWslKVKGY6yK+jFCsCWPB+j8Xpn/mfBaGzY/CA04gy2UL
WlpmUXvSwVUZ5X9PwJgmzVf0OSWft0FMua8DHjs9yKhImNR4HAOfA5+7gkZKXV2l
NCx9p2uJ5QQ00YufJShrFJKWpCdrAtS+j4oO1WQpgqwpfCzYMkEk6K9zAoGBAOQR
NpF29ZsLg1/8bS46k2x8PnWvrKnccaPkgg28GVv1E07HxnT1TqIFDRpYLBQ0AeZ+
NZ+LWiF8+75dfZrvIJZENEyZX3YO8hX8HoyUfmeCvelf1c75BMiMerW31rzYHYzs
LgVeIU2BZbciK5Nqz1iwvOaQ+2A7wwe5gEfy377pAoGAQQ9sUJ9+zigsLQaJZHOw
pIxkJJ0H1OYHMNFCjK2xWfMc0hMM4jTVzlpxE+12/pcVF2arMuLS1n6zpHqomTRO
fSO5wM8NEFUCFZd26V8JmRiSSeSQrpbXG4xtSucsR7YfC02gRg2mTDIqlIudQGph
gbhpAbq99d74JrKfw6TrrQ0CgYEA2XTwKtLaa/MWWLc/Aw0m9BGjHGNcprliQXrn
5mCrbVrIBh3FxE8BospeK/hWTw0norZEOtOMJNIe1uwdj1TiJWTy2PaEZvTpLr0u
A6yyuc+XdKXEH4ygWvhXKF0ZiwYlZvDrEIMoDdaLPYp/Mhhti4s5Ej668I8K7pqZ
DgEuBcECgYEAjFP0UjJWQuBV2z9zPJTltWw6e/KMmz+AIOqz4l3iUaNmhInLk5pK
iiliknXVNHjygimJS6GkZPO7QkncKag5s/lUFGf87OzfU46AM6qBBMofH7G3STWs
9G32FtR2tTCk5vBedGi2clwHWMV1+Cu8gwrI4GJ/BLbKVp/yQUOTBp4=
-----END RSA PRIVATE KEY-----