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.
Prerequisites
- An active Payrails session (see Quick Start) rendering a
CardForm+CardPaymentButton. - Co-branded handling enabled for the session: the init response must include the
binLookuplink andfeatureConfig.coBrandedCardsRolloutgreater 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 insideCardForm when a co-branded card is detected (two or more schemes). You do not add a separate component.
2. Observe the shopper’s choice
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
4. Pay
No extra work. When the shopper pays a co-branded card, the SDK submits the selected scheme aspaymentInstrumentData.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), callSession.binLookup:
Session.binLookup for the full contract.