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 { CardNumberElement, CoBadgedSupport } from '@basis-theory/basis-theory-react-native';

export default function PaymentForm() {
  const cardNumberRef = useRef<BTRef>(null);

  const handleCardNumberChange = (event: ChangeEvent) => {
    // Selected network is available in the event when user selects a brand
    if (event.selectedNetwork) {
      console.log('Selected network:', event.selectedNetwork);
    }
  };

  return (
    <CardNumberElement
      btRef={cardNumberRef}
      coBadgedSupport={[CoBadgedSupport.CartesBancaires]}
      onChange={handleCardNumberChange}
      placeholder="Card Number"
    />
  );
}

The brand selector UI is automatically rendered by the CardNumberElement when multiple brands are detected. You don't need to manually add a separate picker component.

Brand Selection

When co-badge support is enabled and a co-badged card is detected, the CardNumberElement automatically renders a brand selector UI above the input field. This allows users to choose their preferred payment network.

The brand selector:

• Automatically appears when multiple brands are detected
• Displays available brand options in a modal picker
• Updates the selectedNetwork property when a brand is selected
• Automatically hides when the card number is cleared or changed to a non-co-badged card

The brand selector is an internal component of CardNumberElement. You don't need to import or configure it separately - it's automatically managed based on the coBadgedSupport configuration.

Supported Co-Badge Networks

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

const handleCardNumberChange = (event: ChangeEvent) => {
  console.log('Complete:', event.complete);
  console.log('Valid:', event.valid);
  
  // Selected network after user selection
  if (event.selectedNetwork) {
    console.log('Selected network:', event.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	CardBrand?	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 React, { useRef, useState } from 'react';
import { View, Button, StyleSheet } from 'react-native';
import {
  CardNumberElement,
  CardExpirationDateElement,
  CardVerificationCodeElement,
  CoBadgedSupport,
  useBasisTheory,
  type BTRef,
  type ChangeEvent,
} from '@basis-theory/basis-theory-react-native';

export default function CobadgePaymentForm() {
  const { bt } = useBasisTheory('<PUBLIC_API_KEY>');
  const cardNumberRef = useRef<BTRef>(null);
  const cardExpirationRef = useRef<BTRef>(null);
  const cardCvcRef = useRef<BTRef>(null);
  
  const [isComplete, setIsComplete] = useState(false);

  const handleCardNumberChange = (event: ChangeEvent) => {
    // Update completion state
    setIsComplete(event.complete);
    
    // Log selected network
    if (event.selectedNetwork) {
      console.log('User selected:', event.selectedNetwork);
    }
  };

  const handleSubmit = async () => {
    if (!isComplete) {
      console.log('Please complete the form');
      return;
    }

    try {
      const token = await bt?.tokens.create({
        type: 'card',
        data: {
          number: cardNumberRef.current,
          expiration_month: cardExpirationRef.current?.month(),
          expiration_year: cardExpirationRef.current?.year(),
          cvc: cardCvcRef.current,
        },
      });
      
      console.log('Token created:', token);
    } catch (error) {
      console.error('Tokenization error:', error);
    }
  };

  return (
    <View style={styles.container}>
      <CardNumberElement
        btRef={cardNumberRef}
        coBadgedSupport={[CoBadgedSupport.CartesBancaires]}
        onChange={handleCardNumberChange}
        placeholder="Card Number"
        style={styles.input}
      />
      
      <CardExpirationDateElement
        btRef={cardExpirationRef}
        placeholder="MM/YY"
        style={styles.input}
      />
      
      <CardVerificationCodeElement
        btRef={cardCvcRef}
        placeholder="CVC"
        style={styles.input}
      />
      
      <Button
        title="Submit Payment"
        onPress={handleSubmit}
        disabled={!isComplete}
      />
    </View>
  );
}

const styles = StyleSheet.create({
  container: {
    padding: 20,
  },
  input: {
    borderWidth: 1,
    borderColor: '#ccc',
    borderRadius: 4,
    padding: 12,
    marginBottom: 12,
    fontSize: 16,
  },
});

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 Props

Property	Type	Required	Default	Description
coBadgedSupport	CoBadgedSupport[]?	No	undefined	Array of supported co-badge networks

CoBadgedSupport Enum

enum CoBadgedSupport {
  CartesBancaires = 'cartes-bancaires'
}

Related Topics

• React Native Components - Learn about all available React Native element components
• React Native Services - Tokenize data with elements