> ## Documentation Index
> Fetch the complete documentation index at: https://primer.io/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# PrimerCardNetwork

> Card network type used for co-badged card selection

> [!WARNING]
>
> Primer Checkout iOS SDK is currently in **beta** (v3.0.0-beta.8).
> The API is subject to change before the stable release.

`PrimerCardNetwork` represents a single card network (card scheme) detected from a card number, together with the display information needed to render it. It is the model used in **co-badged card** scenarios — when one physical card carries more than one network (for example Cartes Bancaires + Visa) and the shopper, or your UI, must choose which network to route the payment through.

You read `PrimerCardNetwork` values from [`PrimerCardFormState`](https://primer.io/docs/sdk/ios-checkout/v3.0.0-beta/api/card-form/card-form-session) (`availableNetworks`, `selectedNetwork`, and the BIN metadata in `binData.preferred` / `binData.alternatives`) and commit a choice with [`PrimerCardFormSession.selectCardNetwork(_:)`](https://primer.io/docs/sdk/ios-checkout/v3.0.0-beta/api/card-form/card-form-session).

## Definition

```swift theme={"dark"}
@objc
public final class PrimerCardNetwork: NSObject
```

> [!NOTE]
>
> You never construct `PrimerCardNetwork` yourself. The SDK detects networks from the entered card number and publishes them on `PrimerCardFormState.availableNetworks`. Use those instances directly when calling `selectCardNetwork(_:)`.

## Properties

| Property | Type | Description |
| - | - | - |
| `displayName` | `String` | Human-readable network name for display (e.g. `"Visa"`, `"Mastercard"`, `"Cartes Bancaires"`). |
| `network` | `CardNetwork` | The underlying card network value. See [CardNetwork](#cardnetwork). |
| `allowed` | `Bool` | `true` when this network is enabled for the current merchant configuration. |
| `allowsUserSelection` | `Bool` | `true` when the shopper may choose this network in a co-badged selector. `false` for networks that auto-route (e.g. EFTPOS). |
| `issuerCountryCode` | `String?` | ISO country code of the card issuer, when known. |
| `issuerName` | `String?` | Name of the card issuer, when known. |
| `accountFundingType` | `String?` | Account funding type (e.g. credit/debit), when known. |
| `prepaidReloadableIndicator` | `String?` | Indicator describing whether a prepaid card is reloadable, when known. |
| `productUsageType` | `String?` | Product usage type reported by the network, when known. |
| `productCode` | `String?` | Network product code, when known. |
| `productName` | `String?` | Network product name, when known. |
| `issuerCurrencyCode` | `String?` | ISO currency code associated with the issuer, when known. |
| `regionalRestriction` | `String?` | Regional restriction reported by the network, when known. |
| `accountNumberType` | `String?` | Account number type reported by the network, when known. |

> [!NOTE]
>
> `displayName`, `network`, `allowed`, and `allowsUserSelection` are the properties you need for co-badge selection. The other `String?` properties hold issuer/BIN metadata. They are always `nil` on the instances in `availableNetworks` and `selectedNetwork`. They are filled only on the instances in `PrimerCardFormState.binData` (`preferred` and `alternatives`) after a remote BIN lookup (`binData.status == .complete`). Read issuer details from there.

## CardNetwork

`network` is a `CardNetwork` — a `String`-backed enum identifying the scheme. Its raw value matches the network's canonical uppercase identifier.

```swift theme={"dark"}
public enum CardNetwork: String, Codable, CaseIterable
```

> [!NOTE]
>
> The source declaration also conforms to `LogReporter`, an SDK logging marker protocol that is not meant for merchant use; it is omitted here.

| Case | Raw value | Display name |
| - | - | - |
| `.amex` | `AMEX` | American Express |
| `.bancontact` | `BANCONTACT` | Bancontact |
| `.cartesBancaires` | `CARTES_BANCAIRES` | Cartes Bancaires |
| `.diners` | `DINERS_CLUB` | Diners |
| `.discover` | `DISCOVER` | Discover |
| `.eftpos` | `EFTPOS` | EFTPOS |
| `.elo` | `ELO` | Elo |
| `.hiper` | `HIPER` | Hiper |
| `.hipercard` | `HIPERCARD` | Hiper |
| `.jcb` | `JCB` | JCB |
| `.maestro` | `MAESTRO` | Maestro |
| `.masterCard` | `MASTERCARD` | Mastercard |
| `.mir` | `MIR` | Mir |
| `.visa` | `VISA` | Visa |
| `.unionpay` | `UNIONPAY` | UnionPay |
| `.unknown` | `OTHER` | Unknown |

The enum exposes these public members:

| Member | Type | Description |
| - | - | - |
| `displayName` | `String` | Human-readable network name. |
| `icon` | `UIImage?` | Branded network icon, or `nil` when none is bundled. |
| `traits` | `PrimerCardNetworkTraits?` | PAN length, gap pattern, and CVV metadata for the network, or `nil`. |
| `init(cardNumber: String)` | — | Detects the network from a card number, falling back to `.unknown`. |
| `init(cardNetworkStr: String)` | — | Resolves a network from a string identifier, falling back to `.unknown`. |

## Co-badged card selection

When the entered card number resolves to more than one network, the card form publishes those options on `PrimerCardFormState`. Read them inside any [`PrimerCardForm`](https://primer.io/docs/sdk/ios-checkout/v3.0.0-beta/api/card-form/primer-card-form) slot through the injected [`PrimerCardFormSession`](https://primer.io/docs/sdk/ios-checkout/v3.0.0-beta/api/card-form/card-form-session):

| State property | Type | Description |
| - | - | - |
| `availableNetworks` | `[PrimerCardNetwork]` | Networks detected from the card number. More than one indicates a co-badged card. |
| `selectedNetwork` | `PrimerCardNetwork?` | The network the card form currently applies. This is the network you passed to `selectCardNetwork(_:)`, or the shopper selected, while it stays in `availableNetworks`. Otherwise it is the first available network. `nil` while no network is detected. |

To commit a choice, pass one of the `availableNetworks` instances to the session:

| Method | Description |
| - | - |
| `selectCardNetwork(_ network: PrimerCardNetwork)` | Selects a network for a co-badged card. Applicable only when `availableNetworks` contains more than one network. Only a network picked this way or in the built-in selector is sent as the card's preferred network. When nothing is picked, no preferred network is sent. |

> [!TIP]
>
> Show a selector only when there is a real choice to make — gate it on `availableNetworks.count > 1`. For a single detected network the SDK routes automatically and no selection is needed.

### Building a custom selector

```swift theme={"dark"}
import SwiftUI
import PrimerSDK

@available(iOS 15.0, *)
struct CoBadgedNetworkPicker: View {
    @ObservedObject var session: PrimerCardFormSession

    var body: some View {
        let networks = session.state.availableNetworks
        if networks.count > 1 {
            VStack(alignment: .leading, spacing: 8) {
                Text("Choose card network")
                    .font(.subheadline)

                ForEach(networks, id: \.network) { network in
                    Button {
                        session.selectCardNetwork(network)
                    } label: {
                        HStack {
                            Text(network.displayName)
                            Spacer()
                            if session.state.selectedNetwork?.network == network.network {
                                Image(systemName: "checkmark")
                            }
                        }
                    }
                    .disabled(!network.allowed)
                }
            }
        }
    }
}
```

> [!NOTE]
>
> Render only networks where `allowsUserSelection` is `true` (and that are `allowed`). Networks that auto-route — such as EFTPOS — are resolved by the SDK and should not appear as a manual choice.

### Using the built-in selector

If you don't need a fully custom picker, the SDK ships a ready-made selector inside the card number field. Both the default `cardDetails` section and the `CardFormDefaults.cardNumber(_:)` building block show it automatically when a co-badged card is detected. When one of the networks disallows shopper selection (for example EFTPOS), the field shows both network badges and offers no choice. `CardFormDefaults.cardNetwork(_:)` is a standalone dropdown for layouts that do not use `CardFormDefaults.cardNumber(_:)`. It renders only when `availableNetworks.count > 1` and calls `selectCardNetwork(_:)` for you. Do not combine it with `CardFormDefaults.cardNumber(_:)` or the full `cardDetails` section, or two selectors appear. See [Card field components](https://primer.io/docs/sdk/ios-checkout/v3.0.0-beta/api/card-form/card-field-components.md).

```swift theme={"dark"}
PrimerCardForm(cardDetails: { session in
    VStack(alignment: .leading, spacing: 16) {
        // The card number field shows the network selector for co-badged cards.
        CardFormDefaults.cardNumber(session)
        HStack(spacing: 12) {
            CardFormDefaults.expiryDate(session)
            CardFormDefaults.cvv(session)
        }
        CardFormDefaults.cardholderName(session)
    }
})
```

## See also

> [card] [Card Form Session](https://primer.io/docs/sdk/ios-checkout/v3.0.0-beta/api/card-form/card-form-session.md)
>
> State, network selection, and submission for the card form.

> [card] [Card field components](https://primer.io/docs/sdk/ios-checkout/v3.0.0-beta/api/card-form/card-field-components.md)
>
> The built-in co-badge selector and other per-field building blocks.

> [card] [PrimerCardForm](https://primer.io/docs/sdk/ios-checkout/v3.0.0-beta/api/card-form/primer-card-form.md)
>
> The card form view and its slots.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.