--- name: bt-migrate description: Plan card and vault migrations with customer-owned proof gates. license: MIT metadata: tier: core last_verified: '2026-07-21' --- # Migrations and portability ## First principle Implementation pattern: a migration is an architecture review disguised as delivery work. Before moving a single card, confirm the target topology (`bt-architecture`) — migrating into the wrong tenant shape doubles the work. And favor the sequencing that preserves optionality after day one: the customer should end the migration _less_ locked in, not differently locked in. ## The four documented motions 1. **Import cards on file** (PSP/processor → vault): https://developers.basistheory.com/docs/migrations/import-cards-on-file. The PSP-cooperation path: the processor exports the portfolio to Basis Theory under PCI-compliant transfer. Timeline is partly outside the customer's control — start the PSP export request early; it is usually the critical path. 2. **Import from your own database** (in-house storage → vault): https://developers.basistheory.com/docs/migrations/import-from-database. The customer-controlled path for teams currently holding data in scope; ends with dropping the sensitive columns. 3. **Export / leave** (vault → wherever): https://developers.basistheory.com/docs/migrations/export-cards-on-file, plus targeted extraction: https://developers.basistheory.com/docs/guides/process/extract-cards. Use this to keep portability explicit: the exit path is documented, so plans should preserve the customer's ability to leave or change processors later. 4. **Stripe-specific motions**: the forward connection (charge Stripe-stored cards through Basis Theory while migrating): https://developers.basistheory.com/docs/api/connections/stripe-forward; continuous backup of Stripe tokens: https://developers.basistheory.com/docs/guides/process/backup-stripe-tokens. Migrations index: https://developers.basistheory.com/docs/migrations/. ## PSP-to-PSP sequencing (the composite ask) The staged shape that repeatedly works (implementation pattern): 1. **New traffic first**: collect new cards into the vault (`bt-collect`) and charge through the current PSP via proxy (`bt-payments`). No stored-card movement yet; instantly stops the lock-in from growing. 2. **Backfill**: import the existing portfolio (motion 1 or 2). Reconcile counts and fingerprint-level identity — every imported card accounted for: imported, duplicate-merged, or explicitly skipped with reason. 3. **Dual-capability window**: vault tokens can now charge through old and new PSP alike (source-type mappings per PSP in `bt-payments`). Run comparative traffic if useful; recurring MIT traffic needs network transaction IDs carried over — verify the new PSP accepts external ones (`bt-card-lifecycle`). 4. **Cutover by cohort**, not big-bang: shift charge routing per segment, watch auth rates, keep the old path hot until the new path has processed real recurring cycles (a subscription portfolio is not proven until renewals — not just first charges — succeed). 5. **Decommission** only after parity holds: auth-rate delta explained, decline taxonomy mapped, AU/network-token coverage re-established on the new path. Parity checks are their own discipline: after any environment/tenant change, explicitly verify endpoints, key→environment mapping, IP allowlists, webhook signatures, and hidden hardcoding (`bt-production` carries the checklist; heuristic: assume parity drift until disproven). ## Existing-code mode 1. Inventory: where card data lives today (PSP vault, own DB, both), volumes, recurring vs one-time mix, and which PSP features are load-bearing (AU, network tokens, stored MIT credentials). 2. Pick motions and sequence per above; produce a written plan with rollback points per stage. 3. Implement the new-traffic path first (it is also the rehearsal for the charge path the backfilled cards will use). 4. Recommend rehearsing the plan with synthetic, customer-owned, non-production data before any production data move. 5. Final report: cards migrated (counted), parity checks passed, remaining customer-owned items (PSP export contracts, production credential setup, cutover scheduling, decommission decision). Escalate honestly when: the migration is mid-incident (evidence first — `bt-test-debug`), contractual PSP exit terms drive sequencing (customer-owned business conversation, not a technical fact), or timelines depend on PSP export queues Basis Theory doesn't control. ## Basis Theory implementation guidance When the answer needs implementation judgment beyond public docs, load only the relevant slices below from [../\_shared/references/implementation-guidance/README.md](../_shared/references/implementation-guidance/README.md). Treat these as implementation patterns, not canonical product behavior; keep public docs as the source of truth and label the guidance as **Implementation pattern** or **Assumption** unless docs prove it. - `../_shared/references/implementation-guidance/migrations/` - `../_shared/references/implementation-guidance/resilience/` ## Working conventions (shared by all Basis Theory skills) - Public Basis Theory docs are the source of truth for product behavior. Link the specific docs page behind any product claim; if a skill and the docs disagree, follow the docs. - Keep customer ownership clear: customers own PSP accounts, credentials, compliance decisions, production rollout, and application code. Skills can guide plans, bounded changes, and examples; they do not certify production readiness. - Never request, echo, store, or commit real credentials. Use placeholders such as `` and prefer sandbox or synthetic data for examples. - If a live-looking credential, live cardholder data, or production secret appears, stop mutation work, tell the user exactly where it appeared, and require rotation/revocation before continuing. - Default to test tenants and PSP sandboxes. Do not run or recommend production charges, refunds, card reveals, credential migrations, or data moves unless the user explicitly asks and the plan names safeguards, rollback, and customer approval. - Treat vague planning, audit, review, and “should we” prompts as read-only unless the user explicitly asks for a bounded implementation change. - Before changing product code, map the existing checkout/data flow, credential-bearing paths, persistence, retries, refunds, webhooks, logs, and rollback expectations. - End with an honest final report: done, assumed, remaining, proof run, unverified live behavior, rollback, and go-live items.