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