Skip to main content

Processor Switch Checklist (Playbook)

Switching processors is high-stakes. Mess up the migration and you lose recurring revenue, break checkout, or create reconciliation nightmares. This playbook keeps the transition clean.

Timeline: 4-8 weeks minimum. Complex migrations take 12+ weeks.

Workflow Overview​

PhaseKey Tasks
DiscoveryInventory current processor, map features to new, define token strategy
IntegrationBuild parallel integration, test matrix (auth, capture, refund, void), all flows
Token MigrationExport strategy, import tokens, validate mapping, cutover planning
ExecutionRamp 10% → 25% → 50% → 100%, monitor auth rate, migrate recurring billing
CleanupSunset old processor, update docs, post-migration review

Prerequisites: New processor contract signed, test credentials, token export policy known, engineering resources allocated.

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

Prerequisites​

Before starting:

  • New processor contract signed
  • New processor account approved and live
  • Test credentials for new processor
  • Current processor token/card data export policy known
  • Engineering resources allocated

Phase 1: Discovery (Week 1-2)​

Step 1: Inventory Current State​

Document everything about current processor:

ItemDocument
Transaction typesOne-time, recurring, auth+capture, etc.
Payment methodsCards, ACH, wallets, local methods
Token formatVault structure, token format
Recurring billingSubscription count, billing frequency
Stored credentialsHow many cards on file
MIDsAll merchant IDs, per-MID config
ReportingSettlement, reconciliation, disputes
IntegrationsAPIs, webhooks, SDKs in use

Step 2: Map to New Processor​

FeatureCurrentNew ProcessorGap?
Card vaultYes/NoYes/No
Network tokensYes/NoYes/No
3DSVersionVersion
ACHYes/NoYes/No
Apple/Google PayYes/NoYes/No
Reporting formatFormatFormat

Checkpoint: Feature parity confirmed or gaps documented with workarounds.

Step 3: Token Migration Strategy​

ScenarioApproach
Processor supports token migrationExport tokens, import to new processor
No direct migrationUse network tokens (Visa/MC token services)
Neither worksRe-collect cards at next transaction
Account updater availableMay 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 CaseStatus
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

Checkpoint: Migration approach chosen and tested with sample data.

Phase 4: Cutover Planning (Week 4-6)​

Step 1: Define Cutover Strategy​

StrategyProsCons
Big bangClean cutoverHigh risk
Percentage rampLower riskLonger timeline
New customers onlyLowest riskTwo systems forever
By segmentTargeted migrationComplexity

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

Step 2: Create Rollback Plan​

Define criteria and process:

TriggerAction
Auth rate drops 5%+ vs baselinePause ramp, investigate
Error rate over 1%Route back to old processor
New processor outageAutomatic failover to old
Dispute rate spikesInvestigate before proceeding

Step 3: Communication Plan​

StakeholderWhat to CommunicateWhen
Customer supportNew error codes, escalation path1 week before
FinanceNew settlement schedule, reconciliation changes2 weeks before
EngineeringOn-call schedule, rollback procedures1 week before
CustomersOnly if checkout UX changes significantlyOptional

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:

  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

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​

QuestionAnswer
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

Scale Callout​

VolumeConsiderations
Under $100k/moCan often do big-bang cutover; simpler token migration
$100k-$1M/moPercentage ramp recommended; test recurring billing carefully
Over $1M/moDedicated 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. New processor may have different issuer relationships. Compare BIN-level before committing.
  • 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 written timeline. Keep old processor available longer than planned.
  • No rollback tested. Test failover before you need it. Don't assume it works.

Critical Metrics to Track​

MetricPre-MigrationDuring RampPost-Migration
Auth rateBaselineDailyWeekly
Error rateBaselineHourlyDaily
Decline codesDistributionDailyWeekly
Settlement lagBaselineDailyWeekly
Dispute rateBaselineWeeklyMonthly

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