Android Element Types

TextElement

The TextElement can be used to collect any text data within your mobile application. This component allows you to fully customize the look and feel to match your brand, and it does not allow direct access the underlying plaintext values entered by a user, keeping your mobile application out of compliance scope.

Basic Usage

To use the TextElement within your Android application, simply include the view within one of your Android application’s layouts.

<com.basistheory.android.view.TextElement
    android:id="@+id/name"
    android:layout_width="match_parent"
    android:layout_height="wrap_content" />

Properties can be programmatically initialized within your views within either the onCreate or onCreateView lifecycle methods.

Configuration

The TextElement extends the native FrameLayout view, so all standard properties and attributes supported by FrameLayout are supported by TextElement.

Properties

The following additional properties are supported when programmatically interacting with a TextElement:

Name	Type	Description
hint	`String`	Placeholder text to display within the element when empty.
hintTextColor	`Int`	A color value in the form `0xAARRGGBB` to paint the hint text. Do not pass a resource ID. To get a color value from a resource ID, call getColor.
isComplete	`Boolean`	Whether this element satisfies the mask and validator, i.e. it is ready to be tokenized.
isEditable	`Boolean`	Whether this element is editable or readonly.
isEmpty	`Boolean`	Whether this element is empty.
isMaskSatisfied	`Boolean`	Whether this element satisfies the length and format requirements of the mask, if defined. Defaults to `true` if this element does not have a mask.
isValid	`Boolean`	The result of this element's validator, if defined. Defaults to `true` if this element does not have a validator.
inputType	`InputType`	Indicates which type of virtual keyboard to display while editing and how to display data entered into the Element. See Input Types for details.
mask	`ElementMask`	Restricts and formats input entered into this Element. See the Mask options for details.
removeDefaultStyles	`Boolean`	Removes the default Android styling on the underlying EditText. Defaults to `true`.
textColor	`Int`	A color value in the form `0xAARRGGBB` to paint the text. Do not pass a resource ID. To get a color value from a resource ID, call getColor.
textSize	`Float`	The font size, in pixels.
typeface	`Typeface`	The Typeface that is used to style the text.
transform	`ElementTransform`	Transforms the value of this Element prior to tokenization. See the Transform options for details.
validator	`ElementValidator`	Validates the value of this Element. See the Validator options for details.
gravity	`Int`	The Gravity value to apply to the text within the element.
getValueType	`ElementValueType`	The value type for which the element value is rendered to before being sent to the API.
enableCopy	`Boolean`	Adds a copy icon to the element that copies its value to the clipboard when tapped.
copyIconColor	`Int`	The color for the copy icon that gets added when using `enableCopy`

Methods

Signature	Description
`addBlurEventListener(listener: (BlurEvent) -> Unit)`	Adds a listener for any BlurEvents raised by this element.
`addChangeEventListener(listener: (ChangeEvent) -> Unit)`	Adds a listener for any ChangeEvents raised by this element.
`addFocusEventListener(listener: (FocusEvent) -> Unit)`	Adds a listener for any FocusEvents raised by this element.
`setText(value: String?)`	Sets the text value for the element. Note that a getter is not exposed on the TextElement to retrieve the underlying text value.
`setValueRef(elementValueReference: ElementValueReference)`	Sets the element's text to the value referenced by the provided ElementValueReference.
`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.
`setDrawables(startDrawable: Int, topDrawable: Int, endDrawable: Int, bottomDrawable: Int)`	Sets drawables at the start, top, end and/or bottom of the element. Use 0 to not set any drawable on the respective position.

ElementValueReference 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.

When using setValueRef to keep a TextElement 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 readonly. This is possible by setting isEditable=false.

XML Attributes

The following additional XML attributes are also supported when defining a TextElement in a layout XML file:

Name	Type	Description
android:enabled	`boolean`	Whether this element is editable or readonly.
android:hint	`String`	Placeholder text to display within the Element.
android:inputType	`enum`	Indicates which type of virtual keyboard to display while editing and how to display data entered into the Element. See Input Types for details.
android:text	`string`	Sets the text value for the element. Note that a getter is not exposed on the TextElement to retrieve the underlying text value.
android:textColor	`reference`\|`color`	The text color. May be a reference to another resource, in the form `"@[+][package:]type/name"` or a theme attribute in the form `"?[package:]type/name"`. May be a color value, in the form of `"#rgb"`, `"#argb"`, `"#rrggbb"`, or `"#aarrggbb"`
android:textColorHint	`reference`\|`color`	The hint text color. May be a reference to another resource, in the form `"@[+][package:]type/name"` or a theme attribute in the form `"?[package:]type/name"`. May be a color value, in the form of `"#rgb"`, `"#argb"`, `"#rrggbb"`, or `"#aarrggbb"`
android:textSize	`dimension`	The size of text.
android:typeface	`enum`	The typeface (normal, sans, serif, monospace) for the text. To fully customize the font family and text style, set `TextElement.typeface` programmatically.
android:gravity	`String`	The Gravity value to apply to the text within the element. The XML accepts Gravity constants like `"center"`, `"start"` as string values.
bt_mask	`string`	A string defining the mask applied to this Element, e.g. (`###-##-####`).
bt_removeDefaultStyles	`boolean`	Removes the default Android styling on the underlying EditText. Defaults to `true`.

Custom attributes prefixed with bt_ can be used within a view by importing the XML namespace http://schemas.android.com/apk/res-auto, for example

<layout xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:app="http://schemas.android.com/apk/res-auto">

    <com.basistheory.android.view.TextElement
        ...
        app:bt_mask="###-##-####" />

</layout>

CardNumberElement

The CardNumberElement can be used to securely collect credit card numbers within your application. This element will render a text input within your view to accept a card number entered by your end users.

This element was designed to be used in conjunction with the CardExpirationDateElement and CardVerificationCodeElement to collect and tokenize a card token.

Basic Usage

To use the CardNumberElement within your Android application, simply include the view within one of your Android application’s layouts.

<com.basistheory.android.view.CardNumberElement
    android:id="@+id/card_number"
    android:layout_width="match_parent"
    android:layout_height="wrap_content" />

This element can be referenced directly when tokenizing through the BasisTheoryElements service class:

val cardNumberElement = findViewById<CardNumberElement>(R.id.card_number)
...

val tokenizeResponse = bt.tokenize(object {
    val type = "card"
    val data = object {
        val number = cardNumberElement
        val expiration_month = cardExpirationDateElement.month()
        val expiration_year = cardExpirationDateElement.year()
        val cvc = cardVerificationCodeElement
    }
})

The element serves as a reference that can only be resolved back to the original value by the BasisTheoryElements service when tokenizing. Your application is not given direct access to the underlying plaintext value.

Configuration

The CardNumberElement extends the TextElement view, so all properties and attributes supported by TextElement are also supported here.

By default, this element is configured with:

The keyboard is configured to only allow numeric input
A mask is applied to format input values according to the card brand
The LuhnValidator is applied to restrict input to Luhn-valid cards

This component fully supports the same style customizations to match your branding that are supported on the base TextElement.

Card Brands

The first several digits of the card number are analyzed as the user is typing to determine the card brand. The brand is used to automatically set a mask to a brand-specific format. If the CardNumberElement is bound to a CardVerificationCodeElement, a mask is also automatically set on the CardVerificationCodeElement based on the brand's CVC length requirements.

Supported card brands are defined in the table below:

Brand	Identifier	Card Number Digits	CVC Digits
American Express	`american-express`	15	4
Diners Club	`diners-club`	14, 16, 19	3
Discover	`discover`	16, 19	3
Elo	`elo`	16	3
Hiper	`hiper`	16	3
HiperCard	`hipercard`	16	3
JCB	`jcb`	16-19	3
Maestro	`maestro`	12-19	3
Mastercard	`mastercard`	16	3
MIR	`mir`	16-19	3
UnionPay	`unionpay`	14-19	3
Visa	`visa`	16, 18, 19	3

Some card brands have issued card numbers with multiple lengths. The Card Number Digits column documents all acceptable card number lengths for the brand (in number of digits, excluding formatting characters).

CardMetadata

The brand details and other card metadata are made available to your application within the cardMetadata property on the CardNumberElement:

Name	Type	Description
cardMetadata	`CardMetadata`	Gets metadata about the card, derived from user input.

The CardMetadata object contains the properties:

Name	Type	Description
brand	`String`	The card brand identifier
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 that may contain several types of EventDetail records.

cardBrand: Contains the card brand identifier. Only included once enough digits are entered to determine a card brand.
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

The CardExpirationDateElement can be used to securely collect credit card expiration dates within your application. This element will render a text input within your view that accepts input in the form MM/yy.

This element was designed to be used in conjunction with the CardNumberElement and CardVerificationCodeElement to collect and tokenize a card token.

Basic Usage

To use the CardExpirationDateElement within your Android application, simply include the view within one of your Android application’s layouts.

<com.basistheory.android.view.CardExpirationDateElement
    android:id="@+id/expiration_date"
    android:layout_width="match_parent"
    android:layout_height="wrap_content" />

The month and year values can be referenced separately when tokenizing through the BasisTheoryElements service class:

val tokenizeResponse = bt.tokenize(object {
    val type = "card"
    val data = object {
        val number = cardNumberElement
        val expiration_month = cardExpirationDateElement.month()
        val expiration_year = cardExpirationDateElement.year()
        val cvc = cardVerificationCodeElement
    }
})

The month() and year() functions expose a reference object that can only be resolved back to the original values by the BasisTheoryElements service when tokenizing. These methods do not provide your application with direct access to the underlying plaintext values.

Before SDK version 3.0.0 the month() and year() methods rendered as String when sending the value to the API. As of version 3.0.0, these methods now render as Int when sending the value to the API.

Also, format(dateFormat: String) allows you to customize card expiration dates. It implements Java's DateTimeFormatter, so all date formats supported by it are also available.

// cardExpirationDateElement value is 04/25

val response = bt.client.post(object {
    val data = object {
        val expiration_date1 = cardExpirationDateElement.format("yyyy-MM"), // 2025-04
        val expiration_date2 = cardExpirationDateElement.format("MM"),      // 04
        val expiration_date3 = cardExpirationDateElement.format("M"),       // 4
        val expiration_date4 = cardExpirationDateElement.format("MM/yyyy"), // 04/2025
        val expiration_date5 = cardExpirationDateElement.format("yy"),      // 25
    }
})

This code example uses Basis Theory HTTP Client

Configuration

The CardExpirationDateElement extends the TextElement view, so all properties and attributes supported by TextElement are also supported here.

By default, this element is configured with:

The keyboard is configured to only allow numeric input
A mask is applied to format input values as MM/yy
The FutureDateValidator is applied to restrict input to future dates

This component fully supports the same style customizations to match your branding that are supported on the base TextElement.

Additional Methods Supported

Signature	Description
`month(): ElementValueReference`	Returns a value reference to the two-digit expiration month.
`year(): ElementValueReference`	Returns a value reference to the four-digit expiration year.
`format(dateFormat: String): ElementValueReference`	Returns a value reference to the expiration date formatted according to the provided `dateFormat`.
`setValueRef(monthRef: ElementValueReference, yearRef: ElementValueReference)`	Sets the expiration date to the value referenced by the provided references.

CardVerificationCodeElement

The CardVerificationCodeElement can be used to securely collect credit card CVC values within your application. This element will render a text input within your view that accepts either a 3 or 4 digit CVC (the length is determined by the card brand).

This element was designed to be used in conjunction with the CardNumberElement and CardExpirationDateElement to collect and tokenize a card token.

Basic Usage

To use the CardVerificationCodeElement within your Android application, simply include the view within one of your Android application’s layouts.

<com.basistheory.android.view.CardVerificationCodeElement
    android:id="@+id/cvc"
    android:layout_width="match_parent"
    android:layout_height="wrap_content" />

You can optionally bind a CardNumberElement to your CardVerificationCodeElement to automatically enforce the CVC length validation corresponding to the entered card brand.

val cardNumberElement = findViewById<CardNumberElement>(R.id.card_number)
val cvcElement = findViewById<CardVerificationCodeElement>(R.id.cvc)
cvcElement.cardNumberElement = cardNumberElement // optional binding between these two elements

This element can be referenced directly when tokenizing through the BasisTheoryElements service class:

val tokenizeResponse = bt.tokenize(object {
    val type = "card"
    val data = object {
        val number = cardNumberElement
        val expiration_month = cardExpirationDateElement.month()
        val expiration_year = cardExpirationDateElement.year()
        val cvc = cardVerificationCodeElement
    }
})

Configuration

The CardVerificationCodeElement extends the TextElement view, so all properties and attributes supported by TextElement are also supported here.

By default, this element is configured with:

The keyboard is configured to only allow numeric input
A 3 digit mask is applied by default, but this may be automatically changed to a 4 digit mask based on the card brand

This component fully supports the same style customizations to match your branding that are supported on the base TextElement.

Android Element Types

TextElement​

Basic Usage​

Configuration​

Properties​

Methods​

XML Attributes​

CardNumberElement​

Basic Usage​

Configuration​

Card Brands​

CardMetadata​

ChangeEvent Details​

CardExpirationDateElement​

Basic Usage​

Configuration​

Additional Methods Supported​

CardVerificationCodeElement​

Basic Usage​

Configuration​

TextElement

Basic Usage

Configuration

Properties

Methods

XML Attributes

CardNumberElement

Basic Usage

Configuration

Card Brands

CardMetadata

ChangeEvent Details

CardExpirationDateElement

Basic Usage

Configuration

Additional Methods Supported

CardVerificationCodeElement

Basic Usage

Configuration