feat/card-exp-documentation (#361)

* feat/card-exp-documentation * feat/card-exp-documentation * Update docs/expressions/filters.mdx Co-authored-by: Drew Hudec <drew@basistheory.com> * Update docs/expressions/filters.mdx Co-authored-by: Drew Hudec <drew@basistheory.com> * feat/card-exp-documentation --------- Co-authored-by: Drew Hudec <drew@basistheory.com>
Basis-Theory · Apr 10, 2024 · 6df2c7e · 6df2c7e
1 parent 54c4b40
commit 6df2c7e
Show file tree

Hide file tree

Showing 2 changed files with 134 additions and 84 deletions.
diff --git a/docs/expressions/filters.mdx b/docs/expressions/filters.mdx
@@ -11,11 +11,13 @@ or you may wish to reformat the data before indexing it for search (e.g. use onl
 
 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> }}`
+
+`{{ <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> | ... }}`
+
+`{{ <variable> | <filter1> | <filter2> | ... }}`
 
 All standard [Liquid filters](https://shopify.github.io/liquid/filters/) are supported within expressions.
 For example, given a token containing a `name` object containing both first and last name properties:
@@ -32,7 +34,7 @@ For example, given a token containing a `name` object containing both first and
 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:
 
 ```javascript showLineNumbers
-\{\{ data.name | split: ' ' | last | upcase }}
+{{ data.name | split: ' ' | last | upcase }}
 ```
 
 This expression would evaluate to the value `"DOE"`.
@@ -169,6 +171,85 @@ Given a token with the data:
 | <code>\{\{ data &#124; alias_preserve_length: 0, 5 }}</code> | `"v38anr9m2cx67890"` |
 | <code>\{\{ data &#124; alias_preserve_length: 3, 5 }}</code> | `"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:
+
+```json showLineNumbers
+{
+  "id": "d35412f4-9d3b-45d8-b051-fe4b7d4e14c5",
+  "type": "card",
+  "data": {
+    "number": "3622720627165567",
+    "expiration_month": 10,
+    "expiration_year": 2028
+  }
+}
+```
+
+| Expression                                       | Result       |
+| ------------------------------------------------ | ------------ |
+| <code>\{\{ data.number &#124; card_bin }}</code> | `"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 month
+- `MMYY`: 2-digit month, year
+- `YYYY`: 4-digit year
+- `YYYY-MM`: 4-digit year, 2-digit month
+- `MM/YY`: 2-digit month, 2-digit year
+- `MM/YYYY`: 2-digit month, 4-digit year 
+- `MM_YYYY`: 2-digit month, 4-digit year 
+- `MM-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:
+
+```json showLineNumbers
+{
+  "id": "d35412f4-9d3b-45d8-b051-fe4b7d4e14c5",
+  "type": "card",
+  "data": {
+    "number": "3622720627165567",
+    "expiration_month": 10,
+    "expiration_year": 2028
+  }
+}
+```
+
+| Expression                                             | Result      |
+| ------------------------------------------------------ | ----------- |
+| <code>\{\{ data &#124; card_exp: 'MM' }}</code>        | `"10"`      |
+| <code>\{\{ data &#124; card_exp: 'MMYY' }}</code>      | `"1028"`    |
+| <code>\{\{ data &#124; card_exp: 'MM/YY' }}</code>     | `"10/28"`   |
+| <code>\{\{ data &#124; card_exp: 'YYYY' }}</code>      | `"2028"`    |
+| <code>\{\{ data &#124; card_exp: 'YYYY-MM' }}</code>   | `"2028-10"` |
+| <code>\{\{ data &#124; card_exp: 'YYYY/MM' }}</code>   | `"2028/10"` |
+
+
+
 ## card_mask
 
 Returns a masked version of the card number, optionally revealing the card's BIN and last 4 digits.
@@ -318,72 +399,6 @@ Given a token with the data:
 | <code>\{\{ data.number &#124; last4 }}</code>                     | `"1667"` |
 | <code>\{\{ data.number &#124; slice: 12, 2 &#124; last4 }}</code> | `"67"`   |
 
-## 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:
-
-```json showLineNumbers
-{
-  "id": "d35412f4-9d3b-45d8-b051-fe4b7d4e14c5",
-  "type": "card",
-  "data": {
-    "number": "3622720627165567",
-    "expiration_month": 10,
-    "expiration_year": 2028
-  }
-}
-```
-
-| Expression                                       | Result       |
-| ------------------------------------------------ | ------------ |
-| <code>\{\{ data.number &#124; card_bin }}</code> | `"42424242"` |
-
-## 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:
-
-```json showLineNumbers
-{
-  "id": "d35412f4-9d3b-45d8-b051-fe4b7d4e14c5",
-  "type": "token",
-  "data": "3622-7206-2716-5567"
-}
-```
-
-| Expression                                              | Result                  |
-| ------------------------------------------------------- | ----------------------- |
-| <code>\{\{ data &#124; reveal: 6 }}</code>              | `"3622-7XXXXXXXXXXXXX"` |
-| <code>\{\{ data &#124; reveal: 7, 5 }}</code>           | `"3622-72XXXXXXX-5567"` |
-| <code>\{\{ data &#124; reveal: 7, 5, '#' }}</code>      | `"3622-72#######-5567"` |
-| <code>\{\{ data &#124; reveal: 7, 4, '#', "-" }}</code> | `"3622-72##-####-5567"` |
-| <code>\{\{ data &#124; reveal: 10, 9 }}</code>          | `"XXXXXXXXXXXXXXXXXXX"` |
-
 ## pad_left
 
 Returns a new string of the desired length by padding the input string on the left with the specified `padChar`.
@@ -448,6 +463,41 @@ Given a token with the data:
 | <code>\{\{ data &#124; pad_right: 4, '0' }}</code> | `"1234"`   |
 | <code>\{\{ data &#124; pad_right: 2, '0' }}</code> | `"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:
+
+```json showLineNumbers
+{
+  "id": "d35412f4-9d3b-45d8-b051-fe4b7d4e14c5",
+  "type": "token",
+  "data": "3622-7206-2716-5567"
+}
+```
+
+| Expression                                              | Result                  |
+| ------------------------------------------------------- | ----------------------- |
+| <code>\{\{ data &#124; reveal: 6 }}</code>              | `"3622-7XXXXXXXXXXXXX"` |
+| <code>\{\{ data &#124; reveal: 7, 5 }}</code>           | `"3622-72XXXXXXX-5567"` |
+| <code>\{\{ data &#124; reveal: 7, 5, '#' }}</code>      | `"3622-72#######-5567"` |
+| <code>\{\{ data &#124; reveal: 7, 4, '#', "-" }}</code> | `"3622-72##-####-5567"` |
+| <code>\{\{ data &#124; reveal: 10, 9 }}</code>          | `"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.

diff --git a/docs/guides/share/process-card-payments.mdx b/docs/guides/share/process-card-payments.mdx
@@ -94,8 +94,8 @@ curl 'https://api.basistheory.com/proxy' \
 --data-urlencode 'type=card' \
 // highlight-start
 --data-urlencode 'card[number]={{ token: d2cbc1b4-5c3a-45a3-9ee2-392a1c475ab4 | json: "$.data.number" }}' \
---data-urlencode 'card[exp_month]={{ token: d2cbc1b4-5c3a-45a3-9ee2-392a1c475ab4 | json: "$.data.expiration_month" }}' \
---data-urlencode 'card[exp_year]={{ token: d2cbc1b4-5c3a-45a3-9ee2-392a1c475ab4 | json: "$.data.expiration_year" }}' \
+--data-urlencode 'card[exp_month]={{ token: d2cbc1b4-5c3a-45a3-9ee2-392a1c475ab4 | card_exp: 'MM' }}' \
+--data-urlencode 'card[exp_year]={{ token: d2cbc1b4-5c3a-45a3-9ee2-392a1c475ab4 | card_exp: 'YYYY' }}' \
 --data-urlencode 'card[cvc]={{ token: d2cbc1b4-5c3a-45a3-9ee2-392a1c475ab4 | json: "$.data.cvc" }}'
 // highlight-end
 ```
@@ -123,8 +123,8 @@ curl 'https://api.basistheory.com/proxy' \
     "type": "scheme",
     // highlight-start
     "number": "{{ token: d2cbc1b4-5c3a-45a3-9ee2-392a1c475ab4 | json: \"$.data.number\" }}",
-    "expiryMonth": "{{ token: d2cbc1b4-5c3a-45a3-9ee2-392a1c475ab4 | json: \"$.data.expiration_month\" | pad_left: 2, \"0\" }}",
-    "expiryYear": "{{ token: d2cbc1b4-5c3a-45a3-9ee2-392a1c475ab4 | json: \"$.data.expiration_year\" }}",
+    "expiryMonth": "{{ token: d2cbc1b4-5c3a-45a3-9ee2-392a1c475ab4 | card_exp: 'MM' }}",
+    "expiryYear": "{{ token: d2cbc1b4-5c3a-45a3-9ee2-392a1c475ab4 | card_exp: 'YYYY' }}",
     "cvc": "{{ token: d2cbc1b4-5c3a-45a3-9ee2-392a1c475ab4 | json: \"$.data.cvc\" }}",
     // highlight-end
     "holderName": "John Smith"
@@ -169,7 +169,7 @@ curl 'https://api.basistheory.com/proxy' \
     "card": {
       // highlight-start
       "ccAccountNum": "{{ token: d2cbc1b4-5c3a-45a3-9ee2-392a1c475ab4 | json: \"$.data.number\" }}",
-      "ccExp": "{{ token: d2cbc1b4-5c3a-45a3-9ee2-392a1c475ab4 | json: \"$.data.expiration_year\" }}{{ token: d2cbc1b4-5c3a-45a3-9ee2-392a1c475ab4 | json: \"$.data.expiration_month\" | pad_left: 2, \"0\" }}"
+      "ccExp": "{{ token: d2cbc1b4-5c3a-45a3-9ee2-392a1c475ab4 | card_exp: 'YYYYMM' }}"
       // highlight-end
     }
   },
@@ -202,7 +202,7 @@ curl 'https://api.basistheory.com/proxy' \
 -H 'Content-Type: SALEM05210/SLM' \
 -d 'P74VPMT-18R86WXMM9
 // highlight-next-line
-VI{{ token: d2cbc1b4-5c3a-45a3-9ee2-392a1c475ab4 | json: "$.data.number" | pad_right: 19, "x" }}{{ token: d2cbc1b4-5c3a-45a3-9ee2-392a1c475ab4 | json: "$.data.expiration_month" | to_string | pad_left: 2, "0" }}{{ token: d2cbc1b4-5c3a-45a3-9ee2-392a1c475ab4 | json: "$.data.expiration_year" | to_string | slice: 2,2 }}00003319380000000000008407202NVF AB
+VI{{ token: d2cbc1b4-5c3a-45a3-9ee2-392a1c475ab4 | json: "$.data.number" | pad_right: 19, "x" }}{{ token: d2cbc1b4-5c3a-45a3-9ee2-392a1c475ab4 | card_exp: 'MMYYYY' }}00003319380000000000008407202NVF AB
 XX XXX                        XXXXX XXXXXXX XX
 USABBEVILLE           LA70510-7288AC01YEI10000000014064
 7930f35b3c06cffe           FR1XXXXMTCSTO
@@ -247,8 +247,8 @@ curl 'https://api.basistheory.com/proxy' \
       "creditCard": {
         // highlight-start
         "number": "{{ token: d2cbc1b4-5c3a-45a3-9ee2-392a1c475ab4 | json: \"$.data.number\"}}",
-        "expirationMonth": "{{ token: d2cbc1b4-5c3a-45a3-9ee2-392a1c475ab4 | json: \"$.data.expiration_month\"}}",
-        "expirationYear": "{{ token: d2cbc1b4-5c3a-45a3-9ee2-392a1c475ab4 | json: \"$.data.expiration_year\"}}",
+        "expirationMonth": "{{ token: d2cbc1b4-5c3a-45a3-9ee2-392a1c475ab4 | card_exp: 'MM'}}",
+        "expirationYear": "{{ token: d2cbc1b4-5c3a-45a3-9ee2-392a1c475ab4 | card_exp: 'YYYY'}}",
         "cvv": "{{ token: d2cbc1b4-5c3a-45a3-9ee2-392a1c475ab4 | json: \"$.data.cvc\"}}"
         // highlight-end
       }
@@ -275,7 +275,7 @@ curl 'https://api.basistheory.com/proxy' \
   "card": {
     // highlight-start
     "accountNumber": "{{ token: d2cbc1b4-5c3a-45a3-9ee2-392a1c475ab4 | json: \"$.data.number\" }}",
-    "expirationDate": "{{ token: d2cbc1b4-5c3a-45a3-9ee2-392a1c475ab4 | json: \"$.data.expiration_year\" }}{{ token: d2cbc1b4-5c3a-45a3-9ee2-392a1c475ab4 | json: \"$.data.expiration_month\" | pad_left: 2, \"0\" }}",
+    "expirationDate": "{{ token: d2cbc1b4-5c3a-45a3-9ee2-392a1c475ab4 | card_exp: 'YYYYMM' }}",
     "securityCode": "{{ token: d2cbc1b4-5c3a-45a3-9ee2-392a1c475ab4 | json: \"$.data.cvc\" }}"
     // highlight-end
   },
@@ -323,7 +323,7 @@ curl 'https://api.basistheory.com/proxy' \
         "creditCard": {
           // highlight-start
           "cardNumber": "{{ token: d2cbc1b4-5c3a-45a3-9ee2-392a1c475ab4 | json: \"$.data.number\" }}",
-          "expirationDate": "{{ token: d2cbc1b4-5c3a-45a3-9ee2-392a1c475ab4 | json: \"$.data.expiration_year\" }}-{{ token: d2cbc1b4-5c3a-45a3-9ee2-392a1c475ab4 | json: \"$.data.expiration_month\" | pad_left: 2, \"0\" }}",
+          "expirationDate": "{{ token: d2cbc1b4-5c3a-45a3-9ee2-392a1c475ab4 | card_exp: 'YYYY-MM' }}",
           "cardCode": "{{ token: d2cbc1b4-5c3a-45a3-9ee2-392a1c475ab4 | json: \"$.data.cvc\" }}"
           // highlight-end
         }
@@ -352,8 +352,8 @@ curl 'https://api.basistheory.com/proxy' \
     "type": "card",
     // highlight-start
     "number": "{{ token: d2cbc1b4-5c3a-45a3-9ee2-392a1c475ab4 | json: \"$.data.number\" }}",
-    "expiry_month": "{{ token: d2cbc1b4-5c3a-45a3-9ee2-392a1c475ab4 | json: \"$.data.expiration_month\" }}",
-    "expiry_year": "{{ token: d2cbc1b4-5c3a-45a3-9ee2-392a1c475ab4 | json: \"$.data.expiration_year\" }}"
+    "expiry_month": "{{ token: d2cbc1b4-5c3a-45a3-9ee2-392a1c475ab4 | card_exp: 'MM' }}",
+    "expiry_year": "{{ token: d2cbc1b4-5c3a-45a3-9ee2-392a1c475ab4 | card_exp: 'YYYY' }}"
     // highlight-end
   },
   "amount": 6500,
@@ -387,7 +387,7 @@ curl 'https://api.basistheory.com/proxy' \
 // highlight-start
 --data-urlencode 'security_key=P4qR9sT2uY7vX1wA3bC8dL5zG6xK9yH2' \
 --data-urlencode 'ccnumber={{ token: d2cbc1b4-5c3a-45a3-9ee2-392a1c475ab4 | json: "$.data.number" }}' \
---data-urlencode 'ccexp={{ token: d2cbc1b4-5c3a-45a3-9ee2-392a1c475ab4 | json: "$.data.expiration_month" }}{{ token: d2cbc1b4-5c3a-45a3-9ee2-392a1c475ab4 | json: "$.data.expiration_year" | to_string | slice: -2, 2 }}' \
+--data-urlencode 'ccexp={{ token: d2cbc1b4-5c3a-45a3-9ee2-392a1c475ab4 | card_exp: "MMYYYY" }}' \
 --data-urlencode 'cvv={{ token: d2cbc1b4-5c3a-45a3-9ee2-392a1c475ab4 | json: "$.data.cvc" }}'
 // highlight-end
 ```
@@ -414,8 +414,8 @@ curl 'https://api.basistheory.com/proxy' \
     // highlight-start
     "cardNum": "{{ token: d2cbc1b4-5c3a-45a3-9ee2-392a1c475ab4 | json: \"$.data.number\" }}",
     "cardExpiry": {
-      "month": "{{ token: d2cbc1b4-5c3a-45a3-9ee2-392a1c475ab4 | json: \"$.data.expiration_month\" | to_number }}",
-      "year": "{{ token: d2cbc1b4-5c3a-45a3-9ee2-392a1c475ab4 | json: \"$.data.expiration_year\" | to_number }}"
+      "month": "{{ token: d2cbc1b4-5c3a-45a3-9ee2-392a1c475ab4 | card_exp: 'MM' | to_number }}",
+      "year": "{{ token: d2cbc1b4-5c3a-45a3-9ee2-392a1c475ab4 | card_exp: 'YYYY' | to_number }}"
     },
     "cvv": "{{ token: d2cbc1b4-5c3a-45a3-9ee2-392a1c475ab4 | json: \"$.data.cvc\" }}",
     // highlight-end