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 CardNumberUITextField, set the coBadgedSupport property:

import BasisTheoryElements

// Create and configure the card number element
let cardNumberTextField = CardNumberUITextField()
cardNumberTextField.coBadgedSupport = [.cartesBancaires]

// Create the card brand selector button
let cardBrandSelector = CardBrandSelectorUIButton()
let options = CardBrandSelectorOptions(cardNumberUITextField: cardNumberTextField)
cardBrandSelector.setConfig(options: options)

Card Brand Selector

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

Basic Setup

import BasisTheoryElements

class PaymentViewController: UIViewController {
    @IBOutlet weak var cardNumberTextField: CardNumberUITextField!
    @IBOutlet weak var cardBrandSelector: CardBrandSelectorUIButton!
    
    override func viewDidLoad() {
        super.viewDidLoad()
        
        // Configure card number element
        cardNumberTextField.coBadgedSupport = [.cartesBancaires]
        
        // Configure brand selector
        let options = CardBrandSelectorOptions(cardNumberUITextField: cardNumberTextField)
        cardBrandSelector.setConfig(options: options)
    }
}

CardBrandSelectorUIButton

The CardBrandSelectorUIButton is a specialized button 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

let options = CardBrandSelectorOptions(cardNumberUITextField: cardNumberTextField)
cardBrandSelector.setConfig(options: options)

Methods

Method	Description
setConfig(options: CardBrandSelectorOptions)	Configures the selector with a card number element

Supported Co-Badge Networks

Network	Identifier	Description
Cartes Bancaires	.cartesBancaires	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 CardNumberUITextField subject emits events that include the selectedNetwork property when co-badge support is enabled:

cardNumberTextField.subject.sink { completion in
} receiveValue: { event in
    print("Complete: \(event.complete)")
    print("Valid: \(event.valid)")
    
    if let selectedNetwork = event.selectedNetwork {
        print("Selected network: \(selectedNetwork)")
    }
}.store(in: &cancellables)

ElementEvent Properties

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

Property	Type	Description
complete	Bool	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 UIKit
import BasisTheoryElements
import Combine

class CobadgePaymentViewController: UIViewController {
    @IBOutlet weak var cardNumberTextField: CardNumberUITextField!
    @IBOutlet weak var cardBrandSelector: CardBrandSelectorUIButton!
    @IBOutlet weak var submitButton: UIButton!
    
    private var cancellables = Set<AnyCancellable>()
    
    override func viewDidLoad() {
        super.viewDidLoad()
        
        // Configure card number element with co-badge support
        cardNumberTextField.coBadgedSupport = [.cartesBancaires]
        
        // Configure brand selector
        let options = CardBrandSelectorOptions(cardNumberUITextField: cardNumberTextField)
        cardBrandSelector.setConfig(options: options)
        
        // Listen for element changes
        cardNumberTextField.subject.sink { completion in
        } receiveValue: { [weak self] event in
            // Update UI based on completion state
            self?.submitButton.isEnabled = event.complete
            
            if let selectedNetwork = event.selectedNetwork {
                print("User selected: \(selectedNetwork)")
            }
        }.store(in: &cancellables)
        
    }
    
    @IBAction func submitPayment(_ sender: UIButton) {
        // Tokenize the card
        let body: [String: Any] = [
            "type": "card",
            "data": [
                "number": cardNumberTextField,
                "expiration_month": expirationDateTextField.month(),
                "expiration_year": expirationDateTextField.year(),
                "cvc": cvcTextField
            ]
        ]
        
        BasisTheoryElements.tokenize(body: body, apiKey: "<PUBLIC_API_KEY>") { data, error in
            if let error = error {
                print("Tokenization error: \(error)")
            } else {
                print("Token created: \(data)")
            }
        }
    }
}

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

CardNumberUITextField Properties

Property	Type	Required	Default	Description
coBadgedSupport	[CoBadgedSupport]?	No	nil	Array of supported co-badge networks
selectedNetwork	String?	No	nil	The currently selected network (read-only)

CoBadgedSupport Enum

public enum CoBadgedSupport: String, CaseIterable {
    case cartesBancaires = "cartes-bancaires"
}

CardBrandSelectorOptions

public struct CardBrandSelectorOptions {
    let cardNumberUITextField: CardNumberUITextField
    
    public init(cardNumberUITextField: CardNumberUITextField)
}

Related Topics

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