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

# Customer-preferred scheme routing

> Let a buyer choose which network a co-badged card is processed on, and route the transaction on that network.

Many debit cards carry two networks. A French card can carry both Cartes Bancaires and Visa, a Danish
card both Dankort and Visa, an Australian card both EFTPOS Australia and Mastercard. Either network can
carry the authorization, and the two often differ in cost and in approval rate.

Some markets require you to let the cardholder pick. In the European Economic Area, for example,
a buyer's choice of network on a co-badged card must be honored. In other markets you simply
want the choice available. This guide shows how to build that end to end with Gr4vy:

1. Detect that the entered card is co-badged, using the Secure Fields `card-details-changed` event.
2. Show the buyer the networks and let them choose.
3. Send the choice to Gr4vy as `payment_method.preferred_scheme` when you create the transaction.

Gr4vy then processes every attempt of the transaction on the chosen network. A decline on that network
is never retried on another network, but failover to another connection on the same network still
works.

## How it fits together

```mermaid theme={"system"}
sequenceDiagram
    participant Buyer
    participant Page as Checkout page
    participant SF as Secure Fields
    participant Backend as Merchant backend
    participant Gr4vy
    participant PSP as Payment service

    Buyer->>SF: Enters a card number
    SF->>Gr4vy: Looks up the BIN on the checkout session
    Gr4vy-->>SF: scheme and additional_schemes
    SF-->>Page: card-details-changed
    Page-->>Buyer: Offers the two networks
    Buyer->>Page: Selects a network
    Page->>Backend: Submits the order with the selection
    Backend->>Gr4vy: Creates the transaction with preferred_scheme
    Gr4vy->>Gr4vy: Keeps only routes that can use the selected network
    Gr4vy->>PSP: Authorizes on the selected network
    PSP-->>Gr4vy: Returns the authorization result
```

Your page never handles the card number, and you don't need a Flow rule per network. Secure Fields
reports what the card supports, the buyer picks, and Gr4vy keeps the transaction on that network.

## Step 1: Detect a co-badged card

Secure Fields emits `card-details-changed` on the card number field once the API has confirmed the
details for the entered BIN. The payload carries the primary `scheme` and an `additionalSchemes` array
holding the other networks on the card. For a card with a single network, `additionalSchemes` is empty.

```jsx React theme={"system"}
<CardNumber
  onCardDetailsChanged={({ scheme, additionalSchemes }) => {
    setPrimaryScheme(scheme)
    setCoBadgedScheme(additionalSchemes?.[0] ?? null)
  }}
/>
```

```js Node / CDN theme={"system"}
const cardNumberField = secureFields.addCardNumberField('#cc-number')

cardNumberField.addEventListener('card-details-changed', (data) => {
  // { id: 'number', scheme: 'visa', additionalSchemes: ['carte-bancaire'], ... }
  setPrimaryScheme(data.scheme)
  setCoBadgedScheme(data.additionalSchemes?.[0] ?? null)
})
```

The event fires again with `scheme: null` and an empty `additionalSchemes` array when the buyer clears
the field, so reset your selection whenever the co-badged network goes away.

> [!NOTE]
>
> A card's additional schemes can take more digits to resolve than its primary scheme does. Expect
> `additionalSchemes` to populate as the buyer finishes typing the card number, not on the first few
> digits — don't treat an empty array early in typing as "this card has no co-badge."

> [!NOTE]
>
> `card-details-changed` only fires on the card number field. See
> [Secure Fields events](https://docs.gr4vy.com/guides/payments/secure-fields/events.md) for the full event list.

To also show the two logos inside the field itself, enable
[scheme icons](https://docs.gr4vy.com/guides/payments/secure-fields/ux-options.md#scheme-icons) with
`showSchemeIcons={{ scheme: true, additionalSchemes: true }}`.

### Stored cards

For a card already in the vault, the same information is on the payment method. Both
[List payment methods](https://docs.gr4vy.com/reference/payment-methods/list-payment-methods.md) and
[List buyer payment methods](https://docs.gr4vy.com/reference/payment-methods/list-buyer-payment-methods.md) return
`scheme` and `additional_schemes`, so you can offer the same choice without asking for the card again.

## Step 2: Show the choice

Render the choice only when `additionalSchemes` is non-empty. Offering a network that isn't on the
card has no effect: Gr4vy checks the choice against the card's networks and processes the transaction
on the primary network instead. See [When the choice isn't on the card](#when-the-choice-isnt-on-the-card).

Only offer networks that one of your connections can process. If the buyer picks a network that no
connection can process, Gr4vy declines the transaction rather than moving it to another network.

A few practical points for the interface.

* Label the options with the network names the buyer sees on the card, not the Gr4vy scheme IDs.
* Default to whichever network you prefer, and record the buyer's choice only when they change it.
* Reset the selection when the card number changes, since the next card may carry different networks.

Scheme IDs map to display names through the
[card scheme definitions](https://docs.gr4vy.com/reference/card-schemes/list-card-scheme-definitions.md) endpoint, which also
returns an icon URL for each scheme.

## Step 3: Send the choice on the transaction

When you [create the transaction](https://docs.gr4vy.com/reference/transactions/new-transaction.md), set
`payment_method.preferred_scheme` to the network the buyer picked. The field is accepted when you pay with
card details (`card`), a stored card (`id`), or a checkout session (`checkout-session`), which is how
Secure Fields passes the card.

```csharp C# theme={"system"}
var transaction = await client.Transactions.CreateAsync(
    transactionCreate: new TransactionCreate()
    {
        Amount = 1299,
        Currency = "EUR",
        PaymentMethod =
            TransactionCreatePaymentMethod.CreateCheckoutSessionWithUrlPaymentMethodCreate(
                new CheckoutSessionWithUrlPaymentMethodCreate()
                {
                    Id = checkoutSession.Id,
                    PreferredScheme = CheckoutSessionWithUrlPaymentMethodCreatePreferredScheme.CarteBancaire,
                }
            ),
    }
);
```

```go Go theme={"system"}
checkoutSessionWithURLPaymentMethodCreate := components.CheckoutSessionWithURLPaymentMethodCreate{
    ID:              checkoutSession.ID,
    PreferredScheme: components.CheckoutSessionWithURLPaymentMethodCreatePreferredSchemeCarteBancaire.ToPointer(),
}
paymentMethod := components.CreateTransactionCreatePaymentMethodCheckoutSessionWithURLPaymentMethodCreate(checkoutSessionWithURLPaymentMethodCreate)

transactionCreate := components.TransactionCreate{
    Amount:        int64(1299),
    Currency:      "EUR",
    PaymentMethod: &paymentMethod,
}

transaction, err := client.Transactions.Create(ctx, transactionCreate, nil, nil)
```

```java Java theme={"system"}
CreateTransactionResponse transactionResponse = gr4vyClient.transactions().create()
    .transactionCreate(TransactionCreate.builder()
        .amount(1299L)
        .currency("EUR")
        .paymentMethod(TransactionCreatePaymentMethod.of(CheckoutSessionWithUrlPaymentMethodCreate.builder()
            .id(checkoutSession.id())
            .preferredScheme(CheckoutSessionWithUrlPaymentMethodCreatePreferredScheme.CARTE_BANCAIRE)
            .build()))
        .build())
    .call();
```

```php PHP theme={"system"}
$transactionCreate = new TransactionCreate(
    amount: 1299,
    currency: 'EUR',
    paymentMethod: new CheckoutSessionWithUrlPaymentMethodCreate(
        id: $checkoutSession->id,
        preferredScheme: 'carte-bancaire',
    ),
);
$response = self::$sdk->transactions->create($transactionCreate);
```

```python Python theme={"system"}
transaction: models.Transaction = client.transactions.create(
    amount=1299,
    currency="EUR",
    payment_method={
        "method": "checkout-session",
        "id": checkout_session.id,
        "preferred_scheme": "carte-bancaire",
    },
)
```

```ts TypeScript theme={"system"}
const transaction = await gr4vy.transactions.create({
    amount: 1299,
    currency: "EUR",
    paymentMethod: {
        method: "checkout-session",
        id: checkoutSession.id,
        preferredScheme: "carte-bancaire"
    }
})
```

Send the field only when the buyer made a choice. A transaction without `preferred_scheme` behaves
exactly as it did before, unless it uses a stored card with a saved choice. See
[Remember the choice on stored cards](#remember-the-choice-on-stored-cards). Sending the card's primary
network is also valid, and keeps every attempt on that network.

The field accepts the networks listed for `preferred_scheme` in the
[API reference](https://docs.gr4vy.com/reference/transactions/new-transaction.md). Any other value is rejected with a `400`.

## How Gr4vy processes the choice

Your Card transactions Flow still decides which connections to try, and in which order. The choice
filters that list before the first attempt. It doesn't reorder it or add to it.

* **The buyer picks the co-badged network.** Only outcomes with the
  [Force co-badged network](https://docs.gr4vy.com/guides/dashboard/flow/card-transactions.md#co-badged-routing)
  transformation are tried. Outcomes without it are skipped, because they would process the card on
  its primary network.
* **The buyer picks the primary network.** Outcomes with the Force co-badged network transformation
  are skipped. Outcomes without it are tried as usual.
* **No routing rule matches, or you set `payment_service_id`.** The transaction goes to that
  connection on the chosen network.

The remaining outcomes are tried in order, all on the chosen network. A decline on one connection fails
over to the next connection on the same network. It's never retried on a different network.

If the filter leaves nothing to try, the request fails with
`There is no active payment service for this transaction.` This happens when a matching rule has no
outcome for the chosen network.

> [!WARNING]
>
> If a routing rule matches transactions where the buyer can pick the co-badged network, give that rule
> an outcome with the Force co-badged network transformation for each connection that can process the
> co-badged network. Without one, a co-badged choice fails instead of being processed.

Network tokens are only provisioned for a card's primary network. When the buyer picks the co-badged
network, Gr4vy sends the card number instead of a network token.

### When the choice isn't on the card

Gr4vy checks the choice against the networks returned by the card's BIN lookup. If the chosen network
isn't one of them, Gr4vy ignores the choice and processes the transaction as if no choice was sent. The
request doesn't fail. Examples include Mastercard on a card that carries Visa and Cartes Bancaires, or a
moment where the BIN lookup returns only the primary network.

## Remember the choice on stored cards

The choice is saved on the payment method, so later payments with the same card stay on the network the
buyer picked.

* A transaction with `preferred_scheme` that stores the card saves the choice on the new payment
  method. So does `preferred_scheme` on [Create payment method](https://docs.gr4vy.com/reference/payment-methods/new-payment-method.md).
* Later transactions with the stored card (`method: id`) use the saved choice when the request doesn't
  send one. This includes merchant-initiated transactions.
* A transaction with the stored card that sends `preferred_scheme` uses that value instead, and saves it
  as the card's new choice.
* To change or clear the choice without a transaction, set `preferred_scheme` with
  [Update payment method](https://docs.gr4vy.com/reference/payment-methods/update-payment-method.md). Set it to `null` to clear
  it.

The payment method returns the saved choice as `preferred_scheme`, next to `scheme` and
`additional_schemes`. A saved choice that's no longer on the card when the card is next used is
cleared.

## 3DS on the chosen network

3DS results are only valid for the network they were created on, so 3DS has to run on the network the
buyer picked.

### Gr4vy runs 3DS on the transaction

When Gr4vy runs 3DS as part of the transaction, for example with [Hosted 3DS](https://docs.gr4vy.com/guides/features/3ds/hosted.md),
it authenticates on the chosen network automatically. You don't need to change anything in your
checkout.

Gr4vy needs a [3DS configuration](https://docs.gr4vy.com/guides/features/3ds/setup.md#add-a-merchant-account-configuration) for
the chosen network. Add one for each co-badged network you offer, such as Cartes Bancaires. Without one,
the transaction continues without 3DS. See
[When no configuration matches](https://docs.gr4vy.com/guides/features/3ds/setup.md#when-no-configuration-matches).

### Native 3DS with Secure Fields

With [native 3DS](https://docs.gr4vy.com/guides/payments/secure-fields/three-d-secure.md), authentication runs when you call
`submit()`, before the transaction exists. Call `setPreferredScheme()` with the buyer's choice before you
call `submit()`. See
[Co-badged cards](https://docs.gr4vy.com/guides/payments/secure-fields/three-d-secure.md#co-badged-cards).

Gr4vy records the network that 3DS ran on in the checkout session. A transaction created with that
checkout session is processed on the same network, even if it sends a different `preferred_scheme` or
none. This keeps the 3DS result valid for the authorization.

### 3DS data you pass through

If you [pass through 3DS data](https://docs.gr4vy.com/guides/features/3ds/external.md) from another provider, set
`three_d_secure_data.scheme` to the network you authenticated on.

* If `three_d_secure_data.scheme` differs from `preferred_scheme`, the request fails with a `400`.
* If `three_d_secure_data.scheme` isn't set, the 3DS data is treated as belonging to the chosen network.
* If you authenticated on the co-badged network, also send it as `preferred_scheme`. Otherwise the
  transaction is processed on the primary network, and the 3DS data isn't sent because it belongs to a
  different network.

## Move from metadata and Flow rules

Before `preferred_scheme`, the way to honor a choice was to send it as transaction `metadata` and add a
Flow rule that forces the co-badged network for that metadata. To move to `preferred_scheme`:

1. Send `payment_method.preferred_scheme` with the buyer's choice.
2. Move the Force co-badged network outcome from the metadata rule into the routing rules that match
   these transactions. `preferred_scheme` only filters outcomes and never adds one, so each rule needs
   an outcome with the transformation for every connection that can process the co-badged network.
3. Only then remove the metadata condition, or the rule if it only existed to force the co-badged
   network. Removing it first makes every co-badged choice fail with
   `There is no active payment service for this transaction.`

A rule that lists the same connection twice, once with the transformation and once without, no longer
fails a co-badged choice over to the primary network. The outcome that doesn't match the choice is
skipped.

## Authorize and delayed capture

Not every network can hold an authorization and capture it later. When the transaction `intent` is
`authorize`, outcomes with the Force co-badged network transformation are skipped if the co-badged
network is one of these.

`accel`, `bancontact`, `cirrus`, `culiance`, `dankort`, `eftpos-australia`, `hipercard`, `nyce`,
`pulse`, `rupay`, `star`

Every other network can be used under either intent. That includes `carte-bancaire` and `maestro`, the
two most common co-badges on European cards.

A zero-amount card-on-file setup, a pre-authorization, or any other `authorize` transaction where the
buyer picked one of the networks above loses those outcomes. If nothing else is left, the request fails
with `There is no active payment service for this transaction.` Send `intent: capture` on transactions
where the buyer may pick one of these networks, or offer the choice only when the transaction captures.

## Recurring payments

* For a subsequent transaction that carries a scheme transaction ID from an earlier payment, the attempt
  is sent without the ID when the ID belongs to a different network. Some payment services decline or
  reject a merchant-initiated transaction without one. A `previous_scheme_transaction_id` that you send
  in the request is treated as belonging to the card's main network.
* A payment service may not return a scheme transaction ID for a payment on a domestic co-badged
  network, so a card stored with such a payment has no reference for later merchant-initiated
  transactions.
  See [Scheme transaction IDs on stored payment methods](https://docs.gr4vy.com/guides/features/recurring-payments/overview.md#scheme-transaction-ids-on-stored-payment-methods).

## Test in sandbox

Most card numbers resolve to a single network, so the choice never appears while you are building.
The card below has a sandbox-only BIN that always resolves as co-badged, so it exercises the whole
path without needing a real co-badged card.

| Card number | Networks | Country | Type |
| :- | :- | :- | :- |
| `4035 5010 0000 0008` | Visa, Cartes Bancaires | FR | Debit |

Any future expiry date and any security code work. Enter it into Secure Fields and
`card-details-changed` fires with `scheme: "visa"` and `additionalSchemes: ["carte-bancaire"]`.

Send `preferred_scheme` set to `carte-bancaire` or `visa` with this card to test both choices.
Cartes Bancaires can be used under either intent, so this card also works for `authorize` flows. To test
a network that can't, see [Authorize and delayed capture](#authorize-and-delayed-capture).

## Verify the result

The created transaction reports the network it was sent on in `payment_method.scheme`.

```json theme={"system"}
{
  "type": "transaction",
  "id": "fe26475d-ec3e-4884-9553-f7356683f7f9",
  "status": "authorization_succeeded",
  "payment_method": {
    "type": "payment-method",
    "method": "card",
    "scheme": "carte-bancaire"
  }
}
```

This field reports the network Gr4vy sent to the connection. It can differ from the network the payment
service ultimately used when the payment service uses its own token for the card, or falls back to the
primary network internally.

For a stored card, [Get payment method](https://docs.gr4vy.com/reference/payment-methods/get-payment-method.md) returns the saved
choice as `preferred_scheme`.


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