# Ecommerce Payment Migration

> A practical guide to ecommerce payment migration, including scope, transfer checks, launch evidence and recovery planning.

- Type: Merchant guide
- Level: Intermediate
- Reading time: About 4 minutes
- Audience: Written for store owners, builders, and designers refining high-performance ecommerce stores.
- Last updated: 2026-11-04
- Canonical page: https://academy.getzenbasket.com/merchant-questions/ecommerce-payment-migration/
- Part of: [Merchant Questions](https://academy.getzenbasket.com/merchant-questions/) on ZenBasket Academy

---

## What you need to know

### How should payment gateways be migrated?

Configure the gateway through provider-supported credentials and callbacks, then map payment states to order states. Test authorization, capture, failure, cancellation, refund and reconciliation before launch.

### Can stored payment methods be migrated?

Stored payment methods can move only through a provider-supported, authorized portability process. Raw card data must never pass through ordinary migration files or staff tools.

### How should payment tokens be handled during migration?

Treat tokens as provider-scoped payment credentials. Confirm portability and compatibility, restrict access, reconcile ownership, and request customer reauthorization when a safe transfer is unavailable.

### How should payment methods be tested before launch?

Test every enabled payment method from authorization through capture, decline, cancellation, and refund. Confirm the gateway and order show the same final state without duplicate charges.

### How should refunds for pre-migration orders work?

Keep the legacy gateway and order records available for refunds on old orders. Define which system staff use, who can approve the refund and how finance reconciles it.

### How should payment reconciliation work during migration?

Match each gateway transaction to one order using stable identifiers, amount, currency, and final state. Investigate missing, duplicate and mismatched records before launch.

### What happens if payment works, but order creation fails on the new platform?

Place the order in a recoverable payment-exception state, prevent another automatic charge and reconcile the gateway event before retrying order creation or refunding. Never ask the customer to pay again until the first charge is understood.

### A quick store check

Test one success, decline, timeout, cancellation and refund for every enabled method, then reconcile gateway and order states.

---

## Frequently asked questions

### Can the old gateway be turned off at launch?

Not if old orders still require refunds, disputes, or reconciliation. Define the legacy operating period first.

### Should payment credentials be placed in test exports?

No. Use provider-supported secure setup and restrict credentials to the required environment and owners.

## Related articles

- **Ecommerce Integration Migration**
- **Ecommerce Subscription Migration**
- **Ecommerce Payment Troubleshooting and Audit**