feat: new filters and updating card bin length outputs (#92)

Basis-Theory · Apr 3, 2023 · dd0c156 · dd0c156 · vercel · Apr 3, 2023
1 parent 57e1f1d
commit dd0c156
Show file tree

Hide file tree

Showing 4 changed files with 76 additions and 16 deletions.
diff --git a/docs/expressions/filters.mdx b/docs/expressions/filters.mdx
@@ -39,6 +39,40 @@ This expression would evaluate to the value `"DOE"`.
 
 In addition to the standard Liquid filters, several custom filters are also available:
 
+## 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
+
+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; card_mask: 'false', 'false', 'X', '-' }}</code>              | `"XXXX-XXXX-XXXX-XXXX"` |
+| <code>{{ data &#124; card_mask: 'true', 'false', 'X', '-' }}</code>              | `"3622-7206-XXXX-XXXX"` |
+| <code>{{ data &#124; card_mask: 'true', 'true', '#', '-' }}</code>              | `"3622-7206-####-5567"` |
+| <code>{{ data &#124; card_mask: 'false', 'true', 'X', '-' }}</code>              | `"XXXX-XXXX-XXXX-5567"` |
+
 ## alias_preserve_format
 
 Randomly generates a unique alias that preserves the format of the input string, optionally revealing a specified
@@ -194,6 +228,34 @@ Given a token with the data:
 | <code>{{ data &#124; last4 }}</code>                     | `"1667"` |
 | <code>{{ data &#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": "token",
+  "data": "4242424242424242"
+}
+```
+
+| Expression                                               | Result   |
+| -------------------------------------------------------- | -------- |
+| <code>{{ data &#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

diff --git a/docs/sdks/mobile/android/types.mdx b/docs/sdks/mobile/android/types.mdx
@@ -2,7 +2,7 @@
 sidebar_label: Types
 ---
 
-import { Alert } from "@site/src/components/shared/Alert";
+import {Alert} from "@site/src/components/shared/Alert";
 import CardBrands from "@site/docs/sdks/_card-brands.mdx";
 
 # Android Element Types
@@ -68,13 +68,16 @@ The following additional properties are supported when programmatically interact
 | `setValueRef(element: TextElement)`                         | Binds the provided `element: TextElement` instance as a value source for this element, keeping the value of this element in sync with any changes made to the other element. |
 
 <Alert>
-  <code>ElementValueReference</code> is a class that stores a reference to a value which can only be accessed by BasisTheoryElements, so that
+  <code>ElementValueReference</code> is a class that stores a reference to a value which can only be accessed by
+  BasisTheoryElements, so that
   you can reference data without touching the plaintext value and pulling your application into compliance scope.
 </Alert>
 
 <Alert>
-  When using <code>setValueRef</code> to keep a <code>TextElement</code> in sync with another element, or to set the text of an element, it is strongly recommended that
-  you make the element that is being acted upon <code>readonly</code>. This is possible by setting <code>isEditable=false</code>.
+  When using <code>setValueRef</code> to keep a <code>TextElement</code> in sync with another element, or to set the
+  text of an element, it is strongly recommended that
+  you make the element that is being acted upon <code>readonly</code>. This is possible by
+  setting <code>isEditable=false</code>.
 </Alert>
 
 #### XML Attributes
@@ -157,7 +160,7 @@ The brand is used to automatically set a [mask](/docs/sdks/mobile/android/option
 If the [CardNumberElement](#cardnumberelement) is bound to a [CardVerificationCodeElement](#cardverificationcodeelement),
 a mask is also automatically set on the `CardVerificationCodeElement` based on the brand's CVC length requirements.
 
-<CardBrands />
+<CardBrands/>
 
 #### CardMetadata
 
@@ -173,15 +176,15 @@ The `CardMetadata` object contains the properties:
 | Name  | Type     | Description                                                       |
 |-------|----------|-------------------------------------------------------------------|
 | brand | `String` | The card [brand identifier](#card-brands)                         |
-| bin   | `String` | The first 6 digits of the card number if complete, otherwise null |
+| bin   | `String` | The first 6 or 8 digits of the card number if complete, otherwise null. It is 6 digits for card numbers less than 16 digits long and 8 otherwise. |
 | last4 | `String` | The last 4 digits of the card number if complete, otherwise null  |
 
 ### ChangeEvent Details
 
 The `CardNumberElement` emits [ChangeEvents](/docs/sdks/mobile/android/events#changeevent) that may contain several types of [EventDetail](/docs/sdks/mobile/android/events#eventdetails) records.
 
 - `cardBrand`: Contains the card [brand identifier](#card-brands). Only included once enough digits are entered to determine a card brand.
-- `cardBin`: Contains the first 6 digits of the card number. Only included for complete card numbers satisfying the brand-specific mask.
+- `cardBin`: Contains the first 6 or 8 digits of the card number. It is 6 digits for card numbers less than 16 digits long and 8 otherwise. Only included for complete card numbers satisfying the brand-specific mask.
 - `cardLast4`: Contains the last 4 digits of the card number. Only included for complete card numbers satisfying the brand-specific mask.
 
 ## CardExpirationDateElement

diff --git a/docs/sdks/mobile/ios/events.mdx b/docs/sdks/mobile/ios/events.mdx
@@ -40,7 +40,7 @@ The following are the available element event detail types and their description
 | --- |--- |
 | cardBrand | `CardNumberUITextField` elements emit a [card brand](/docs/sdks/mobile/ios/types#card-brands) name when a card number can be identified. |
 | cardLast4 | `CardNumberUITextField` elements emit the last 4 digits of a card number when the input is considered `complete`. |
-| cardBin | `CardNumberUITextField` elements emit the first 6 digits of a card number when the input is considered `complete`. |
+| cardBin | `CardNumberUITextField` elements emit the first 6 or 8 digits of a card number when the input is considered `complete`. It is 6 digits for card numbers less than 16 digits long and 8 otherwise. |
 
 ## Usage
 
@@ -77,4 +77,4 @@ The following are the available properties accessible from `cardMetadata`.
 | --- | --- | --- |
 | cardBrand | _String_ | [Card brand](/docs/sdks/mobile/ios/types#card-brands) name when a card number can be identified. |
 | cardLast4 | _String_ | Last 4 digits of a card number when the input is considered `complete`. |
-| cardBin   | _String_ | First 6 digits of a card number when the input is considered `complete`. |
+| cardBin   | _String_ | First 6 or 8 digits of a card number when the input is considered `complete`. It is 6 digits for card numbers less than 16 digits long and 8 otherwise. |
diff --git a/docs/sdks/web/javascript/methods.mdx b/docs/sdks/web/javascript/methods.mdx
@@ -2,7 +2,7 @@
 sidebar_label: Methods & Events
 ---
 
-import { Alert, Alerts } from "@site/src/components/shared/Alert";
+import {Alert, Alerts} from "@site/src/components/shared/Alert";
 
 # Elements Methods & Events
 
@@ -108,12 +108,7 @@ changes. Default validation (`onBlur`) triggers an event every time one of the v
 | `errors`        | _array_   | All                                                                                                                        | Array of [FieldError](#fielderror).                                                                                                                                                                       |
 | `cardBrand`     | _string_  | [card](/docs/sdks/web/javascript/types#card-element)<br/>[cardNumber](/docs/sdks/web/javascript/types#card-number-element) | (Optional) The credit card [brand](/docs/sdks/web/javascript/options#card-brands) (e.g. `'american-express'`, `'visa'`, `'unknown'`). The value defaults to `'unknown'` until a card brand is recognized. |
 | `cardLast4`     | _string_  | [card](/docs/sdks/web/javascript/types#card-element)<br/>[cardNumber](/docs/sdks/web/javascript/types#card-number-element) | (Optional) The credit card's last 4 digits. The value is not provided until a complete card number is entered.                                                                                            |
-| `cardBin`       | _string_  | [card](/docs/sdks/web/javascript/types#card-element)<br/>[cardNumber](/docs/sdks/web/javascript/types#card-number-element) | (Optional) The credit card number's first 6 digits when the input is considered complete.                                                                                                                 |
-
-<Alert>
-  If you need an eight digit BINs please email us at{" "}
-  <a href="mailto:info@basistheory.com">info@basistheory.com.</a>
-</Alert>
+| `cardBin`       | _string_  | [card](/docs/sdks/web/javascript/types#card-element)<br/>[cardNumber](/docs/sdks/web/javascript/types#card-number-element) | (Optional) The credit card number's first 6 or 8 digits when the input is considered complete. It is 6 digits for card numbers less than 16 digit long and 8 otherwise.                                   |
 
 #### Metadata