Filters
Oftentimes data may be tokenized in one format, but you wish to use this data in a different format within a request. Several pieces of data may be stored together in a single token (e.g., a user record containing first and last names and contact information), but you wish to only use a single piece of that data within a Proxy or Reactor request, or you may wish to reformat the data before indexing it for search (e.g., use only the last name, but normalize by uppercasing it).
To allow you complete flexibility, transformation functions called filters can be applied within any expression.
Generally, a variable's value can be transformed by specifying a filter after the | symbol:
{{ <variable> | <filter> }}
You can effectively think of this as "piping" a variable into the filter in the same way you may be familiar with the "pipe" operator from Unix-like systems. Multiple filters can be chained together by "piping" the result of each filter into the next, applying in order from left to right:
{{ <variable> | <filter1> | <filter2> | ... }}
All standard Liquid filters are supported within expressions.
For example, given a token containing a name object containing both first and last name properties:
{
"data": {
"name": "John Doe"
},
...
}
We can create an expression to return the upper-cased last name by splitting on the space character, grabbing the last element, and upper-casing:
{{ data.name | split: ' ' | last | upcase }}
This expression would evaluate to the value "DOE".
In addition to the standard Liquid filters, several custom filters are also available:
alias_card
Randomly generates a unique alias that preserves the format of the card number, optionally revealing the card's BIN and last 4 digits. If the card's length without the preserved character is less than 16 digits, the card BIN will be 6 digits long, 8 otherwise.
The special characters preserved are the traditional card number delimiters such as " " and "-". If the card number length is less than the revealed
length, an error is returned.
Parameters
| Position | Name | Type | Required | Default Value | Description |
|---|---|---|---|---|---|
| 0 | reveal_bin | bool | false | false | Whether to reveal the card BIN or not |
| 1 | reveal_last4 | bool | false | false | Whether to reveal the last 4 digits or not |
Examples
Card token type
Given a token with the data:
{
"id": "d35412f4-9d3b-45d8-b051-fe4b7d4e14c5",
"type": "card",
"data": {
"number": "3622720627165567",
"expiration_month": 10,
"expiration_year": 2028
}
}
| Expression | Result |
|---|---|
{{ data.number | alias_card }} | "3292231249202291" |
{{ data.number | alias_card: 'false', 'false' }} | "2012232912901293" |
{{ data.number | alias_card: 'true', 'false' }} | "3622720629129014" |
{{ data.number | alias_card: 'true', 'true' }} | "3622720639185567" |
{{ data.number | alias_card: 'false', 'true' }} | "4024420198125567" |
Card number with delimiters
Given a token with the data:
{
"id": "d35412f4-9d3b-45d8-b051-fe4b7d4e14c5",
"type": "token",
"data": "3622-7206-2716-5567"
}
| Expression | Result |
|---|---|
{{ data | alias_card }} | "3292-2312-4920-2291" |
{{ data | alias_card: 'false', 'false' }} | "2012-2329-1290-1293" |
{{ data | alias_card: 'true', 'false' }} | "3622-7206-2912-9014" |
{{ data | alias_card: 'true', 'true' }} | "3622-7206-3918-5567" |
{{ data | alias_card: 'false', 'true' }} | "4024-4201-9812-5567" |
alias_preserve_format
Randomly generates a unique alias that preserves the format of the input string, optionally revealing a specified number of characters from the beginning and end of the value.
Alpha characters are replaced with randomized alpha characters, numeric characters are replaced with randomized numeric characters, and special characters and whitespace are preserved.
Parameters
| Position | Name | Type | Required | Default Value | Description |
|---|---|---|---|---|---|
| 0 | reveal_first_length | int | false | 0 | The number of characters to reveal from the beginning of the value |
| 1 | reveal_last_length | int | false | 0 | The number of characters to reveal from the end of the value |
Examples
Given a token with the data:
{
"id": "<expression>",
"type": "token",
"data": "ABC12345DEF67890"
}
| Expression | Example Result |
|---|---|
{{ data | alias_preserve_format }} | "xir83203hqn73599" |
{{ data | alias_preserve_format: 3 }} | "ABC83203hqn73599" |
{{ data | alias_preserve_format: 0, 5 }} | "xir83203hqn67890" |
{{ data | alias_preserve_format: 3, 5 }} | "ABC83203hqn67890" |
alias_preserve_length
Randomly generates a unique alias that preserves the length of the input string, optionally revealing a specified number of characters from the beginning and end of the value.
All characters are replaced with randomized alphanumeric characters. The type of the character in each position is not preserved, e.g., alpha characters may be replaced with numeric characters and vice versa. Special characters and whitespace are not preserved and will be replaced with alphanumeric characters.
Parameters
| Position | Name | Type | Required | Default Value | Description |
|---|---|---|---|---|---|
| 0 | reveal_first_length | int | false | 0 | The number of characters to reveal from the beginning of the value |
| 1 | reveal_last_length | int | false | 0 | The number of characters to reveal from the end of the value |
Examples
Given a token with the data:
{
"id": "<expression>",
"type": "token",
"data": "ABC12345DEF67890"
}
| Expression | Example Result |
|---|---|
{{ data | alias_preserve_length }} | "v38anr9m2cx0giw7" |
{{ data | alias_preserve_length: 3 }} | "ABCanr9m2cx0giw7" |
{{ data | alias_preserve_length: 0, 5 }} | "v38anr9m2cx67890" |
{{ data | alias_preserve_length: 3, 5 }} | "ABCanr9m2cx67890" |
card_bin
Returns the card's BIN, which is 6 digits for card numbers with less than 16 digits and 8 otherwise. If the card number
contains a character separator like 4242-4242-4242-4242, it can be passed in so it is not part of the returned BIN.
Parameters
| Position | Name | Type | Required | Default Value | Description |
|---|---|---|---|---|---|
| 1 | separator_char | string | false | `` | The card number separator character |
Examples
Given a token with the data:
{
"id": "d35412f4-9d3b-45d8-b051-fe4b7d4e14c5",
"type": "card",
"data": {
"number": "3622720627165567",
"expiration_month": 10,
"expiration_year": 2028
}
}
| Expression | Result |
|---|---|
{{ data.number | card_bin }} | "42424242" |
card_exp
Returns the card's expiration date in a given format. The format can be specified using a combination of the following placeholders:
MM: 2-digit monthMMYY: 2-digit month, yearYYYY: 4-digit yearYYYY-MM: 4-digit year, 2-digit monthMM/YY: 2-digit month, 2-digit yearMM/YYYY: 2-digit month, 4-digit yearMM_YYYY: 2-digit month, 4-digit yearMM-YYYY: 2-digit month, 4-digit year
Parameters
| Position | Name | Type | Required | Default Value | Description |
|---|---|---|---|---|---|
| 1 | date_expression | string | true | `` | The card number expiration expression |
Examples
Card token type
Given a token with the data:
{
"id": "d35412f4-9d3b-45d8-b051-fe4b7d4e14c5",
"type": "card",
"data": {
"number": "3622720627165567",
"expiration_month": 10,
"expiration_year": 2028
}
}
| Expression | Result |
|---|---|
{{ data | card_exp: 'MM' }} | "10" |
{{ data | card_exp: 'MMYY' }} | "1028" |
{{ data | card_exp: 'MM/YY' }} | "10/28" |
{{ data | card_exp: 'YYYY' }} | "2028" |
{{ data | card_exp: 'YYYY-MM' }} | "2028-10" |
{{ data | card_exp: 'YYYY/MM' }} | "2028/10" |
card_mask
Returns a masked version of the card number, optionally revealing the card's BIN and last 4 digits. If the card's length without the preserved character is less than 16 digits, the card BIN will be 6 digits long, 8 otherwise. If the resulting masked string equals the original unmasked value, the whole value is masked.
Parameters
| Position | Name | Type | Required | Default Value | Description |
|---|---|---|---|---|---|
| 0 | reveal_bin | bool | false | false | Whether to reveal the card BIN or not |
| 1 | reveal_last4 | bool | false | false | Whether to reveal the last 4 digits or not |
| 2 | mask_char | char | false | X | The masking character |
| 3 | preserve_char | string | false | `` | The character to preserve |
Examples
Card token type
Given a token with the data:
{
"id": "d35412f4-9d3b-45d8-b051-fe4b7d4e14c5",
"type": "card",
"data": {
"number": "3622720627165567",
"expiration_month": 10,
"expiration_year": 2028
}
}
| Expression | Result |
|---|---|
{{ data.number | card_mask: 'false', 'false', 'X', '-' }} | "XXXXXXXXXXXXXXXX" |
{{ data.number | card_mask: 'true', 'false', 'X', '-' }} | "36227206XXXXXXXX" |
{{ data.number | card_mask: 'true', 'true', '#', '-' }} | "36227206####5567" |
{{ data.number | card_mask: 'false', 'true', 'X', '-' }} | "XXXXXXXXXXXX5567" |
Card number with delimiters
Given a token with the data:
{
"id": "d35412f4-9d3b-45d8-b051-fe4b7d4e14c5",
"type": "token",
"data": "3622-7206-2716-5567"
}
| Expression | Result |
|---|---|
{{ data | card_mask: 'false', 'false', 'X', '-' }} | "XXXX-XXXX-XXXX-XXXX" |
{{ data | card_mask: 'true', 'false', 'X', '-' }} | "3622-7206-XXXX-XXXX" |
{{ data | card_mask: 'true', 'true', '#', '-' }} | "3622-7206-####-5567" |
{{ data | card_mask: 'false', 'true', 'X', '-' }} | "XXXX-XXXX-XXXX-5567" |
json
Evaluates a JSON Path expression (proposed spec) on the input object.
All standard JSON Path syntax is supported, provided that the expression resolves to a single value. If the expression resolves to multiple values, the request will result in a 400 error.
While Liquid supports a very similar syntax to JSON path when selecting properties within a JSON object (e.g., \{\{ data.bicycle.color }}),
it does not support more complex JSON Path expressions (e.g., array filter expressions like $.books[?(@.price < 10)].title).
The json filter provides further flexibility for evaluating complex JSON Path expressions.
Parameters
| Position | Name | Type | Required | Description |
|---|---|---|---|---|
| 0 | json_path_expression | string | true | A JSON Path expression |
Examples
Given a token with the data:
{
"id": "d35412f4-9d3b-45d8-b051-fe4b7d4e14c5",
"type": "token",
"data": {
"books": [
{
"category": "fiction",
"author": "Herman Melville",
"title": "Moby Dick",
"isbn": "0-553-21311-3",
"price": 8.99
},
{
"category": "fantasy",
"author": "J. R. R. Tolkien",
"title": "The Lord of the Rings",
"isbn": "0-395-19395-8",
"price": 22.99
}
],
"bicycle": {
"color": "red",
"price": 19.95
}
}
}
| Expression | Result |
|---|---|
{{ data.bicycle.color }} | "red" |
{{ data | json: '$.bicycle.color' }} | "red" |
{{ data | json: '$.bicycle.price' }} | "19.95" |
{{ data.bicycle }} | { "color": "red", "price": 19.95 } |
{{ data | json: '$.books[0].author' }} | "Herman Melville" |
{{ data | json: '$.books[?(@.price < 10)].title' }} | "Moby Dick" |
{{ data.nonexistent }} | null |
{{ data | json: '$.book..author' }} | <400 Error> |
last4
Returns the last 4 characters of a string. If the string's length is less than 4, the whole value is returned.
Parameters
None
Examples
Given a token with the data:
{
"id": "d35412f4-9d3b-45d8-b051-fe4b7d4e14c5",
"type": "card",
"data": {
"number": "3622720627165567",
"expiration_month": 10,
"expiration_year": 2028
}
}
| Expression | Result |
|---|---|
{{ data.number | last4 }} | "1667" |
{{ data.number | slice: 12, 2 | last4 }} | "67" |
pad_left
Returns a new string of the desired length by padding the input string on the left with the specified padChar.
Returns null when provided a null input value.
Parameters
| Position | Name | Type | Required | Description |
|---|---|---|---|---|
| 0 | length | int | true | The number of characters in the resulting string |
| 1 | pad_char | char | true | A padding character |
Examples
Given a token with the data:
{
"id": "d35412f4-9d3b-45d8-b051-fe4b7d4e14c5",
"type": "token",
"data": "1234"
}
| Expression | Result |
|---|---|
{{ data | pad_left: 6, '0' }} | "001234" |
{{ data | pad_left: 6, 'X' }} | "XX1234" |
{{ data | pad_left: 4, '0' }} | "1234" |
{{ data | pad_left: 2, '0' }} | "1234" |
pad_right
Returns a new string of the desired length by padding the input string on the right with the specified padChar.
Returns null when provided a null input value.
Parameters
| Position | Name | Type | Required | Description |
|---|---|---|---|---|
| 0 | length | int | true | The number of characters in the resulting string |
| 1 | pad_char | char | true | A padding character |
Examples
Given a token with the data:
{
"id": "d35412f4-9d3b-45d8-b051-fe4b7d4e14c5",
"type": "token",
"data": "1234"
}
| Expression | Result |
|---|---|
{{ data | pad_right: 6, '0' }} | "123400" |
{{ data | pad_right: 6, 'X' }} | "1234XX" |
{{ data | pad_right: 4, '0' }} | "1234" |
{{ data | pad_right: 2, '0' }} | "1234" |
reveal
Returns a masked version of the string revealing characters at the start and end whilst preserving others. If the string's
length is less than or equal to reveal_first + reveal_last, or the resulting masked string equals the original unmasked value,
the whole value is masked.
Parameters
| Position | Name | Type | Required | Default Value | Description |
|---|---|---|---|---|---|
| 0 | reveal_first | int | false | 0 | The number of characters to reveal at the start |
| 1 | reveal_last | int | false | 0 | The number of characters to reveal at the end |
| 2 | mask_char | char | false | X | A masking character |
| 3 | preserve_chars | string | false | `` | The characters to preserve |
Examples
Given a token with the data:
{
"id": "d35412f4-9d3b-45d8-b051-fe4b7d4e14c5",
"type": "token",
"data": "3622-7206-2716-5567"
}
| Expression | Result |
|---|---|
{{ data | reveal: 6 }} | "3622-7XXXXXXXXXXXXX" |
{{ data | reveal: 7, 5 }} | "3622-72XXXXXXX-5567" |
{{ data | reveal: 7, 5, '#' }} | "3622-72#######-5567" |
{{ data | reveal: 7, 4, '#', "-" }} | "3622-72##-####-5567" |
{{ data | reveal: 10, 9 }} | "XXXXXXXXXXXXXXXXXXX" |
reveal_last
Returns the last length characters of a string. If the string's length is less than or equal to length, the whole value is returned.
Parameters
| Position | Name | Type | Required | Default Value | Description |
|---|---|---|---|---|---|
| 0 | length | int | true | null | The number of characters to reveal |
| 1 | mask_char | char | false | X | A masking character |
Examples
Given a token with the data:
{
"id": "d35412f4-9d3b-45d8-b051-fe4b7d4e14c5",
"type": "token",
"data": "36227206271667"
}
| Expression | Result |
|---|---|
{{ data | reveal_last: 6 }} | "XXXXXXXX271667" |
{{ data | reveal_last: 3, '#' }} | "###########667" |
stringify
Returns a JSON serialized string of the input object.
Returns null when provided a null input value.
Parameters
None
Examples
Given a token with the data:
{
"id": "d35412f4-9d3b-45d8-b051-fe4b7d4e14c5",
"type": "token",
"data": {
"books": [
{
"category": "fiction",
"author": "Herman Melville",
"title": "Moby Dick",
"isbn": "0-553-21311-3",
"price": 8.99
},
{
"category": "fantasy",
"author": "J. R. R. Tolkien",
"title": "The Lord of the Rings",
"isbn": "0-395-19395-8",
"price": 22.99
}
],
"bicycles": [
{
"color": "red",
"price": 19.95
},
{
"color": "blue",
"price": 24.95
}
]
}
}
| Expression | Result |
|---|---|
{{ data.books[0].price | stringify }} | "8.99" |
{{ data.books[1].title | stringify }} | "The Lord of the Rings" |
{{ data.bicycles[1] | stringify }} | "{\"color\":\"red\",\"price\":19.95}" |
{{ data.bicycles | stringify }} | "[{\"color\":\"red\",\"price\":19.95},{\"color\":\"blue\",\"price\":24.95}]" |
to_boolean
Casts the input value to a boolean value.
Returns null when provided a null input value. Returns an error when the input cannot be cast to a boolean.
Parameters
None
Examples
Given a token with the data:
{
"id": "d35412f4-9d3b-45d8-b051-fe4b7d4e14c5",
"type": "token",
"data": {
"true_string": "true",
"false_string": "false"
}
}
| Expression | Result |
|---|---|
{{ data.true_string | to_boolean }} | true |
{{ data.false_string | to_boolean }} | false |
to_number
Casts the input value to a numeric value.
Returns null when provided a null input value. Returns an error when the input cannot be cast to a number.
Parameters
None
Examples
Given a token with the data:
{
"id": "d35412f4-9d3b-45d8-b051-fe4b7d4e14c5",
"type": "token",
"data": {
"int_string": "42",
"decimal_string": "3.14159"
}
}
| Expression | Result |
|---|---|
{{ data.int_string | to_number }} | 42 |
{{ data.decimal_string | to_number }} | 3.14159 |
to_string
Casts the input value to a string value.
Returns null when provided a null input value. Returns an error when the input cannot be cast to a string (e.g., for complex object values).
Parameters
None
Examples
Given a token with the data:
{
"id": "d35412f4-9d3b-45d8-b051-fe4b7d4e14c5",
"type": "token",
"data": {
"numeric_value": 3.14159,
"boolean_value": true,
"string_value": "foo"
}
}
| Expression | Result |
|---|---|
{{ data.numeric_value | to_string }} | "3.14159" |
{{ data.boolean_value | to_string }} | "true" |
{{ data.string_value | to_string }} | "foo" |
to_base64
Encodes the provided byte array to base64 format.
Returns an error if the byte array is null.
Parameters
None
Examples
Given a token with the data:
{
"id": "d35412f4-9d3b-45d8-b051-fe4b7d4e14c5",
"type": "token",
"data": "secretText"
}
| Expression | Result |
|---|---|
{{ data | hmac: 'sha-256', 'secretKeyValue' | to_base64 }} | "Q31M2Y1rHnxT+hzO4XAlrfYrLRDX26/fmgadtcmpzhQ=" |
to_base16 (hex)
Encodes the provided byte array to base16 (hex) format.
Returns an error if the byte array is null.
Parameters
None
Examples
Given a token with the data:
{
"id": "d35412f4-9d3b-45d8-b051-fe4b7d4e14c5",
"type": "token",
"data": "secretText"
}
| Expression | Result |
|---|---|
{{ data | hmac: 'sha-256', 'secretKeyValue' | to_base16 }} | "437D4CD98D6B1E7C53FA1CCEE17025ADF62B2D10D7DBAFDF9A069DB5C9A9CE14" |
hmac
Generates a hmac signature using the specified algorithm.
Returns the signature byte array which can be encoded using to_base64 or to_base16 filters.
Parameters
| Position | Name | Type | Required | Default Value | Description |
|---|---|---|---|---|---|
| 0 | algorithm | string | false | sha-256 | Algorithm to use. One of sha-1, sha-256 or sha-512 |
| 1 | key | string | true | - | Secret key used to hash the data |
Examples
Given a token with the data:
{
"id": "d35412f4-9d3b-45d8-b051-fe4b7d4e14c5",
"type": "card_number",
"data": "4242424242424242"
}
| Expression | Result |
|---|---|
{{ data | hmac: 'sha-256', 'secretKeyValue' | to_base16 }} | "90A0050E90515101DCAD0F68955370CCA81F6DCB9D299E7E0585CC9746716D9B" |