← All guides

Payment Processing Migration Project Timeline

Manage a payment processor migration with a project timeline covering gateway selection, card vault migration, integration testing, and parallel processing.

Payment Processing Migration Project Timeline

Migrating Payment Processors Is Not Like Migrating a Database

When you migrate a database, you copy the data from one place to another and cut over. When you migrate payment processors, the equivalent of "the data" — card tokens — cannot be directly copied. Tokens are generated by and belong to each processor's vault. A Stripe token is meaningless to Adyen. An Adyen token is meaningless to Braintree.

This means every existing subscription customer and stored card needs to either have their token migrated (requires cooperation from both processors), re-tokenize when they next transact, or be proactively contacted to re-enter their card details. Each approach has cost and complexity tradeoffs. Your migration strategy hinges on which approach you use, and that decision should be made in Phase 1 — not discovered in Phase 4.

Phase 1: Assessment and Vendor Selection (Weeks 1–4)

Current state documentation:

  • Map all payment flows: checkout (new customers), subscription billing (recurring), refunds, voids, disputes, manual charges
  • Measure current performance: authorization rate by BIN range, decline rate by decline code, processing cost (interchange + processing fee + dispute costs)
  • Count stored card tokens: how many subscription customers, how many stored payment methods

Selection criteria:

  • Authorization rates: the most important metric. A 2% improvement in auth rate on $100M volume is $2M in recovered revenue.
  • Pricing: interchange-plus vs. flat rate; negotiate based on volume
  • Feature parity: confirm all current features are available (3DS2, network tokenization, Apple Pay/Google Pay, ACH)
  • Geography: required payment methods and currencies for all markets you serve
  • Bank account debits: required for SaaS with large ACH volume

Vendor shortlist:

  • Stripe: developer-friendly, strong subscription tooling, excellent auth rates
  • Adyen: enterprise-focused, strong international coverage, interchange-plus pricing at volume
  • Braintree (PayPal): PayPal integration native, good fraud tooling
  • Checkout.com: strong EMEA and APAC coverage

Contract negotiation: get competing offers from at least two finalists. Processing rates are negotiable, especially at >$10M annual volume.

Phase 2: Integration Architecture Design (Weeks 4–6)

Design the migration architecture before writing code.

Parallel processing architecture:

Route new customers to the new processor while existing customers continue on the legacy processor. This approach:

  • Eliminates risk of disrupting existing subscription customers
  • Allows real-time comparison of new processor performance
  • Allows gradual token migration at renewal time

Card token migration strategy:

Option A — Bulk migration: both processors coordinate to export and import tokens (requires processor agreement and technical support from both sides). Allows same-day migration of all stored cards.

Option B — Lazy migration: existing customers continue on legacy processor. When a subscription renews, or when a customer updates their card, re-tokenize on the new processor. Full migration may take 12–24 months for customers with infrequent renewals.

Option C — Proactive re-auth campaign: email customers asking them to re-enter payment details. Achieves faster migration but has customer friction and non-response risk.

Most companies use Option B or a hybrid: bulk migration for top accounts, lazy migration for the long tail.

Fallback design:

  • Define fallback behavior if new processor returns an unexpected error
  • For new customers: retry on legacy processor? Or show error and require new card?
  • Document the rollback plan if the new processor has systemic issues post-launch

Phase 3: New Processor Integration (Weeks 5–12)

Implement payment flows:

  • Payment form / SDK integration for checkout
  • Stored card tokenization flow
  • Recurring billing (subscription) charge processing
  • 3DS2 authentication flow
  • Apple Pay and Google Pay if required
  • ACH bank account collection and debit if applicable

Fraud tools:

Configure the new processor's fraud tools:

  • Radar rules (Stripe), Risk (Adyen) or equivalent
  • Define block rules, review rules, and allow rules
  • Configure 3DS step-up authentication for high-risk transactions

Refunds and voids:

Implement refund and void APIs. Refunds on the new processor for charges made on the legacy processor require legacy processor refund APIs — confirm how you'll handle cross-processor refund scenarios during the transition period.

Dispute / chargeback handling:

  • Configure dispute webhook to receive notification when a dispute is filed
  • Implement evidence submission workflow
  • Confirm dispute escalation process to fraud/finance team

PCI compliance:

If your integration changes scope — for example, moving from hosted fields to a self-hosted form — reassess PCI scope. Submit updated SAQ or bring in a QSA for assessment before going live.

Phase 4: Card Token Migration (Weeks 10–14)

For bulk migration (if applicable):

  1. Initiate bulk token export from legacy processor
  2. Transmit token data to new processor vault via encrypted transfer
  3. New processor generates new tokens mapping to the imported card data
  4. Update your database: map old token to new token for each customer
  5. Validate: run test charge on a sample of migrated tokens
  6. Switch subscription billing to use new tokens for renewed charges

For lazy migration:

  1. At next renewal, attempt charge on legacy processor
  2. If successful: log that this customer has not migrated
  3. If customer updates payment method: capture new token on new processor, switch customer to new processor
  4. Annual subscription renewals: proactively re-tokenize 30 days before renewal

Track migration percentage weekly. Set a completion target date and communicate to affected teams.

Phase 5: Testing (Weeks 12–15)

Full test coverage required:

  • Successful payment: all payment methods (card, Apple Pay, ACH)
  • Card decline: per decline code (insufficient funds, card blocked, 3DS failure, expired card)
  • Network timeout: processor unavailable — graceful error handling
  • 3DS challenge: card requiring 3DS — flow works end-to-end
  • Refund: full and partial, same-day and delayed
  • Dispute: confirm webhook received, internal process triggered
  • Subscription renewal: confirmed to charge on correct processor/token

Authorization rate validation:

Run a real-money production pilot on a small segment of new customers. Compare auth rate to legacy processor baseline. Don't declare success until auth rates are confirmed equivalent or better.

Phase 6: Cutover and Parallel Running (Weeks 15–18)

Traffic routing:

Start with 10% of new customer traffic to the new processor. Monitor for 48 hours. If auth rates and error rates are acceptable, increase to 25%, then 50%, then 100%.

Parallel monitoring:

  • Auth rate: target ≥ legacy baseline
  • Decline rate by decline code: watch for unusual spikes in specific decline codes
  • Payment processing latency: p95 response time
  • Dispute rate: watch for elevated dispute rate on new processor in first 30 days

New customer cutover: complete cutover of new customer traffic once validation is complete.

Existing customer migration: continue lazy migration program per Phase 4.

Build your payment migration project timeline in gantt-chart.io with explicit milestones for the architecture decision (Phase 2), PCI assessment sign-off, auth rate validation, and full cutover. The token migration strategy decision is a milestone that must happen in Phase 1 — it affects the entire downstream timeline. Visualizing the dependency makes that clear from the start of the project.