Processor Switch Checklist (Playbook)

TL;DR

• Processor migrations take 4-8 weeks minimum; complex token migrations with large card-on-file databases take 12+ weeks - don't underestimate the timeline
• Token portability is the make-or-break factor. Confirm your current processor will export tokens and the new one can import them before you sign anything, because you can't fix it after
• Run both processors in parallel for 2-4 weeks instead of a hard cutover. Route a percentage of traffic to the new one first, so integration issues don't land on all your revenue at once
• Recurring billing is the highest-risk part. Test every subscription scenario (new charges, retries, cancellations) before you touch your existing subscriber base, and don't migrate it in one go

Switching processors is high-stakes: mess up the migration and you'll lose recurring revenue, break checkout, or spend a quarter on reconciliation. This one's about not doing that.

Timeline: 4-8 weeks minimum, and complex migrations take 12+ weeks.

Workflow Overview

Phase	Key Tasks
Discovery	Inventory current processor, map features to new, define token strategy
Integration	Build parallel integration, test matrix (auth, capture, refund, void), all flows
Token Migration	Export strategy, import tokens, validate mapping, cutover planning
Execution	Ramp 10% → 25% → 50% → 100%, monitor auth rate, migrate recurring billing
Cleanup	Sunset old processor, update docs, post-migration review

Line up four things before Phase 1: the signed contract with the new processor, a live account and test credentials, your current processor's policy on exporting token and card data, and engineering time booked. The third one decides the other three. If your current processor won't put its token export policy in writing before you sign, you aren't planning a migration, you're planning a re-collection project. Find that out now, not in week three.

Trigger Criteria

Use this playbook when:

• You're migrating to a new payment processor
• You're adding a backup processor
• You're consolidating from multiple processors to one
• Current processor relationship is ending

The real cost here is 4-8 weeks of engineering time that isn't going into your product. Weigh the reason against that before Phase 1. Abandon it in week five and you're running two half-built integrations. That's worse than the processor you were unhappy with.

---

Phase 1: Discovery (Week 1-2)

Step 1: Inventory Current State

Document everything about current processor:

Item	Document
Transaction types	One-time, recurring, auth+capture, etc.
Payment methods	Cards, ACH, wallets, local methods
Token format	Vault structure, token format
Recurring billing	Subscription count, billing frequency
Stored credentials	How many cards on file
MIDs	All merchant IDs, per-MID config
Reporting	Settlement, reconciliation, disputes
Integrations	APIs, webhooks, SDKs in use

Step 2: Map to New Processor

Feature	Current	New Processor	Gap?
Card vault	Yes/No	Yes/No
Network tokens	Yes/No	Yes/No
3DS	Version	Version
ACH	Yes/No	Yes/No
Apple/Google Pay	Yes/No	Yes/No
Reporting format	Format	Format

Checkpoint: Feature parity confirmed or gaps documented with workarounds.

Step 3: Token Migration Strategy

Scenario	Approach
Processor supports token migration	Export tokens, import to new processor
No direct migration	Use network tokens (Visa/MC token services)
Neither works	Re-collect cards at next transaction
Account updater available	May help with expired cards during transition

Critical question: Can you export raw PANs or tokens that the new processor accepts?

---

Phase 2: Integration (Week 2-4)

Step 1: Build New Integration

Parallel integration approach:

Step 2: Integration Checklist

• Auth request/response handling
• Capture flow
• Refund flow
• Void flow
• Partial capture (if used)
• 3DS integration
• AVS/CVV handling
• Error handling and retries
• Webhook receivers
• Tokenization flow
• Recurring billing integration

Step 3: Test Matrix

Test Case	Status
Successful card auth
Declined card (various codes)
3DS challenge flow
3DS frictionless flow
Auth + capture
Auth + void
Auth + partial capture
Refund (full)
Refund (partial)
Recurring billing (create)
Recurring billing (charge)
Recurring billing (update)
Apple Pay
Google Pay

Checkpoint: All test cases passing in sandbox.

---

Phase 3: Token Migration (Week 3-5)

Option A: Processor-to-Processor Migration

If new processor accepts imported tokens:

1. Request token export from current processor
2. Transform token format if needed
3. Import tokens to new processor vault
4. Map old token IDs to new token IDs
5. Update your database with new token references
6. Validate sample of migrated tokens

Option B: Network Token Migration

Using Visa/Mastercard network tokenization:

1. Ensure both processors support network tokens
2. Export network tokens (DPAN + cryptograms) from old processor
3. Register network tokens with new processor
4. Network tokens work across processors

Option C: Gradual Re-collection

If migration not possible:

1. Keep old processor active for existing tokens
2. New customers go to new processor
3. At next transaction, existing customers re-enter card
4. Migrate stored credential to new processor
5. Eventually sunset old processor

Rank these A, then B, then C. Option C isn't a strategy, it's attrition on a delay. Every re-entry is a chance for the customer to cancel.

Checkpoint: Migration approach chosen and tested with sample data.

---

Phase 4: Cutover Planning (Week 4-6)

Step 1: Define Cutover Strategy

Strategy	Pros	Cons
Big bang	Clean cutover	High risk
Percentage ramp	Lower risk	Longer timeline
New customers only	Lowest risk	Two systems forever
By segment	Targeted migration	Complexity

Recommendation: Percentage ramp (10% → 25% → 50% → 100%)

Ramp, for almost everyone. A broken integration then lands on a tenth of your revenue instead of all of it. Under $100k a month, big-bang it and go do something else, because at that size the ramp costs more in project management than it saves in risk. The one to avoid is new customers only. It reads as the safe option. It commits you to two integrations, two reconciliations and two support runbooks forever.

Step 2: Create Rollback Plan

Define criteria and process:

Trigger	Action
Auth rate drops 5%+ vs baseline	Pause ramp, investigate
Error rate over 1%	Route back to old processor
New processor outage	Automatic failover to old
Dispute rate spikes	Investigate before proceeding

Step 3: Communication Plan

Stakeholder	What to Communicate	When
Customer support	New error codes, escalation path	1 week before
Finance	New settlement schedule, reconciliation changes	2 weeks before
Engineering	On-call schedule, rollback procedures	1 week before
Customers	Only if checkout UX changes significantly	Optional

---

Phase 5: Migration Execution (Week 5-8)

Step 1: Initial Ramp (10%)

1. Route 10% of new transactions to new processor
2. Monitor for 3-5 days minimum
3. Check:
   • Auth rate vs baseline
   • Error rate
   • Customer complaints
   • Settlement accuracy

Step 2: Expand Ramp (25% → 50% → 75%)

At each stage:

1. Increase traffic percentage
2. Monitor for 2-3 days
3. Verify metrics stable
4. Proceed or troubleshoot

Step 3: Full Cutover (100%)

1. Route 100% to new processor
2. Keep old processor available for fallback
3. Monitor closely for 1 week
4. Begin old processor sunset planning

Step 4: Recurring Billing Migration

Handle separately from one-time payments, and only after one-time traffic has held at 100% for a full week:

1. Identify all active subscriptions
2. Migrate tokens (per Phase 3 approach)
3. Update subscription records with new tokens
4. Test billing on subset of subscriptions
5. Run first full billing cycle with monitoring
6. Validate all charges succeeded

This is the highest-risk step in the whole migration. Give it its own week and its own rollback. If a billing cycle goes wrong you want exactly one variable to look at, and you want the old processor still standing. Don't batch it.

Checkpoint: All traffic on new processor, metrics stable.

---

Phase 6: Cleanup (Week 6-10)

Step 1: Sunset Old Processor

1. Confirm no active traffic to old processor
2. Resolve any pending transactions/settlements
3. Download historical data for records
4. Cancel old processor contract (if applicable)
5. Remove old processor code paths (after stabilization)

Step 2: Update Documentation

• Internal runbooks updated
• Dispute handling procedures updated
• Reconciliation processes updated
• Alert thresholds calibrated for new processor

Step 3: Post-Migration Review

Question	Answer
Auth rate vs pre-migration?
Any lost recurring customers?
Settlement timing acceptable?
Support ticket volume?
Lessons for next migration?

---

Success Criteria

You're done when:

• 100% of traffic on new processor
• Auth rate within 0.5% of pre-migration baseline
• All recurring billing functioning
• Reconciliation process working
• Old processor dependencies removed

The auth rate line is the one that gets waved through. A migration that settles outside that 0.5% band isn't finished, it's a revenue cut you agreed to on a call and then stopped measuring. Compare declines at BIN level and close the gap, or route back.

---

Scale Callout

Volume	Considerations
Under $100k/mo	Can often do big-bang cutover; simpler token migration
$100k-$1M/mo	Percentage ramp recommended; test recurring billing carefully
Over $1M/mo	Dedicated migration team; extended parallel running; fallback essential

---

Where This Breaks

• Token migration fails. Test migration on small sample first. Have re-collection fallback.
• Auth rate tanks. The new processor doesn't have the same issuer relationships. Compare at BIN level before you commit.
• Recurring billing broken. Test billing flow end-to-end before migrating subscriptions.
• Settlement reconciliation off. Different settlement timing/format. Update finance processes.
• Old processor shuts down early. Get the timeline in writing, and keep them live longer than you think you'll need.
• No rollback tested. Test failover before you need it. Don't assume it works.

---

Critical Metrics to Track

Metric	Pre-Migration	During Ramp	Post-Migration
Auth rate	Baseline	Daily	Weekly
Error rate	Baseline	Hourly	Daily
Decline codes	Distribution	Daily	Weekly
Settlement lag	Baseline	Daily	Weekly
Dispute rate	Baseline	Weekly	Monthly

---

Next Steps

After migration is complete:

1. Optimize on new processor: Run auth optimization experiments now that you have fresh baseline
2. Clean up old code: Remove old processor integration after 30-day stability period
3. Update documentation: Runbooks, escalation contacts, API references
4. Renegotiate terms: At 6-month mark, review volume and negotiate better rates
5. Plan redundancy: Consider keeping a backup processor relationship for failover

---

Related

• Auth Optimization - Improving approval rates
• Processor Reporting Checklist - Data requirements
• Settlement & Reconciliation - Post-capture operations
• Benchmarks - Auth rate targets
• Processor Management - Working with processors
• Subscriptions & Recurring - Migrating recurring billing
• 3D Secure - Authentication integration
• Decline Codes - Understanding declines
• Holds and Reserves - Processor reserves
• Payment Change Checklist - Testing changes
• Reading Statements - Understanding processor costs
• Buying Payments - Processor selection criteria