Card migration (zero re-entry)
What this is: how every card already on file across the ecosystem reaches the portable Basis Theory vault without a single customer re-entering a card — and why that convergence is the ecosystem wallet.
Who it’s for: anyone planning the cutover off Stripe, or reasoning about how a card entered on one brand becomes usable on another.
What to read next: Vault & tokens · PCI posture · Subscriptions.
Status. This is the Phase-B migration design from ADR-0093. The vault
adapter (BasisTheoryVault) is built; the forwarding flow already runs
in the proven loopbio-v2 pipeline (Rimo does this today). The platform-wide
historical export + cutover is planned / gated on a confirmed BT tenant and
Phase-0 sign-off. No customer card is re-collected at any point.
Two complementary paths
Cards reach the vault two ways, and both avoid re-entry:
1. Stripe vault export (historical)
The cards already stored in Stripe are migrated into Basis Theory through a PCI-compliant card-data migration (the card networks and processors support a vault-to-vault export between compliant parties). This is a one-time backfill of the existing book of business. The customer does nothing; their stored card simply now also exists as a Loop-owned portable token.
This is exactly why ADR-0093 makes “exportable vault only” a hard vendor-selection rule (rule 3): a vault that cannot contractually export tokens would strand the entire book of business. Basis Theory was chosen because it can export.
2. Stripe → Basis Theory card forwarding (ongoing)
For cards going forward, new card data is forwarded into Basis Theory as it is collected, so the portable token is created from the start. This already happens — the loopbio-v2 / Rimo pipeline forwards into Basis Theory today, which is the proven pattern BasisTheoryVault matches (POST /tokens to vault, POST /proxy to charge).
The convergence: one BT vault = the ecosystem wallet
Each path feeds the same Basis Theory vault. Once every brand’s cards live there as Loop-owned portable tokens, a card a customer entered for one brand can — subject to consent and entity eligibility — be charged for another, because the token is Loop’s and is vault-agnostic.
This is the third problem from the overview — “there is no ecosystem wallet” — solved structurally: the wallet is simply the shared, exportable vault that every brand’s cards converge into.
Convergence does not loosen the laundering guard. A shared wallet means one token is reusable; it does not mean a charge can cross entity/product eligibility. Every charge still routes only to MIDs of an entity underwritten for that product. The wallet changes whose card is on file, never which LLC may collect for what.
Why re-entry-free matters
- No conversion cliff at cutover. Moving off Stripe without re-collecting cards means no drop in active payment methods, no churned subscriptions, no “update your card” friction.
- Subscriptions survive. Recurring billing (Subscriptions) can move to the own-clock engine because the card-on-file moved with it.
- Portability compounds. Combined with network tokens under Loop’s own TRID, a migrated card survives reissue and provider/acquirer swaps.
Migration sequence
Forwarding (B) is the part already proven; the rest is gated on Phase-0 and a confirmed tenant.
See also
- Vault & tokens — the vault these paths feed, and TRID portability
- PCI posture — why migration keeps Loop at SAQ A
- Subscriptions — what the migrated cards unlock
- Status & roadmap — where this sits
Source
services/payments/src/orchestration/basis-theory-vault.ts(matches the loopbio-v2 forwarding pipeline)- ADR-0093 (Phase B — vault + network tokens; rule 3 exportable-vault-only)