A card your customer saved used to belong to the gateway account that first took it. Every later payment on that card went back to the same account, even when another of your accounts would have served the payment better. That is no longer the case.
A saved card is now one Flo card: a stable identity of its own, independent of the account that captured it. The same card can hold a binding on more than one of your gateway accounts, and FloPay chooses the account for each new payment. Your customer sees the same card and never re-enters it.
Your preference order decides
For each new card payment, FloPay first removes the gateways that cannot serve it at all: wrong environment, inactive, wrong session mode, restricted, no card support, no stored credential, or another merchant's. It then ranks what is left by how well it matches the payment's country and currency, and your preference order breaks the tie.
Set that order in Settings > Gateways, where the Preference column now reads first to last with Move up and Move down on each row, or send priority to the gateway settings API. Lower ranks first.
Preference applies only after a gateway has been found eligible, so it decides between accounts that fit the payment equally well. It never promotes an account the payment context has already ruled out.
What changing your order does not do
Before FloPay makes any charge-capable request, it snapshots that payment's routing decision, and every retry and late completion resumes that snapshot. So reordering your preferences:
- does not re-route a payment already in flight,
- does not rewrite where past payments were processed or reported,
- does not migrate subscriptions a provider bills directly,
- does not bypass 3DS. Prior setup on one account is friction reduction on that account, never portable approval.
Cards saved before the change
Existing cards are adopted automatically, one at a time, the first time a new payment is routed for them, whenever FloPay still holds a reusable credential for the card. Nothing to run, no batch job, and your customer is not asked to consent again or to re-enter the card.
Where only the provider's own payment-method reference was kept, the card is never adopted and never presented as portable. It keeps working exactly where it is, or your customer can add it again. No migration is promised for those cards.
Setting a card up
POST /v1/checkouts/sessions/setup now accepts three optional fields describing the transaction the card is being saved for: country, currency, and futureUse (on_session or off_session, off-session when omitted). @flopay/shared publishes the body as the type-only CreateCardSetupSessionRequest. This context never selects or hints a gateway: the billing API alone decides which gateway verifies the card.
Turning it on
FloPay enables gateway-agnostic saved cards per account. There is no self-serve toggle and no request field: ask your FloPay contact. Until it is enabled nothing changes, and every response keeps the shape you already handle.
Read Saved cards are gateway agnostic for the model and the adoption rules, and Gateway selection for the full routing decision.