Can I migrate Paystack authorization codes (stored cards) to a new gateway?

No — Paystack authorization codes are tokens that point to card data stored in Paystack's PCI-DSS vault. They are not exportable. When you migrate, customers must re-enter their card details on the new gateway. You can smooth this by sending an email asking customers to update their payment method, or by triggering the re-entry flow on the next renewal attempt if the old gateway can no longer charge the card.

What happens to webhooks from the old gateway during migration?

Keep the old webhook endpoint active and processing events throughout migration and for 90 days after cutover. Paystack retries webhooks for up to 72 hours — you may receive events for old-gateway transactions long after you have switched new traffic to the new gateway. If you decommission the old webhook handler too early, those events will be lost and orders may not be fulfilled.

How do I tell customers their subscriptions have moved to a new provider?

For most customers, you should not need to — subscriptions on the old gateway continue to charge normally until they cancel. If you want to migrate customers actively (to get everyone on the new gateway), send a clear email explaining they need to re-enter their payment details, with a link to update their subscription. Offer a small credit or discount for the friction. Expect 20-30% of customers to not complete the update — plan for this in your revenue projections.

By Bonaventure Ogeto|Updated July 22, 2026

Migrating Between Payment Gateways Without Downtime

Gateway migration strategy: 1) Run both gateways in parallel — new transactions go to the new gateway, old webhook handlers stay active for legacy transactions. 2) Migrate one-time checkout first — it is stateless, easiest to validate. 3) For subscriptions: let existing subscriptions run on the old gateway until they cancel or expire; new signups go to the new gateway. 4) Stored card authorizations cannot be migrated — customers must re-enter card details on the new gateway. 5) Keep the old gateway's webhook endpoint active for 90 days after cutover to catch late-arriving events.

Migration Plan

Phase	Action	Duration	Rollback?
1. Preparation	Build and test new gateway integration in staging; set up new webhook endpoint	1-2 weeks	N/A (not live yet)
2. Soft launch	Route 5-10% of new checkouts to new gateway; keep old gateway as default	1 week	Yes — flip routing back
3. Ramp up	Increase new gateway traffic to 50%, then 100% for new checkouts	1-2 weeks	Yes — flip routing back
4. Subscriptions	Route new subscription sign-ups to new gateway; existing on old gateway	Ongoing — subscriptions decay naturally	Partial — new subs on old gateway
5. Old gateway cleanup	Keep old webhook handler active 90 days; then decommission	3 months post-cutover	No (but old gateway account stays open)

// Routing logic during migration (store in DB or env var)
var GATEWAY_ROUTING = {
  new_checkouts: 'new_gateway',    // flip this progressively
  new_subscriptions: 'new_gateway',
  existing_subscriptions: 'old_gateway', // never change this — tokens are gateway-specific
};

async function getGatewayForRequest(type, customerId) {
  if (type === 'subscription_renewal') {
    // Always use the gateway this customer's subscription is on
    var subscription = await db.subscriptions.findByCustomer(customerId);
    return subscription.gateway; // 'old_gateway' or 'new_gateway'
  }
  return GATEWAY_ROUTING[type] || 'new_gateway';
}

Learn More

See building a payment provider abstraction layer — the prerequisite that makes parallel running feasible.

Sign up for the McTaba newsletter

Key Takeaways

✓Run old and new gateways in parallel during migration — never cut over all at once.
✓Migrate one-time checkout first (stateless), subscriptions last (stateful and non-portable).
✓Stored card tokens and subscription codes are not portable between gateways.
✓Keep the old gateway's webhook endpoint active for 90 days post-cutover.
✓Test the full payment flow on the new gateway with real transactions before traffic cutover.

Frequently Asked Questions

Can I migrate Paystack authorization codes (stored cards) to a new gateway?: No — Paystack authorization codes are tokens that point to card data stored in Paystack's PCI-DSS vault. They are not exportable. When you migrate, customers must re-enter their card details on the new gateway. You can smooth this by sending an email asking customers to update their payment method, or by triggering the re-entry flow on the next renewal attempt if the old gateway can no longer charge the card.
What happens to webhooks from the old gateway during migration?: Keep the old webhook endpoint active and processing events throughout migration and for 90 days after cutover. Paystack retries webhooks for up to 72 hours — you may receive events for old-gateway transactions long after you have switched new traffic to the new gateway. If you decommission the old webhook handler too early, those events will be lost and orders may not be fulfilled.
How do I tell customers their subscriptions have moved to a new provider?: For most customers, you should not need to — subscriptions on the old gateway continue to charge normally until they cancel. If you want to migrate customers actively (to get everyone on the new gateway), send a clear email explaining they need to re-enter their payment details, with a link to update their subscription. Offer a small credit or discount for the friction. Expect 20-30% of customers to not complete the update — plan for this in your revenue projections.

Learn Paystack Integration

KES 2,999

The definitive guide to building payment systems with Paystack — from your first transaction to production-grade payment infrastructure across Africa. 9 modules, 47 lessons. Free preview available.

Start Paystack Course

Not ready? Create Free Account

By Bonaventure Ogeto|Updated July 22, 2026

Migrating Between Payment Gateways Without Downtime

Migration Plan

Phase	Action	Duration	Rollback?
1. Preparation	Build and test new gateway integration in staging; set up new webhook endpoint	1-2 weeks	N/A (not live yet)
2. Soft launch	Route 5-10% of new checkouts to new gateway; keep old gateway as default	1 week	Yes — flip routing back
3. Ramp up	Increase new gateway traffic to 50%, then 100% for new checkouts	1-2 weeks	Yes — flip routing back
4. Subscriptions	Route new subscription sign-ups to new gateway; existing on old gateway	Ongoing — subscriptions decay naturally	Partial — new subs on old gateway
5. Old gateway cleanup	Keep old webhook handler active 90 days; then decommission	3 months post-cutover	No (but old gateway account stays open)

// Routing logic during migration (store in DB or env var)
var GATEWAY_ROUTING = {
  new_checkouts: 'new_gateway',    // flip this progressively
  new_subscriptions: 'new_gateway',
  existing_subscriptions: 'old_gateway', // never change this — tokens are gateway-specific
};

async function getGatewayForRequest(type, customerId) {
  if (type === 'subscription_renewal') {
    // Always use the gateway this customer's subscription is on
    var subscription = await db.subscriptions.findByCustomer(customerId);
    return subscription.gateway; // 'old_gateway' or 'new_gateway'
  }
  return GATEWAY_ROUTING[type] || 'new_gateway';
}

Learn More

See building a payment provider abstraction layer — the prerequisite that makes parallel running feasible.

Sign up for the McTaba newsletter

Key Takeaways

✓Run old and new gateways in parallel during migration — never cut over all at once.
✓Migrate one-time checkout first (stateless), subscriptions last (stateful and non-portable).
✓Stored card tokens and subscription codes are not portable between gateways.
✓Keep the old gateway's webhook endpoint active for 90 days post-cutover.
✓Test the full payment flow on the new gateway with real transactions before traffic cutover.

Frequently Asked Questions

Can I migrate Paystack authorization codes (stored cards) to a new gateway?: No — Paystack authorization codes are tokens that point to card data stored in Paystack's PCI-DSS vault. They are not exportable. When you migrate, customers must re-enter their card details on the new gateway. You can smooth this by sending an email asking customers to update their payment method, or by triggering the re-entry flow on the next renewal attempt if the old gateway can no longer charge the card.
What happens to webhooks from the old gateway during migration?: Keep the old webhook endpoint active and processing events throughout migration and for 90 days after cutover. Paystack retries webhooks for up to 72 hours — you may receive events for old-gateway transactions long after you have switched new traffic to the new gateway. If you decommission the old webhook handler too early, those events will be lost and orders may not be fulfilled.
How do I tell customers their subscriptions have moved to a new provider?: For most customers, you should not need to — subscriptions on the old gateway continue to charge normally until they cancel. If you want to migrate customers actively (to get everyone on the new gateway), send a clear email explaining they need to re-enter their payment details, with a link to update their subscription. Offer a small credit or discount for the friction. Expect 20-30% of customers to not complete the update — plan for this in your revenue projections.

Learn Paystack Integration

KES 2,999

The definitive guide to building payment systems with Paystack — from your first transaction to production-grade payment infrastructure across Africa. 9 modules, 47 lessons. Free preview available.

Start Paystack Course

Not ready? Create Free Account