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. Basis Theory supports co-badge functionality for the following domestic payment schemes:

• Cartes Bancaires - French domestic payment network, commonly co-badged with Visa or Mastercard
• Bancontact - Belgian domestic payment network, commonly co-badged with Mastercard
• Dankort - Danish domestic payment network, commonly co-badged with Visa

Enabling Co-Badge Support

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

import React, { useRef } from 'react';
import {
  CardNumberElement,
  CoBadgedSupport,
  type BTRef,
  type ElementEvent,
} from '@basis-theory/react-native-elements';

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

  const handleCardNumberChange = (event: ElementEvent) => {
    // 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
Bancontact	CoBadgedSupport.Bancontact	Belgian domestic payment scheme, often co-badged with Mastercard
Dankort	CoBadgedSupport.Dankort	Danish domestic payment scheme, often co-badged with Visa

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

Pre-Selected Networks

You can use the preSelectedNetworks property to automatically select a preferred network when a co-badged card is detected. This is useful when you have a preferred domestic network for processing payments.

import React, { useRef } from 'react';
import {
  CardNumberElement,
  CoBadgedSupport,
  type BTRef,
  type ElementEvent,
} from '@basis-theory/react-native-elements';

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

  const handleCardNumberChange = (event: ElementEvent) => {
    if (event.selectedNetwork) {
      console.log('Selected network:', event.selectedNetwork);
    }
  };

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

When preSelectedNetworks is provided:

• The first network from the list that matches an available co-badged option is automatically selected
• Users can still manually change the selection after auto-selection
• If no networks in preSelectedNetworks match the available options, no auto-selection occurs

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: ElementEvent) => {
  console.log('Complete:', event.complete);
  console.log('Valid:', event.valid);

  // Selected network after user selection
  if (event.selectedNetwork) {
    console.log('Selected network:', event.selectedNetwork);
  }
};

ElementEvent Properties

When co-badge support is enabled, the ElementEvent 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 ElementEvent,
} from '@basis-theory/react-native-elements';

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: ElementEvent) => {
    // 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, CoBadgedSupport.Bancontact, CoBadgedSupport.Dankort]}
        preSelectedNetworks={[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.

Cartes Bancaires

Test PAN	International Scheme	Domestic Network	Supported Countries
4000000022222220	Visa	Cartes Bancaires	France
5555550099999999	Mastercard	Cartes Bancaires	France

Bancontact

Test PAN	International Scheme	Domestic Network	Supported Countries
5550009900000005	Mastercard	Bancontact	Belgium

Dankort

Test PAN	International Scheme	Domestic Network	Supported Countries
4571009900000003	Visa	Dankort	Denmark

API Reference

CardNumberElement Props

Property	Type	Required	Default	Description
coBadgedSupport	CoBadgedSupport[]?	No	undefined	Array of supported co-badge networks
preSelectedNetworks	CoBadgedSupport[]?	No	undefined	Ordered array of preferred networks for auto-selection

CoBadgedSupport Enum

enum CoBadgedSupport {
  CartesBancaires = 'cartes-bancaires',
  Bancontact = 'bancontact',
  Dankort = 'dankort'
}

selectedNetwork Event Property

Property	Type	Description
selectedNetwork	CardBrand?	The network selected by the user for co-badged cards

Possible Values:

• 'cartes-bancaires' - When user selects Cartes Bancaires network
• 'bancontact' - When user selects Bancontact network
• 'dankort' - When user selects Dankort network
• 'visa' - When user selects Visa network (for co-badged cards)
• 'mastercard' - When user selects Mastercard network (for co-badged cards)

Related Topics

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