Paybyrd Paybyrd
Sign Up Free
The migration playbook · 2026 edition

How to leave your current processor without breaking payments.

A 47-point runbook from the engineers who migrated TAP Air Portugal, Vila Galé, Prozis and KuantoKusta. Phased framework, technical + commercial checklists, honest red flags. Written the way we'd brief our own team — not as a sales deck.

Want the full runbook in your inbox? One email with every section above, plus links to copy-paste into your team's Confluence / Notion.

No marketing list. One email with the runbook + a follow-up 14 days later to check how it went.

What's inside
  1. 01Why most migrations fail
  2. 02The 5-phase framework
  3. 03Technical migration checklist
  4. 04Commercial checklist
  5. 05Questions to ask before you tell them you're leaving
  6. 06When NOT to switch
  7. 0722 days to live traffic · Vila Galé
  8. 0830-60-90 post-migration
01 · Why most migrations fail

It's almost never the integration.

We've run the diff on dozens of migrations — ours and competitors'. When one goes sideways, the root cause is usually in the same five places. Knowing them in advance turns a risky 60-day project into a boring 22-day one.

  1. 01

    The all-or-nothing cutover

    Team flips 100% of traffic on Monday morning. By Tuesday at 11, the diff reveals subscription re-auth failures no one caught in sandbox. Rolling back now means flipping traffic again, re-triggering the same failure modes in reverse. Always migrate via parallel processing with a staged ramp — 5% → 20% → 50% → 100% over 2–4 weeks.

  2. 02

    Card-token re-auth at scale

    You have 80,000 customers on file with saved cards. The new processor doesn't support network-token import from your current vendor. Result: 80,000 re-authentication emails over two weeks, hundreds of churned customers from confused senior shoppers, and a CS team drowning in tickets. Always verify network-token portability before signing.

  3. 03

    Reconciliation drift during the handoff

    Your current processor pays T+2. New one is T+1. During parallel processing, your finance team is reconciling two schedules against one ERP. One payout lands under the wrong month, one refund shows up twice, and the CFO loses trust in the numbers for the whole quarter. Align ledger mapping BEFORE flipping any traffic.

  4. 04

    Webhook endpoint mismatches

    Old processor fires payment.captured. New one fires transaction.succeeded. Both look right in isolation. Together they bypass your order-fulfilment logic — payments process fine, but nothing ships. Stand up new webhook handlers before cutting a single transaction over, and replay historical events against them for a week.

  5. 05

    Missing PCI-scope paperwork

    New processor uses a different embedded component pattern. Your merchant's auditor asks for an updated SAQ. Eight weeks pass. In the meantime you can't touch the checkout page without re-scoping. Get the Attestation of Compliance (AoC) + SAQ type from the new processor in writing at evaluation — not after go-live.

Want this as an editable runbook doc?

Drop your email — we'll send the full playbook as a single email your team can archive, plus a 14-day nudge to check how migration planning is going.

↓ Or keep scrolling — the full playbook is below, organised by section.

02 · The 5-phase framework

Contract to 100% live traffic, in five phases.

We publish these timelines as defaults. For the majority of merchants under €500M annual volume, this framework ships cleanly in 20–28 business days without customer-visible disruption. Enterprise accounts with complex reconciliation stacks can add another 2–4 weeks.

  1. Phase 0 · Pre-work
    Week 0
    Stakeholder alignment

    Name the owner on both sides. Confirm CFO has signed off on the parallel-processing cost. Freeze the feature backlog for the migration window.

  2. Phase 1 · Onboard
    Week 1–2
    Sandbox + integration

    Certify sandbox. Stand up parallel webhook endpoints. Export historical data. Test 10 real tokens end-to-end.

  3. Phase 2 · Parallel
    Week 3–4
    5–20% live traffic

    Tagged transactions run through both sides. Diff reports daily. Finance validates one payout cycle before expanding.

  4. Phase 3 · Ramp
    Week 5–6
    Graduated cutover

    20% → 50% → 80% → 100%. You hold the rollback switch. Paybyrd's SREs sit on your Slack channel during each bump.

  5. Phase 4 · Validate
    Week 7–8
    Sunset + stabilise

    Close old processor to new volume. Reserve release scheduled. Chargeback-tail ownership mapped. 30-60-90 validation plan armed.

03 · Technical migration checklist

The 36-point technical pass.

Work through every item before Phase 2. Cross out what doesn't apply to your stack (e.g. no subscriptions = skip the tokenisation group). The rest is non-negotiable.

Integration surface

4 items
  • Inventory every codepath that calls the current processor (checkout, subscriptions, refunds, admin tools, reporting exports, customer-service panels).
  • Identify SDK versions in production — some endpoints are version-pinned; the new processor may need matching versions or a parallel lib.
  • Document the existing webhook handlers and their idempotency guarantees before touching anything.
  • Catalog every test card / test account currently hard-coded. They won't work on the new side.

Data handoff

5 items
  • Export the full transaction history (at least 18 months) in both CSV and processor-native format. You'll need it for refunds, chargebacks and tax audits long after cutover.
  • Export all stored card tokens with their expiry metadata — you'll reference these when importing to the new processor's vault.
  • Export customer records, subscription schedules, payment plans and saved payment methods.
  • Snapshot the chargeback history (including arbitration stages) — the new processor inherits dispute obligations for in-flight cases.
  • Preserve all PCI attestation documents. Auditors will ask.

Tokenisation & subscriptions

4 items
  • Confirm the new processor supports network-token import from your current vendor (Visa/Mastercard network tokens are portable; brand-specific proprietary tokens often aren't).
  • For subscriptions: decide on re-auth strategy. Network-token porting avoids customer-visible re-auth. Proprietary tokens mean re-entry at next bill — plan the comms.
  • Test the migration on a sample of 10 real tokens end-to-end before bulk-migrating.
  • Verify 3DS2 step-up flows on the new side for recurring and merchant-initiated transactions.

Webhooks & async

4 items
  • Stand up new webhook endpoints alongside existing ones; don't replace until parallel processing validates parity.
  • Replay tests: can the new endpoint handle an old payload shape? (Your backfill / reconciliation tools may still send legacy events for weeks.)
  • Verify idempotency keys work identically on the new side. Double-capture / double-refund are the classic migration bugs.
  • Confirm webhook retry policies are compatible with your existing at-least-once tolerance.

Fraud & risk

4 items
  • Export current fraud rules (block lists, velocity rules, geo restrictions) and translate to the new engine's grammar — do not copy-paste.
  • Run shadow mode on the new fraud stack for 2–3 weeks before enabling decisioning.
  • Verify 3DS2 challenge flow on the new side matches customer expectations (same UI transition, same success/failure UX).
  • Sync BIN lists, issuer-level rules, and card-brand-specific logic.

Reconciliation & finance

4 items
  • Map the new payout schedule to your existing ledger / ERP. T+0 / T+1 / T+2 differences break automated reconciliation silently.
  • Confirm per-outlet / per-SKU / per-channel breakdown available on the new side matches (or exceeds) your current operational reports.
  • Align the first month's cut-off dates between old + new so finance can close books without double-counting.
  • Tag parallel-processed transactions on both sides with a shared identifier (your order ref is ideal) for automated diff reporting.
04 · Commercial checklist

Before your legal team touches the new contract.

Engineering gets the headlines; procurement decides whether the migration actually pays back. These three groups are the ones your CFO needs answered before sign-off.

Exit terms with current processor

3 items
  • Read the contract. Notice period, exit fees, data-export obligations, chargeback-tail handling, reserve release schedule.
  • Confirm the date of your last new-volume transaction does NOT trigger early-termination penalties.
  • If your current processor offers any incentive to stay, get it in writing and evaluate it against total migration value.

Acquirer / scheme arrangements

3 items
  • If you hold direct acquirer contracts separately, you don't need to move them — most orchestrators (Paybyrd included) sit above.
  • Negotiate with the new processor whether to consolidate acquiring or keep your existing agreements.
  • Review interchange++ terms carefully; blended pricing and IC++ have very different cash-flow implications at scale.

Reserves & holds

3 items
  • Get written commitments on when held reserves will be released after migration (standard is 180 days post last new transaction).
  • Confirm chargeback-tail ownership: your current processor is still on the hook for disputes arising from pre-migration transactions.
  • Surcharge and DCC revenue shares — understand both sides before you flip.
05 · Questions to ask before you tell them you're leaving

Support priority drops the moment you announce.

Do the data-export and reserve-release work before the conversation. Once notice is filed, your current processor's incentive to help you export smoothly is zero. Sequence matters.

  1. 01 Can I export 24 months of transaction history in their native format AND standard CSV, today, unattended?
  2. 02 Does network-token porting work for our Visa + Mastercard on-file base? (Answer: yes, always — but confirm in writing.)
  3. 03 When does reserves hold release and what's the schedule? (Standard: 180 days post last new transaction.)
  4. 04 Who owns chargebacks and disputes filed after migration against pre-migration transactions? (Answer: the old processor, but get it documented.)
  5. 05 What's the cadence of dispute notification after our account is closed to new volume? (Some degrade to monthly batches — brutal for response SLAs.)
  6. 06 Do we lose access to the admin dashboard immediately on migration, or is there a read-only grace period? (Ask for 180 days; many grant 90.)
  7. 07 Are there any minimum-volume clauses that trigger penalties if we ramp down during parallel processing?
  8. 08 For subscription businesses: does our recurring agreement transfer automatically with network-token porting, or do we owe customer-facing re-auth notices?
06 · When NOT to switch

We'll tell you when it's a bad idea.

Not every quarter is a good migration quarter. Here are the five situations where the honest answer is "wait" — even if you're sure the new numbers are better.

You're entering peak season in < 8 weeks.

Even a clean 22-day migration has operational tails. Don't migrate into Black Friday / Christmas / summer travel peak. Plan the cutover for your quietest six-week window.

Your tech team is one or two engineers.

Parallel processing demands monitoring both sides simultaneously. If you don't have bandwidth, negotiate more migration support from the new processor or phase the project over 3+ months.

You haven't exported everything yet.

The day you announce the switch is the day your current processor's support priority drops. Do the exports first, sign second.

Your checkout is deeply custom with no test coverage.

Parallel processing is how you discover mismatches. If you can't instrument both sides with diff reports, you're flying blind.

Your contract has a variable surcharge that triggers on volume drops.

Parallel processing will briefly split your volume. Read the fine print — some contracts penalise this.

07 · The 22-day migration · Vila Galé

Contract Monday. Live traffic three weeks later.

Vila Galé runs 40+ hotels across Portugal and Brazil with a unified booking engine, on-property POS, and a growing mobile channel. Their migration from their previous processor to Paybyrd was the fastest enterprise-scale hospitality migration we've run — here's what the timeline actually looked like.

Hotels migrated
40+
Channels unified
Web + POS + Kiosk
Contract to live
22 days
Customer disruption
Zero
  1. Day 1 · Contract signed

    Integrations team paired. Sandbox credentials delivered inside 4 hours. 18 months of transaction history exported from the old side by Day 3.

  2. Day 4–9 · Parallel endpoints up

    New webhook listeners deployed alongside old ones. Network-token porting for 200K card-on-file records validated on a 50-row sample. Sandbox certified against real staging booking flow.

  3. Day 10–14 · 5% live traffic

    Paybyrd handled 1 in 20 real transactions for 5 days. Diff report ran every morning. Only anomaly: a rounding drift on city tax that surfaced inside 24 hours. Fixed by Day 11.

  4. Day 15–19 · 20% → 50% → 80%

    Graduated bumps. Finance team ran their month-end close on parallel-processed volume — reconciliation matched within 4 cents on €3.2M of booked revenue.

  5. Day 20–22 · 100% cutover

    Old processor closed to new volume on Day 20. 30-day reserve release scheduled. Paybyrd's SRE on-call sat in their Slack for the first week post-cutover. Zero customer-visible incidents.

"Finance closes the day in hours, not Mondays. The migration itself was less disruptive than a normal release week."

— Vila Galé, post-migration retrospective
08 · 30-60-90 post-migration

The three windows where it still matters.

Cutover is not the finish line. Most migrations that "went live clean" still leak value for two reasons: chargeback-tail handoff drifts, and approval-rate parity isn't validated against the new baseline.

Day 0 – 30

Stabilise

  • • Daily approval-rate diff against the old baseline.
  • • Weekly reconciliation audit (first payout cycle).
  • • Customer-service ticket-volume drift monitored. (Spike = something slipped through diff reports.)
  • • Chargeback-tail notification channel from old processor confirmed working.
Day 30 – 60

Optimise

  • • Tune multi-acquiring routing against your actual decline patterns.
  • • Enable fraud decisioning after 3-week shadow-mode observation.
  • • First full calendar month of reporting — CFO review.
  • • Reserve release scheduled, 180 days from last transaction.
Day 60 – 90

Validate the business case

  • • Blended cost-per-transaction vs the old baseline — does the actual saving match the projection?
  • • Approval-rate lift materialised?
  • • Support ticket volume on parity or better?
  • • Net-new capabilities enabled (DCC revenue share, InstaTax, customer intelligence, etc.) — any revenue generated yet?

Still here? Put numbers against it.

30 minutes with a senior payment engineer. Bring your most recent processor statement. We'll walk through this framework against your actual stack, and you'll leave with a written 22-day migration plan — whether you go with Paybyrd or not.

Book 30 min with an engineer