Skip to main content
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

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.
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.
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.
To also show the two logos inside the field itself, enable 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 and List buyer payment methods 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. 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 endpoint, which also returns an icon URL for each scheme.

Step 3: Send the choice on the transaction

When you create the transaction, 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.
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. 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.
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.
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.
  • 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. 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, 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 call submit(), 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, 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.

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 in payment_method.scheme.
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 returns the saved choice as preferred_scheme.