Display detected card network

Display the detected card network (Visa, Mastercard, etc.) as users enter their card number.

Recipe

Web
Android
iOS

checkout.addEventListener('primer:bin-data-available', (event) => {
  const { preferred, status } = event.detail;

  if (preferred) {
    document.getElementById('card-logo').src = `/images/${preferred.network.toLowerCase()}.svg`;
  }
});

val controller = rememberCardFormController(checkout)
val state by controller.state.collectAsStateWithLifecycle()

val detected = state.networkSelection.selectedNetwork

if (detected != null) {
    Text(text = detected.displayName)
}

PrimerCardForm displays the card brand icon automatically in the card number field. Custom rendering is optional — use state.networkSelection only if you need to display the network outside the card form.

struct CardFormWithNetwork: View {
  var body: some View {
    PrimerCardForm(cardDetails: { session in
      CardDetailsWithNetwork(session: session)
    })
  }
}

struct CardDetailsWithNetwork: View {
  @ObservedObject var session: PrimerCardFormSession

  var body: some View {
    HStack {
      CardFormDefaults.cardNumber(session)
      if let network = session.state.availableNetworks.first {
        Text(network.displayName)
          .font(.caption)
          .padding(4)
          .background(Color(.secondarySystemBackground))
          .cornerRadius(4)
      }
    }
  }
}

PrimerCardForm displays the card brand icon automatically in the card number field. Read session.state.availableNetworks only if you need to display the network outside the card form. For a single-network card, the detected network is availableNetworks.first; selectedNetwork is reserved for co-badge selection and stays nil while the network is auto-detected.

How it works

Web
Android
iOS

Listen for the primer:bin-data-available event
Use preferred.network to get the card brand identifier
Update your UI with the appropriate logo or icon

Create a PrimerCardFormController using rememberCardFormController()
Observe its state with collectAsStateWithLifecycle()
Read state.networkSelection.selectedNetwork for the currently detected network
The state updates reactively as the user types — no event listener needed

Property	Type	Description
`selectedNetwork`	`PrimerCardNetwork?`	Currently detected network, or `null`
`availableNetworks`	`List<PrimerCardNetwork>`	All selectable networks (for co-badged cards)
`isNetworkSelectable`	`Boolean`	`true` when the card has multiple networks

Mark the PrimerCardFormSession injected into your slot closure as @ObservedObject
Read session.state.availableNetworks for the detected networks (use availableNetworks.first for the single-network case)
Use session.state.selectedNetwork only for the co-badge choice (it is nil while the network is auto-detected)
The state updates reactively as the user types — no event listener needed

Property	Type	Description
`availableNetworks`	`[PrimerCardNetwork]`	Networks detected from the card number. More than one indicates a co-badged card.
`selectedNetwork`	`PrimerCardNetwork?`	Currently selected co-badge network, or `nil` while auto-detected

The preferred field contains the recommended card network based on orderedAllowedCardNetworks. It is undefined when no network is detected (e.g., empty input or insufficient digits).

The preferred object

Web
Android
iOS

The preferred object contains the detected card network and, when status is 'complete', additional issuer details:

{
  displayName: string;  // Human-readable name (e.g., "Visa", "American Express")
  network: string;      // Backend identifier (e.g., "VISA", "AMEX")
  allowed: boolean;     // Whether the network is allowed per orderedAllowedCardNetworks
  // Available when status is 'complete':
  issuerCountryCode?: string;
  issuerName?: string;
  accountFundingType?: string;
}

See the Events Reference for the full BinDataDetails type definition.

data class PrimerCardNetwork(
    val network: CardNetwork.Type,
    val displayName: String,
    val allowed: Boolean,
)

selectedNetwork is null when no card network is detected. Android uses the CardNetwork.Type enum with a displayName property.

@objc
public final class PrimerCardNetwork: NSObject {
    public let displayName: String   // Human-readable name (e.g. "Visa")
    public let network: CardNetwork  // String-backed enum (.visa, .masterCard, ...)
    public let allowed: Bool         // Enabled for the current merchant configuration
}

The detected network comes from availableNetworks (use availableNetworks.first for the single-network case); it is empty when no card network is detected. selectedNetwork is reserved for the co-badge choice and stays nil while the network is auto-detected. iOS exposes PrimerCardNetwork with a displayName string property and a network (CardNetwork) enum whose raw value matches the backend identifier (e.g. "VISA").

Supported card networks

`network`	Web / Android `displayName`	iOS `displayName`
`VISA`	Visa	Visa
`MASTERCARD`	Mastercard	Mastercard
`AMEX`	American Express	American Express
`DISCOVER`	Discover	Discover
`DINERS_CLUB`	Diners Club	Diners
`JCB`	JCB	JCB
`MAESTRO`	Maestro	Maestro
`UNIONPAY`	UnionPay	UnionPay
`ELO`	Elo	Elo
`HIPER`	Hiper	Hiper
`HIPERCARD`	Hipercard	Hiper
`MIR`	Mir	Mir
`CARTES_BANCAIRES`	Cartes Bancaires	Cartes Bancaires
`BANCONTACT`	—	Bancontact
`DANKORT`	Dankort	— (not in iOS `CardNetwork`)
`EFTPOS`	Eftpos	EFTPOS
`OTHER`	Other	Unknown

On Android, these are values of the CardNetwork.Type enum, each with a displayName property. On iOS, the network raw values map to cases of the CardNetwork enum; a few display names and the supported set differ (iOS has no DANKORT and adds BANCONTACT). See PrimerCardNetwork for the authoritative iOS list.

Variations

Show a loading indicator

Use primer:bin-data-loading-change to indicate when BIN data is being fetched:

checkout.addEventListener('primer:bin-data-loading-change', (event) => {
  const { loading } = event.detail;
  document.getElementById('card-logo').style.opacity = loading ? '0.5' : '1';
});

Display card network name

Web
Android
iOS

For user-facing text, use displayName instead of network:

checkout.addEventListener('primer:bin-data-available', (event) => {
  const { preferred } = event.detail;

  const networkName = preferred?.displayName || 'Card';
  document.getElementById('card-type-label').textContent = networkName;
});

val controller = rememberCardFormController(checkout)
val state by controller.state.collectAsStateWithLifecycle()

val networkName = state.networkSelection.selectedNetwork?.displayName ?: "Card"
Text(text = "Paying with $networkName")

let networkName = session.state.availableNetworks.first?.displayName ?? "Card"
Text("Paying with \(networkName)")

Show/hide based on detection

Web
Android
iOS

const cardLogo = document.getElementById('card-logo');

checkout.addEventListener('primer:bin-data-available', (event) => {
  const { preferred } = event.detail;

  if (preferred) {
    cardLogo.src = `/images/${preferred.network.toLowerCase()}.svg`;
    cardLogo.style.display = 'block';
  } else {
    cardLogo.style.display = 'none';
  }
});

val controller = rememberCardFormController(checkout)
val state by controller.state.collectAsStateWithLifecycle()

val detected = state.networkSelection.selectedNetwork

AnimatedVisibility(visible = detected != null) {
    if (detected != null) {
        Text(text = detected.displayName)
    }
}

@ObservedObject var session: PrimerCardFormSession

var body: some View {
  VStack {
    if let network = session.state.availableNetworks.first {
      Text(network.displayName)
        .transition(.opacity)
    }
    CardFormDefaults.cardNumber(session)
  }
  .animation(.default, value: session.state.availableNetworks.isEmpty)
}

Co-badge network selector

Web
Android
iOS

Some cards support multiple networks (e.g., Carte Bancaire / Visa). Use alternatives to offer a network picker:

checkout.addEventListener('primer:bin-data-available', (event) => {
  const { preferred, alternatives } = event.detail;
  const cobrandEl = document.getElementById('cobrand-selector');

  if (preferred) {
    document.getElementById('card-logo').src = `/images/${preferred.network.toLowerCase()}.svg`;
  }

  const selectableNetworks = [preferred, ...alternatives].filter(n => n?.allowed);
  cobrandEl.hidden = selectableNetworks.length <= 1;
});

val controller = rememberCardFormController(checkout)
val state by controller.state.collectAsStateWithLifecycle()
val networkSelection = state.networkSelection

if (networkSelection.isNetworkSelectable && networkSelection.availableNetworks.size > 1) {
    NetworkSelector(
        networks = networkSelection.availableNetworks,
        selected = networkSelection.selectedNetwork,
        onSelect = { network -> controller.selectCardNetwork(network) },
    )
}

PrimerCardForm renders a dropdown selector for co-badged cards automatically. Use selectCardNetwork() only if building a fully custom card form.

When a card supports multiple networks, session.state.availableNetworks contains all options. Render your own picker and commit the choice with session.selectCardNetwork(_:):

@ObservedObject var session: PrimerCardFormSession

var body: some View {
  let networks = session.state.availableNetworks
  if networks.count > 1 {
    HStack {
      ForEach(networks, id: \.network) { network in
        Button(network.displayName) {
          session.selectCardNetwork(network)
        }
        .buttonStyle(.bordered)
        .disabled(!network.allowed)
      }
    }
  }
}

PrimerCardForm renders a dropdown selector for co-badged cards automatically. When you recompose the individual card fields yourself, drop in CardFormDefaults.cardNetwork(session) for the built-in selector, or call selectCardNetwork() directly only if building a fully custom one.

Use icon font or CSS classes

checkout.addEventListener('primer:bin-data-available', (event) => {
  const { preferred } = event.detail;
  const iconEl = document.getElementById('card-icon');

  if (preferred) {
    iconEl.classList.add(`card-${preferred.network.toLowerCase()}`);
  }
});

Build a custom card form

Step-by-step guide to building a fully custom card form

Events guide

Handle payment lifecycle events

Use BIN data for Click to Pay

Control Click to Pay based on BIN data

​Recipe

​How it works

​The preferred object

​Supported card networks

​Variations

​Show a loading indicator

​Display card network name

​Show/hide based on detection

​Co-badge network selector

​Use icon font or CSS classes

​See also

Build a custom card form

Events guide

Use BIN data for Click to Pay

Recipe

How it works

The preferred object

Supported card networks

Variations

Show a loading indicator

Display card network name

Show/hide based on detection

Co-badge network selector

Use icon font or CSS classes

See also