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

> ## Agent Instructions
> Use the Payrails Web SDK v6 for new browser integrations. The Web SDK v5 pages are kept only for existing integrations; point anyone still on v5 to the v6 migration guide rather than extending v5 code.
> Collect card data client-side through the Payrails SDKs — Secure Fields, client-side encryption, or the checkout drop-in — so that card data never reaches the merchant's own servers. Recommend the API-only tokenization flow, which accepts raw card numbers server-side, only when the merchant has confirmed they hold the PCI scope for it.
> Model every payment as a workflow execution: create an execution, then drive it with the lifecycle actions (lookup payment options, authorize, capture, cancel, refund). Do not call provider APIs directly — routing, retries, 3DS and fraud steps belong in the workflow configuration, not in integration code.
> Reconcile the final state of a payment on the notification (webhook), never on a client-side event. An in-request long-poll of the execution is a supported additional signal, not a replacement for that reconciliation.
> Send an idempotency key — a UUID, in the `X-Idempotency-Key` header — on every POST, PUT and PATCH request, and on soft deletes. GET requests need none, and hard deletes cannot be idempotent.
> Pass provider-specific data through meta fields rather than hardcoding per-provider payloads. Payrails translates meta fields into each provider's own format.
> Configure routing, retries and provider selection in Workflow Studio, so that changes ship without redeploying application code.

# How to Let Shoppers Choose a Card Network (Co-Branded Cards)

> Let shoppers choose which network processes a co-branded card in the Android SDK, and submit that choice with the payment.

Some cards carry two networks — a local/domestic scheme (e.g. `mada`, `cartesbancaires`) and an international one (e.g. `visa`, `mastercard`). This guide shows how to let the shopper pick which network the payment routes over and submit that choice. Also known as **co-badged cards** or **card brand choice**.

> Background: [Co-Branded Cards](/docs/orchestration/checkout-sdks/android/sdk-concepts#co-branded-cards).

## Prerequisites

* An active Payrails session (see [Quick Start](/docs/orchestration/checkout-sdks/android)) rendering a `CardForm` + `CardPaymentButton`.
* Co-branded handling **enabled for the session**: the init response must include the `binLookup` link **and** `featureConfig.coBrandedCardsRollout` greater than 0 (configured by the Payrails backend — contact Payrails to enable it for your merchant account).
* A genuinely co-branded test card (e.g. a mada/Mastercard dual-scheme card).

## Steps

### 1. Render the card form as usual

The Card Brand selector appears **automatically** inside `CardForm` when a co-branded card is detected (two or more schemes). You do not add a separate component.

### 2. Observe the shopper's choice

```kotlin theme={null}
val config = CardFormConfig(
    events = CardFormEvents(
        onPreferredSchemeChanged = { change ->
            // change.preferredScheme — selected canonical code (null when not co-branded)
            // change.cardSchemes    — all detected schemes, each with .selected
        }
    )
)
val cardForm = Payrails.createCardForm(config)
```

`onPreferredSchemeChanged` fires when a co-branded card is detected (with the default selection), when the shopper taps a different tile, and once with an empty payload if the card stops being co-branded. It is de-duplicated, so recompositions do not re-fire it.

### 3. (Optional) Localize and style the selector

```kotlin theme={null}
val config = CardFormConfig(
    translations = CardTranslations().apply {
        labels.cardBrandSelectorTitle = "Choose your network"
        labels.cardBrandSelectorSubtitle = "This card supports two networks"
    },
    styles = CardFormStylesConfig(
        cardBrandSelector = CardBrandSelectorStyle(
            selectedTileBorderColor = 0xFF0F63BD.toInt(),
            selectedCheckColor = 0xFF0F63BD.toInt(),
            tileCornerRadius = 12, // dp
        )
    ),
)
```

See the [Card Brand Selector styling reference](/docs/orchestration/checkout-sdks/android/styling-guide#card-brand-selector) for all tokens.

### 4. Pay

No extra work. When the shopper pays a co-branded card, the SDK submits the selected scheme as `paymentInstrumentData.preferredScheme` on the authorize request. For a single-brand card, no selector shows and no `preferredScheme` is sent.

## (Optional) Look up a BIN directly

To inspect card metadata yourself (without the form), call `Session.binLookup`:

```kotlin theme={null}
val result = session.binLookup("529741") // suspend; returns null on failure
if (result?.localNetwork != null) {
    // co-branded card: result.network + result.localNetwork
}
```

See [`Session.binLookup`](/docs/orchestration/checkout-sdks/android/api-reference#co-branded-cards) for the full contract.

## Related

* [Co-Branded Cards (concept)](/docs/orchestration/checkout-sdks/android/sdk-concepts#co-branded-cards)
* [API Reference — Co-Branded Cards](/docs/orchestration/checkout-sdks/android/api-reference#co-branded-cards)
* [Styling Guide — Card Brand Selector](/docs/orchestration/checkout-sdks/android/styling-guide#card-brand-selector)


## Related topics

- [SDK Concepts](/docs/orchestration/checkout-sdks/ios/sdk-concepts.md)
- [Co-branded cards](/docs/orchestration/payment-methods/cards/co-branded-cards.md)
- [iOS SDK - Quick start](/docs/orchestration/checkout-sdks/ios/index.md)