How to migrate to a new payment gateway on WooCommerce (safely)

Introduction

Switching payment gateways on a live WooCommerce store is a change management project, not a one-hour plugin swap. Subscriptions, saved cards, webhooks, refunds, and reporting all depend on processor-specific tokens and events—cutover without a plan risks failed renewals, silent order stuck states, and reconciliation chaos that surfaces weeks later in finance close.

Use this checklist alongside the WooCommerce payment gateway integration checklist, webhook monitoring for WooCommerce, and—if you are buying software—buying a payment gateway plugin for WordPress. For failure handling post-cutover, see payment failure recovery.

Quick answer

Migrate in phases: finalize processor contracts and sandbox tests, run parallel validation (old vs new) on staging, schedule cutover in a low-traffic window, keep a rollback path until webhooks and renewals prove stable. Tokens from the old processor do not transfer magically—plan customer card re-collection or processor-assisted migration when available. Communicate before renewal batches if payment methods must be updated.

1. Why migration is a project (not a plugin toggle)

WooCommerce abstracts checkout UX, but processors differ in:

• Capture models (auth vs capture, partial captures)
• Refund and void semantics
• 3-D Secure and SCA paths by region
• Webhook signing, idempotency, and retry behavior

A green sandbox payment does not prove production renewals, multi-currency, or ERP hooks. Treat migration like a mini launch: owner, runbook, metrics, rollback.

2. Before you touch production

• [ ] Inventory every active payment method, plugin, and integration (subscriptions, ERP, CRM, shipping insurance, marketplace feeds).
• [ ] Confirm the new gateway supports your countries, currencies, capture model, and refund SLAs.
• [ ] Read subscription migration notes for your processor pair—often non-trivial; coordinate with subscriptions and payment gateways.
• [ ] Export recent settlement and dispute reports from the old processor for baseline comparison.
• [ ] Document SSL, domain, and webhook URLs (SSL and insecure checkout if mixed content is a risk).

3. Staging and parallel testing

• Clone production data carefully—never run live keys on staging without processor approval; use test keys and test cards.
• Validate happy path, decline, timeout, and refund on both classic and Blocks checkout if you use both (Blocks article).
• Compare order notes and metadata fields finance relies on—missing transaction IDs break support.

4. Subscriptions and saved payment methods

WooCommerce Subscriptions and similar engines depend on tokens at the processor. Migration may require:

• Asking customers to re-add payment methods, or
• Processor-assisted token migration (when available—not universal)

Plan email cadence and in-app banners before renewal windows. If digital wallets are part of recovery, see digital wallets on WooCommerce.

5. Webhooks, async events, and monitoring

Many gateways finalize state asynchronously. Misconfigured webhook secrets or firewall rules cause paid customer, unpaid order limbo. Pre-cutover:

• Verify endpoint reachability from processor IP allowlists if used.
• Log signature failures without exposing secrets in tickets.
• Run webhook monitoring playbooks for the first 48 hours live.

6. Cutover weekend: sequence

1. Freeze risky changes (theme, unrelated plugins, SEO experiments).
2. Switch API keys and webhook URLs; rotate signing secrets per vendor docs.
3. Run a small live transaction + refund in production; confirm order status and ledger entries.
4. Monitor logs, gateway dashboard, and subscription renewal queue for 48 hours minimum.
5. Compare decline rates to baseline—spikes may indicate mis–configured currency or 3DS (international payments).

7. Customer communications

Be specific: why cards must be updated, by when, and how support helps. Avoid blame—issuer declines and migration cutovers are normal. Link policy pages and align with chargebacks vs refunds if customers confuse refunds with disputes.

8. Rollback and incident response

Keep old gateway credentials disabled but recoverable until success criteria met. Define rollback triggers: spike in failed captures, webhook error rate, subscription batch failure. Post-incident, update common mistakes internal notes so repeat errors shrink.

Post-migration success criteria (define before cutover)

Agree in writing what “done” means: e.g. X hours without webhook signature errors, Y% of test renewals succeeding, refund latency under Z minutes, finance sign-off on settlement report mapping. Without criteria, teams debate whether to rollback while orders stall. Revisit criteria after peak events (Black Friday, month-end B2B invoicing) because volume exposes race conditions and rate limits that staging did not.

9. When to hire integration help

Multi-vendor, split payouts, headless checkout, or no maintained plugin for your processor → custom payment gateway integration or plugin installation support for scoped deployments. PCI scope questions belong in PCI scope for merchants discussions with acquirers, not only in Slack.

FAQ

Can we migrate without asking customers to re-enter cards?
Sometimes—only if processors offer approved token migration programs. Assume re-collection until proven otherwise.

How long should we monitor after cutover?
At least two full billing cycles for subscription-heavy stores; one week minimum for one-off only.

What if renewals fail silently?
Treat as P1: webhooks, plugin logs, processor status—see payment failure recovery.

Should we migrate gateways and redesign checkout in the same release?
Avoid combining high-risk changes unless you have extra rollback capacity. Checkout UX bugs and processor misconfiguration overlap in symptoms—separate releases isolates root cause.

Related reading

• How to evaluate payment gateway plugins
• Payment gateway glossary
• Contact PatSaTECH