Skip to main content

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:

NameTypeDescription
hintStringPlaceholder text to display within the element when empty.
hintTextColorIntA 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.
isCompleteBooleanWhether this element satisfies the mask and validator, i.e. it is ready to be tokenized.
isEditableBooleanWhether this element is editable or readonly.
isEmptyBooleanWhether this element is empty.
isMaskSatisfiedBooleanWhether this element satisfies the length and format requirements of the mask, if defined. Defaults to true if this element does not have a mask.
isValidBooleanThe result of this element's validator, if defined. Defaults to true if this element does not have a validator.
inputTypeInputTypeIndicates which type of virtual keyboard to display while editing and how to display data entered into the Element. See Input Types for details.
maskElementMaskRestricts and formats input entered into this Element. See the Mask options for details.
removeDefaultStylesBooleanRemoves the default Android styling on the underlying EditText. Defaults to true.
textColorIntA 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.
textSizeFloatThe font size, in pixels.
typefaceTypefaceThe Typeface that is used to style the text.
transformElementTransformTransforms the value of this Element prior to tokenization. See the Transform options for details.
validatorElementValidatorValidates the value of this Element. See the Validator options for details.

Methods

SignatureDescription
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:

NameTypeDescription
android:enabledbooleanWhether this element is editable or readonly.
android:hintStringPlaceholder text to display within the Element.
android:inputTypeenumIndicates which type of virtual keyboard to display while editing and how to display data entered into the Element. See Input Types for details.
android:textstringSets the text value for the element. Note that a getter is not exposed on the TextElement to retrieve the underlying text value.
android:textColorreference|colorThe 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:textColorHintreference|colorThe 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:textSizedimensionThe size of text.
android:typefaceenumThe typeface (normal, sans, serif, monospace) for the text. To fully customize the font family and text style, set TextElement.typeface programmatically.
bt_maskstringA string defining the mask applied to this Element, e.g. (###-##-####).
bt_removeDefaultStylesbooleanRemoves 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:

BrandIdentifierCard Number DigitsCVC Digits
American Expressamerican-express154
Diners Clubdiners-club14, 16, 193
Discoverdiscover16, 193
Eloelo163
Hiperhiper163
HiperCardhipercard163
JCBjcb16-193
Maestromaestro12-193
Mastercardmastercard163
MIRmir16-193
UnionPayunionpay14-193
Visavisa16, 18, 193
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:

NameTypeDescription
cardMetadataCardMetadataGets metadata about the card, derived from user input.

The CardMetadata object contains the properties:

NameTypeDescription
brandStringThe card brand identifier
binStringThe 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.
last4StringThe 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.

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

SignatureDescription
month(): ElementValueReferenceReturns a value reference to the two-digit expiration month.
year(): ElementValueReferenceReturns a value reference to the four-digit expiration year.
format(dateFormat: String): ElementValueReferenceReturns 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
}
})

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