Co-Badge Support

Some cards carry more than one payment network — for example a domestic network alongside Visa or Mastercard. Co-badge support lets the cardNumber and card elements detect these networks and choose, or let the user choose, which one processes the payment.

This is distinct from co-brand detection: co-brand detection resolves which brand a partially typed number belongs to (for example Mastercard vs. Maestro), while co-badging selects between the multiple networks a fully identified card supports.

---

How networks are detected

Network detection relies on BIN enrichment — a lookup based on the card's BIN (the first six digits). Enrichment is enabled by either of two options:

• binLookup — turns BIN enrichment on.
• coBadge — configures network selection. Setting it enables BIN enrichment automatically, so you do not also need to set binLookup.

When enrichment is active and the card participates in more than one network, the change event reports the available networks and the selectedNetwork.

When the card is tokenized, additional card brands are returned in the Token's card.additional array. For a Cartes Bancaires co-badge, an entry has brand set to cartes-bancaires.

binLookup

binLookup turns BIN enrichment on. It is not specific to co-badging — enrichment also returns the issuer metadata described in BIN enrichment. You only need it here if you want to tune debounceMs, since setting coBadge enables enrichment on its own.

coBadge

Use coBadge when you want to control which network is selected, or render a selector for the user.

Field	Type	Description
preferredNetworks	string[]	Priority order used to pick the network automatically. The first available network that matches is selected. When omitted, a default priority order is used: visa, mastercard, amex, discover, jcb, diners, cartes-bancaires, unionpay, elo, maestro, mir, hiper, hipercard. If nothing in the list matches the card's networks, the first network in the enrichment response is selected.
mode	'auto' | 'manual'	'auto' (default) selects a network automatically using preferredNetworks. 'manual' renders a built-in network selector inside the element for the user to choose.

const cardNumberEl = bt.createElement('cardNumber', {
  coBadge: {
    preferredNetworks: ['cartes-bancaires', 'visa'],
    mode: 'auto',
  },
});

await cardNumberEl.mount('#card-number-container');

Network identifiers are lowercase, kebab-case strings — for example visa and cartes-bancaires. Matching against preferredNetworks and setNetwork() is case-insensitive.

---

Reading the selected network

When enrichment is active, the change event adds two fields to event.detail:

Field	Type	Description
networks	string[]	Payment networks the card participates in. Populated only for multi-network (co-badged) cards.
selectedNetwork	string	The currently selected network, when the card participates in more than one.

For a co-badged card, event.detail looks like this:

{
  isValid: true,
  isEmpty: false,
  error: null,
  cardBrand: 'visa',
  last4: '0008',
  bin: '403550',
  cvvLengths: [3],
  potentialBrands: ['visa'],
  matchStrength: 1,
  networks: ['visa', 'cartes-bancaires'],
  selectedNetwork: 'cartes-bancaires',
}

cardNumberEl.on('change', (event) => {
  const { networks, selectedNetwork } = event.detail;

  if (networks && networks.length > 1) {
    // Co-badged card — surface the selected network
    console.log('Available networks:', networks, 'selected:', selectedNetwork);
  }
});

---

The networkChanged event

The networkChanged event fires whenever the selected network changes — through automatic selection, the built-in selector, or a call to setNetwork(). Only cardNumber and card elements emit it.

Field	Type	Description
network	string	The newly selected network.
previousNetwork	string	The network selected before this change, if any.
availableNetworks	string[]	All networks the card supports.
selectionMode	'auto' | 'user'	How the selection was made: 'auto' for automatic selection, or 'user' when the user picks a network via the built-in selector or setNetwork.

When the user switches from Visa to Cartes Bancaires, event.detail looks like this:

{
  network: 'cartes-bancaires',
  previousNetwork: 'visa',
  availableNetworks: ['visa', 'cartes-bancaires'],
  selectionMode: 'user',
}

Web Elements

cardNumberEl.on('networkChanged', (event) => {
  const { network, availableNetworks } = event.detail;
  console.log('Network is now', network, 'of', availableNetworks);
});

React Elements

import { CardNumberElement } from '@basis-theory/react-elements';

<CardNumberElement
  id="card-number"
  coBadge={{ preferredNetworks: ['cartes-bancaires', 'visa'] }}
  onNetworkChanged={(event) => {
    const { network, availableNetworks } = event.detail;
    console.log('Network is now', network, 'of', availableNetworks);
  }}
/>

---

Build your own network picker

With mode: 'manual' the element renders a built-in selector. To render your own selector instead, read networks from the change event to populate your UI, then call setNetwork() to apply the user's choice. setNetwork() requires the element to be mounted.

Web Elements

// When the user picks a network in your UI:
await cardNumberEl.setNetwork('cartes-bancaires');

React Elements

setNetwork is exposed on the element ref:

import { useRef } from 'react';
import { CardNumberElement } from '@basis-theory/react-elements';

function PaymentForm() {
  const cardNumberRef = useRef(null);

  const chooseNetwork = (network) => cardNumberRef.current?.setNetwork(network);

  return (
    <CardNumberElement
      ref={cardNumberRef}
      coBadge={{ mode: 'auto', preferredNetworks: ['cartes-bancaires', 'visa'] }}
    />
  );
}