Co-Badge Support

Co-badge support allows the Card Number Element to handle cards that support multiple payment networks, giving users the ability to choose which network to use for processing their payment. This feature is particularly important in regions where co-branded cards are common.

Overview

When a card supports multiple payment networks (co-badged), the Card Number Element can detect this and allow users to select their preferred network. Currently, Basis Theory supports co-badge functionality for Cartes Bancaires cards, which are commonly co-badged with Visa or Mastercard in France.

Enabling Co-Badge Support

To enable co-badge support on your CardNumberElement, set the coBadgedSupport property:

import com.basistheory.android.view.CardNumberElement
import com.basistheory.android.view.CardBrandSelector
import com.basistheory.elements.constants.CoBadgedSupport

// Configure card number element with co-badge support
val cardNumberElement = findViewById<CardNumberElement>(R.id.card_number)
cardNumberElement.coBadgedSupport = listOf(CoBadgedSupport.CARTES_BANCAIRES)

// Configure the BasisTheoryElements service
cardNumberElement.setBasisTheoryElements(bt)

// Configure brand selector
val cardBrandSelector = findViewById<CardBrandSelector>(R.id.card_brand_selector)
cardBrandSelector.setCardNumberElement(cardNumberElement)

Card Brand Selector

The CardBrandSelector component provides a UI for users to select their preferred payment network when multiple brands are detected. This component automatically shows and hides based on whether co-badged card brands are available.

XML Layout

<LinearLayout
    xmlns:android="http://schemas.android.com/apk/res/android"
    android:layout_width="match_parent"
    android:layout_height="wrap_content"
    android:orientation="vertical">

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

    <com.basistheory.android.view.CardBrandSelector
        android:id="@+id/card_brand_selector"
        android:layout_width="match_parent"
        android:layout_height="wrap_content"
        android:visibility="gone" />

</LinearLayout>

Basic Setup

import com.basistheory.android.view.CardNumberElement
import com.basistheory.android.view.CardBrandSelector
import com.basistheory.elements.constants.CoBadgedSupport
import com.basistheory.elements.service.BasisTheoryElements

class PaymentActivity : AppCompatActivity() {
    private lateinit var cardNumberElement: CardNumberElement
    private lateinit var cardBrandSelector: CardBrandSelector
    private lateinit var bt: BasisTheoryElements

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContentView(R.layout.activity_payment)

        // Initialize BasisTheoryElements
        bt = BasisTheoryElements.builder()
            .apiKey("<PUBLIC_API_KEY>")
            .build()

        // Configure card number element
        cardNumberElement = findViewById(R.id.card_number)
        cardNumberElement.coBadgedSupport = listOf(CoBadgedSupport.CARTES_BANCAIRES)
        cardNumberElement.setBasisTheoryElements(bt)

        // Configure brand selector
        cardBrandSelector = findViewById(R.id.card_brand_selector)
        cardBrandSelector.setCardNumberElement(cardNumberElement)
    }
}

CardBrandSelector

The CardBrandSelector is a specialized component that:

• Automatically displays when multiple card brands are detected
• Hides when only one brand is available or no card number is entered
• Shows available brand options for user selection
• Updates the selected network on the card number element

Configuration

cardBrandSelector.setCardNumberElement(cardNumberElement)

Methods

Method	Description
setCardNumberElement(cardNumberElement: CardNumberElement)	Configures the selector with a card number element

Supported Co-Badge Networks

Network	Identifier	Description
Cartes Bancaires	CoBadgedSupport.CARTES_BANCAIRES	French domestic payment scheme, often co-badged with Visa or Mastercard

Adding unsupported networks will result in an error. Additional co-badge networks may be supported in future releases.

Element Events

When co-badge support is enabled, the Card Number Element emits additional event data that allows your application to respond to network selection changes.

The CardNumberElement emits change events that include the selectedNetwork property when co-badge support is enabled:

cardNumberElement.addChangeEventListener { event ->
    println("Complete: ${event.complete}")
    println("Valid: ${event.valid}")
    
    event.selectedNetwork?.let { selectedNetwork ->
        println("Selected network: $selectedNetwork")
    }
}

ChangeEvent Properties

When co-badge support is enabled, the ChangeEvent includes:

Property	Type	Description
complete	Boolean	false until a brand is selected for co-badged cards
selectedNetwork	String?	The selected network identifier (e.g., "cartes-bancaires", "visa")

The complete property will be false for valid co-badged cards until the user selects a network, even if the card number is valid and satisfies the mask.

Complete Example

import android.os.Bundle
import android.widget.Button
import androidx.appcompat.app.AppCompatActivity
import com.basistheory.android.view.CardNumberElement
import com.basistheory.android.view.CardExpirationDateElement
import com.basistheory.android.view.CardVerificationCodeElement
import com.basistheory.android.view.CardBrandSelector
import com.basistheory.elements.constants.CoBadgedSupport
import com.basistheory.elements.service.BasisTheoryElements

class CobadgePaymentActivity : AppCompatActivity() {
    private lateinit var cardNumberElement: CardNumberElement
    private lateinit var cardExpirationElement: CardExpirationDateElement
    private lateinit var cardCvcElement: CardVerificationCodeElement
    private lateinit var cardBrandSelector: CardBrandSelector
    private lateinit var submitButton: Button
    private lateinit var bt: BasisTheoryElements

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContentView(R.layout.activity_cobadge_payment)

        // Initialize BasisTheoryElements
        bt = BasisTheoryElements.builder()
            .apiKey("<PUBLIC_API_KEY>")
            .build()

        // Initialize views
        cardNumberElement = findViewById(R.id.card_number)
        cardExpirationElement = findViewById(R.id.card_expiration)
        cardCvcElement = findViewById(R.id.card_cvc)
        cardBrandSelector = findViewById(R.id.card_brand_selector)
        submitButton = findViewById(R.id.submit_button)

        // Configure card number element with co-badge support
        cardNumberElement.coBadgedSupport = listOf(CoBadgedSupport.CARTES_BANCAIRES)
        cardNumberElement.setBasisTheoryElements(bt)

        // Configure brand selector
        cardBrandSelector.setCardNumberElement(cardNumberElement)

        // Listen for element changes
        cardNumberElement.addChangeEventListener { event ->
            // Update UI based on completion state
            submitButton.isEnabled = event.complete

            event.selectedNetwork?.let { selectedNetwork ->
                println("User selected: $selectedNetwork")
            }
        }

        // Submit button handler
        submitButton.setOnClickListener {
            tokenizeCard()
        }
    }

    private fun tokenizeCard() {
        val tokenizeResponse = bt.tokenize(object {
            val type = "card"
            val data = object {
                val number = cardNumberElement
                val expiration_month = cardExpirationElement.month()
                val expiration_year = cardExpirationElement.year()
                val cvc = cardCvcElement
            }
        })

        println("Token created: $tokenizeResponse")
    }
}

Test Cards

Within a Test Tenant, the following test cards can be used to test different scenarios when using co-badged features.

These cards are not valid for real transactions and should only be used in a Test Tenant.

Test PAN	International Scheme	Domestic Network	Supported Countries
4000 0000 2222 2220	Visa	Cartes Bancaires	France
5555 5500 9999 9999	Mastercard	Cartes Bancaires	France

API Reference

CardNumberElement Properties

Property	Type	Required	Default	Description
coBadgedSupport	List<CoBadgedSupport>?	No	null	List of supported co-badge networks
selectedNetwork	String?	No	null	The currently selected network (read-only)

CoBadgedSupport Enum

enum class CoBadgedSupport(val value: String) {
    CARTES_BANCAIRES("cartes-bancaires")
}

Related Topics

• Android Elements Types - Learn about all available Android element types
• Android Elements Events - Handle element events
• Android Elements Services - Tokenize data with elements