Braintree to Stripe migration: what actually moves

Braintree to Stripe is one of the most common migrations I see, and one of the most underestimated — not because the card vault is hard to move, but because Braintree is PayPal-owned, and the PayPal side of your vault plays by entirely different rules. I have led subscription migrations moving $100M+ in recurring revenue with zero downtime; this guide covers what is specific about leaving Braintree.

What actually lives in your Braintree account

Three different things, with three different migration paths:

• The card vault. Standard PCI-scoped tokens. Braintree exports these to another Level 1 provider on request — a support-ticket process with legal authorization, done provider-to-provider so you never touch a card number. This is the well-trodden path.
• Vaulted PayPal accounts. These are billing agreements, not tokens, and they belong to the PayPal side of the house. They do not travel with the card vault, and whether they can move at all depends on your region and Stripe's PayPal support there. Every Braintree migration plan should start by sizing this population — if a third of your subscribers pay via PayPal, they are a separate project.
• Subscription state. Braintree runs its own subscription engine. Plans, billing cycles, discounts, retry state — none of it transfers. You rebuild on Stripe Billing and take over at each subscription's renewal boundary.

The Braintree-specific gotchas

• Split the PayPal decision from the card migration. Cards can move on the standard timeline while the PayPal population follows its own track (transfer where supported, re-consent campaign where not). Coupling them stalls the whole project on the hardest 20%.
• Payment-method tokens vs customer objects. Braintree customers can hold multiple payment methods with their own token lifecycle. Decide up front which method wins per customer — the default card in Braintree is not always the one paying the subscription.
• 3DS and network-token history does not follow. Authentication exemptions and network tokens are re-established on Stripe. Expect a brief settling-in period on European traffic while SCA exemptions rebuild.
• Webhook vocabulary differs more than you expect. Braintree's webhook events do not map one-to-one onto Stripe's. Build a translation layer that normalizes Stripe events into your internal vocabulary, and the rest of your codebase never notices the swap.

The framework every migration shares

Whatever provider you are leaving, the platform you build is the same five layers: a snapshot mirror so selection never touches production; a selector that is the single source of truth for eligibility; batching with a migration lock and one correlation ID stamped everywhere; the credential transfer covered above; and cutover pinned to each subscription's renewal boundary— the old provider bills the last cycle it owns, Stripe bills the next one, and no customer is ever billed twice or skipped. Reconciliation runs the whole time, counting row states rather than log events, with Stripe's warehouse as the authority for "ever migrated."

I wrote the full treatment — sequencing, reconciliation formulas, the long-tail playbook, and ten field lessons — in the complete migration guide. This page covers what is different about your starting point.

Sequencing a Braintree exit

1. Size the PayPal population and settle its path first.
2. Reproduce your plan catalog on Stripe Billing.
3. Request the vault export early — the handshake is your critical path.
4. Migrate cards in waves, pinned to renewal boundaries.
5. Run the PayPal track (transfer or re-consent) in parallel.
6. Delta batches for failures and late arrivals until the account is drained.

Frequently asked questions