Element Events

Each element type supports a standard set of events that can be subscribed to in order to receive callbacks within your application.

ChangeEvent

Raised whenever the element's value is changed, upon each keypress and after pasting multiple characters into the element.

Schema

Property	Type	Description
isComplete	Boolean	Whether this element satisfies the mask and validator, i.e. it is ready to be tokenized.
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.
details	List<EventDetails>	A list of EventDetails included with this event
binDetails	BinDetails?	BinDetails object containing card BIN details when binLookup is enabled on CardNumberElement.
selectedNetwork	String?	The selected payment network for co-badged cards (e.g., "cartes-bancaires", "visa"). Only present when co-badge support is enabled.

EventDetails

Property	Type	Description
type	String	The type of data represented by this detail object
message	String	The content of this detail object

Usage

myElement.addChangeEventListener {
    // handle event
}

FocusEvent

Raised whenever the element receives focus.

Schema

Empty

Usage

myElement.addFocusEventListener {
    // handle event
}

BlurEvent

Raised whenever the element loses focus.

Schema

Empty

Usage

myElement.addBlurEventListener {
    // handle event
}

CopyEvent

Raised whenever the element's value is copied to the clipboard. This event is available on all element types (TextElement, CardNumberElement, CardExpirationDateElement, CardVerificationCodeElement) when the enableCopy option is set to true.

Schema

Empty

Enabling Copy

To enable the copy functionality on an element, set enableCopy to true. This displays a copy icon that users can tap to copy the element's value to the clipboard:

val cardNumberElement = findViewById<CardNumberElement>(R.id.card_number)
cardNumberElement.enableCopy = true
cardNumberElement.copyIconColor = Color.BLUE // Optional: customize the copy icon color

You can also trigger a copy programmatically using the performCopy() method:

val success = cardNumberElement.performCopy() // Returns true if copy was performed, false if enableCopy is disabled

Usage

cardNumberElement.addCopyEventListener {
    // handle event - triggered when value is copied to clipboard
    println("Card number copied to clipboard")
    showCopiedConfirmation()
}

Example with TextElement

val textElement = findViewById<TextElement>(R.id.text_element)
textElement.enableCopy = true

textElement.addCopyEventListener {
    Toast.makeText(context, "Value copied!", Toast.LENGTH_SHORT).show()
}

BinDetails

When binLookup is enabled on a CardNumberElement, the element will automatically perform a BIN lookup and include the results in the binDetails property of the ChangeEvent. This provides detailed information about the card based on its BIN (Bank Identification Number).

BinDetails Properties

Property	Type	Description
brand	String?	The card brand (e.g., "visa", "mastercard")
funding	String?	The funding type (e.g., "credit", "debit", "prepaid")
issuer	String?	The name of the issuing bank
segment	String?	The card segment type
binRange	List<BinRange>?	List of BIN ranges for the primary card brand
additional	List<AdditionalCardDetail>?	List of additional card information for co-badged cards

AdditionalCardDetail Properties

Property	Type	Description
brand	String?	Additional card brand for co-badged cards
funding	String?	Funding type for the additional brand
issuer	String?	Issuer for the additional brand
segment	String?	Segment for the additional brand
binRange	List<BinRange>?	BIN ranges for the additional brand

BinRange Properties

Property	Type	Description
binMin	String	Minimum BIN value in the range
binMax	String	Maximum BIN value in the range

Enabling BIN Lookup

To enable BIN lookup on a CardNumberElement:

val cardNumberElement = findViewById<CardNumberElement>(R.id.card_number)
cardNumberElement.binLookup = true
cardNumberElement.setBasisTheoryElements(bt)

Usage Example

cardNumberElement.addChangeEventListener { event ->
    event.binDetails?.let { binDetails ->
        println("Card brand: ${binDetails.brand ?: "unknown"}")
        println("Funding type: ${binDetails.funding ?: "unknown"}")
        println("Issuer: ${binDetails.issuer ?: "unknown"}")
        
        // Check for co-badged cards
        binDetails.additional?.let { additional ->
            if (additional.isNotEmpty()) {
                println("Co-badged card detected")
                additional.forEach { cardDetail ->
                    println("Additional brand: ${cardDetail.brand ?: "unknown"}")
                }
            }
        }
    }
}