- Detect that the entered card is co-badged, using the Secure Fields
card-details-changedevent. - Show the buyer the networks and let them choose.
- Send the choice to Gr4vy as
payment_method.preferred_schemewhen you create the transaction.
How it fits together
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 emitscard-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.
scheme: null and an empty additionalSchemes array when the buyer clears
the field, so reset your selection whenever the co-badged network goes away.
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.”card-details-changed only fires on the card number field. See
Secure Fields events for the full event list.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 and List buyer payment methods returnscheme 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 whenadditionalSchemes 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.
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.
Step 3: Send the choice on the transaction
When you create the transaction, setpayment_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.
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. 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. 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 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.
There is no active payment service for this transaction. This happens when a matching rule has no
outcome for the chosen network.
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_schemethat stores the card saves the choice on the new payment method. So doespreferred_schemeon Create payment method. - 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_schemeuses that value instead, and saves it as the card’s new choice. - To change or clear the choice without a transaction, set
preferred_schemewith Update payment method. Set it tonullto clear it.
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, it authenticates on the chosen network automatically. You don’t need to change anything in your checkout. Gr4vy needs a 3DS 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.Native 3DS with Secure Fields
With native 3DS, authentication runs when you callsubmit(), before the transaction exists. Call setPreferredScheme() with the buyer’s choice before you
call submit(). See
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 from another provider, setthree_d_secure_data.scheme to the network you authenticated on.
- If
three_d_secure_data.schemediffers frompreferred_scheme, the request fails with a400. - If
three_d_secure_data.schemeisn’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
Beforepreferred_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:
- Send
payment_method.preferred_schemewith the buyer’s choice. - Move the Force co-badged network outcome from the metadata rule into the routing rules that match
these transactions.
preferred_schemeonly 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. - 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.
Authorize and delayed capture
Not every network can hold an authorization and capture it later. When the transactionintent 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_idthat 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.
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.
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.
Verify the result
The created transaction reports the network it was sent on inpayment_method.scheme.
preferred_scheme.