Changing Payment Provider With a Custom API: An Enterprise PSP Migration Guide 

An Enterprise PSP Migration Guide

Changing payment provider sounds straightforward in procurement.

Select a new PSP. Agree commercial terms. Build the integration. Switch traffic.

For an established business with a custom payment integration, it rarely works like that.

Your existing payment provider may already sit inside:

checkout → customer accounts → subscriptions → tokens → fraud → 3DS → refunds → finance → webhooks → reporting → reconciliation

It may also control thousands or millions of stored payment credentials.

So when a CTO says:

“We can integrate another API.”

that may be technically correct.

But it does not answer the harder question:

“Can we move the payment estate without disrupting customers, recurring revenue or finance operations?”

For an enterprise merchant, a PSP migration should therefore be treated as a controlled production migration, not simply another supplier switch.

This guide is primarily for established businesses with bespoke payment infrastructure, significant processing volume or recurring/card-on-file payments that are considering changing PSP, gateway or acquiring architecture.

For the broader commercial decision, see the MAS High-Volume Merchant Processing guide and the Payments Strategy Library.

---

Quick Summary

The hardest part of changing payment provider is often not accepting the first transaction through the new API.

It is everything surrounding that transaction.

A serious migration may need to account for:

• checkout;
• API calls;
• webhooks;
• customer identifiers;
• stored cards;
• network and PSP tokens;
• subscriptions;
• merchant-initiated transactions;
• 3D Secure;
• refunds;
• partial captures;
• voids;
• disputes;
• alternative payment methods;
• fraud rules;
• reporting;
• settlement;
• reconciliation;
• finance integrations;
• customer service tools;
• testing;
• rollback; and
• transactions still completing on the old PSP.

For larger migrations, running the old and new payment providers in parallel is often more realistic than a single overnight cutover.

Current provider documentation supports this approach. Stripe's current migration guidance describes taking new customers through Stripe while existing customers continue being charged by the incumbent processor until their payment data has migrated. Adyen similarly recommends a staged migration and says payment-data migration usually takes 10 days or more because of technical and compliance complexity. 

The objective should not be:

“Switch the API.”

It should be:

“Move payment processing while preserving customer and financial continuity.”

---

Find Your New Processor

Your PSP Is Probably More Deeply Embedded Than You Think

Ask a development team where the existing payment provider appears in the codebase.

The first answer might be:

Checkout.

Then keep asking.

How are refunds triggered?

How are disputes received?

How does finance identify settlement?

How are failed subscriptions retried?

Where are card tokens stored?

What happens when a payment needs 3D Secure?

How does customer service find a transaction?

What happens after an asynchronous payment method completes?

What system marks the order as paid?

What happens if the webhook never arrives?

Suddenly the PSP is not one integration.

It is a dependency shared across several business processes.

---

The API Endpoint Is Usually the Easy Bit

At its simplest, the payment flow might appear to be:

Create payment → receive response → fulfil order

A mature implementation is rarely that simple.

It may actually be:

Create payment

↓

Authentication required?

↓

Customer completes 3DS

↓

Authorisation

↓

Webhook received

↓

Order status updated

↓

Capture now or later

↓

Settlement received

↓

Finance reconciles

↓

Possible refund/dispute weeks later

Each provider may represent these states differently.

One PSP might call something:

authorised

while another has separate objects for:

payment created → payment requires action → payment processing → payment succeeded

This is why a successful sandbox transaction does not prove that the migration is ready.

---

Start by Mapping the Payment Contract Your Code Has With the PSP

Before designing the new integration, document what the existing provider actually does.

Not the commercial contract.

The technical contract.

For example:

This is the real migration scope.

MAS View

Don't start with the new PSP's API documentation. Start with everything your business currently expects the old PSP to do.

Only then compare the two.

---

Webhooks Are Where Migrations Often Become More Complicated

Modern payment systems rely heavily on asynchronous events.

Your application sends a request.

Something happens later.

The provider then tells you about it via webhook.

Examples include:

• payment succeeded;
• payment failed;
• refund completed;
• dispute opened;
• subscription renewed;
• payout completed;
• chargeback updated.

But webhook behaviour is not universal.

Stripe's current technical documentation, for example, explicitly warns developers that webhook events are not guaranteed to arrive in the order they were generated and that the same event may sometimes be delivered more than once. It recommends designing endpoints to handle duplicate events and asynchronous processing. 

That is useful beyond Stripe.

It demonstrates why your business logic should not blindly assume:

webhook received = run action once

or:

events arrive in perfect sequence.

During a migration, you may also temporarily need to process events from:

old PSP + new PSP

at the same time.

---

Find Your New Processor

Don't Translate Provider A's Webhooks Directly Into Provider B's

This is an architectural opportunity.

Imagine your application currently contains logic like:

if Stripe payment_intent.succeeded → mark order paid

You migrate to another provider.

The tempting solution is:

if NewPSP.payment.completed → mark order paid

That works.

But your internal business logic is still coupled directly to whichever PSP is live.

A more portable model is:

PSP-specific event

↓

payment abstraction layer

↓

internal event: PAYMENT_CONFIRMED

↓

order system

Now your commercial systems understand your language — not the PSP's.

That makes future switching easier.

It can also make multi-provider payments much more realistic.

---

Your Internal Payment IDs Matter More Than They Seem

Imagine a customer exists in your database as:

customer_18472

But in your current PSP they are:

cus_A827DK

and in the new PSP:

shopper_H6JG8

If your internal systems have treated the PSP customer ID as the primary customer identity, migration becomes unnecessarily difficult.

The same applies to:

• payment IDs;
• subscriptions;
• payment methods;
• mandates;
• transactions; and
• refunds.

A mature payment architecture should ideally maintain its own canonical identifiers and map external provider IDs against them.

This is particularly important during dual running.

One customer may temporarily have:

Internal customer ID → old PSP customer ID → new PSP customer ID

at the same time.

---

Stored Cards Turn an Integration Project Into a Migration Project

This is where the commercial and technical sides collide.

A merchant processing only one-off payments can potentially send future customers to the new provider and let the old infrastructure disappear naturally.

A subscription business cannot.

Imagine:

400,000 active subscriptions

with payment credentials tokenised by the incumbent PSP.

Those customers expect their next payments to happen automatically.

You cannot normally ask all 400,000 to enter their card details again without creating significant churn.

That means the token estate needs its own migration workstream.

Our existing guide to moving stored cards, payment tokens and recurring payments between gateways covers this issue in more detail.

---

A Good Token Migration Has Two Moving Targets

This is something provider migration guides often underestimate.

Imagine you export your stored-card population on Monday.

It takes several days to transfer, import and validate it.

During that time:

• new customers sign up;
• existing customers change cards;
• cards expire;
• subscriptions renew;
• Account Updater changes credentials;
• customers cancel; and
• new tokens are created.

So the migration dataset is already changing while you are moving it.

Stripe's current guidance specifically warns that customer payment-method changes occurring between data transfer and completion of an import can be lost unless the merchant designs around that window. 

This is one reason staged migrations are safer.

---

The Cleanest Switch Is Often Not a Switch

For larger businesses, the better model may be a progressive migration.

Consider:

Phase 1 — Build

The old PSP handles live traffic.

The new integration is built and tested.

Phase 2 — Start new traffic

New customers begin tokenising and paying through the new PSP.

Existing recurring customers remain on the incumbent.

Phase 3 — Run both

Payments occur through both environments.

Finance reconciles both.

Support teams can see both.

Phase 4 — Migrate stored credentials

Existing customers progressively move across.

Phase 5 — Shift remaining traffic

Remaining payment flows move to the new provider.

Phase 6 — Drain the old environment

Old refunds, disputes, settlements and residual activity continue to be handled.

Phase 7 — Decommission

Only when there is no remaining operational dependency should the old environment be shut down.

This is broadly consistent with the staged approach described in current Adyen and Stripe migration documentation. 

---

The Old PSP Can Remain Operational Long After New Payments Stop

This catches businesses out.

Suppose the final new transaction goes through PSP A on:

1 October

That does not mean PSP A can be switched off on:

2 October.

You may still receive:

• refunds;
• chargebacks;
• disputes;
• settlement;
• retrieval requests;
• recurring payments not yet migrated;
• reversals;
• delayed payment notifications; and
• finance reports.

Your contract termination date and your last new payment date may therefore need to be different.

---

A Custom API Migration Needs a Cutover Strategy

The board may hear:

“We're going live on 14 March.”

Engineering needs a much more precise definition.

Does that mean:

10% of traffic?

All new customers?

One market?

One legal entity?

One payment method?

One ecommerce brand?

All payment traffic?

An enterprise migration should define exactly what “live” means.

---

Use Traffic Segmentation Instead of an All-or-Nothing Cutover

A custom payment architecture may allow traffic to be migrated incrementally.

For example:

Week 1: internal/test transactions

Week 2: 1% of new ecommerce traffic

Week 3: 10%

Week 4: 25%

Week 5: 50%

Week 6: 100% new traffic

Or segmentation might be by:

• country;
• legal entity;
• brand;
• payment method;
• customer type;
• channel;
• card type; or
• transaction value.

That makes it possible to compare payment performance before committing the entire estate.

---

Find Your New Processor

Parallel Running Gives You Something Procurement Cannot: Real Comparative Data

Suppose the incumbent PSP reports:

Authorisation rate: 92.8%

The new provider claims it can improve acceptance.

A presentation cannot prove that.

Live traffic can.

If both providers run simultaneously for a controlled period, the business can potentially evaluate:

• authorisation;
• latency;
• payment errors;
• 3DS conversion;
• fraud;
• refunds;
• operational issues;
• reconciliation; and
• support.

This can be especially valuable where the original reason for switching is performance rather than simply price.

See the MAS guide to improving payment authorisation rates for enterprise merchants.

---

Don't Measure the New PSP Using Different Traffic

There is a trap here.

Suppose:

PSP A handles existing UK customers

while:

PSP B handles new international customers.

PSP B might appear to have poorer authorisation.

That may be caused by the traffic mix rather than the provider.

Useful comparisons should control for factors such as:

• market;
• card type;
• customer profile;
• transaction value;
• authentication;
• device;
• new versus returning customer; and
• payment method.

Otherwise the business can draw the wrong conclusion.

---

Refunds Are Easy to Forget During Design

The development team naturally focuses on accepting payments.

Operations often care just as much about everything that happens afterwards.

A PSP migration needs to answer:

Can we refund an old-provider transaction after cutover?

Which admin interface will support use?

Does customer service know which provider owns the payment?

Can partial refunds still be processed?

What happens if the original merchant account has closed?

How does finance identify refunds across both providers?

Refunding the wrong PSP is impossible.

Your internal systems therefore need to preserve the relationship between:

order → payment → provider

for as long as the transaction could reasonably require further action.

---

Disputes Have an Even Longer Tail

Chargebacks and payment disputes may arise well after the original transaction.

A business could therefore be processing all new payments through the new PSP while still managing disputes through the incumbent.

That means the old provider may continue to require:

• portal access;
• user permissions;
• finance processes;
• evidence submission;
• notifications; and
• staff training.

Do not decommission operational knowledge too early.

---

Settlement and Reconciliation Deserve Their Own Testing

A payment can succeed perfectly while finance concludes the migration has failed.

Why?

Because:

payment accepted

does not automatically mean:

money correctly reconciled.

Finance needs to understand:

• settlement references;
• payout reports;
• fees;
• gross/net settlement;
• currencies;
• merchant accounts;
• legal entities;
• refund treatment;
• chargebacks;
• reserve deductions;
• timing; and
• how transactions map back to internal orders.

This is especially important during dual running.

For several months finance may need to reconcile:

PSP A settlements + PSP B settlements

against one underlying sales ledger.

---

The Finance Team Should Be Involved Before Go-Live

A common project pattern is:

Procurement selects provider

↓

Engineering builds integration

↓

Finance sees settlement format after launch

That is backwards.

Finance should validate:

• report availability;
• field-level data;
• settlement frequency;
• transaction identifiers;
• fee reporting;
• currency reporting;
• reconciliation logic; and
• accounting-system integration

before production migration.

For a £50m merchant, reconciliation failure is not a minor inconvenience.

---

3D Secure Should Be Re-Tested, Not Assumed

Two PSPs may both support EMV 3-D Secure.

That does not mean the resulting payment journey is identical.

The integration may differ around:

• exemptions;
• challenges;
• browser flows;
• app flows;
• soft declines;
• authentication data;
• retries; and
• merchant-initiated transactions.

A migration test plan therefore needs more than:

successful card / declined card

It should test actual customer journeys.

---

Build a Payment Migration Scenario Library

Instead of a generic test checklist, use the business's actual payment behaviour.

For example:

New customer

First purchase with 3DS.

Returning customer

Stored card checkout.

Subscription renewal

Customer not present.

Expired card

Account Updater or failed-payment journey.

Partial capture

Authorise £500, capture £420.

Refund

Refund £75 of a £200 transaction.

Authentication failure

Customer abandons challenge.

Soft decline

Payment requires further authentication.

Timeout

No immediate API response.

Duplicate request

Can the system prevent double charging?

Missing webhook

Can payment state be recovered?

Duplicate webhook

Does fulfilment happen twice?

Events arriving out of order

Does the system still reach the correct state?

Those last cases matter. Current Stripe documentation specifically notes that events may be duplicated and are not guaranteed to arrive in sequence. 

---

Test the Failure Paths Harder Than the Success Path

The easiest transaction to process is:

£10 Visa → authorised → captured → webhook arrives immediately

That is not where production failures usually hide.

Test:

authorised but webhook delayed

customer closes browser after successful payment

API times out but transaction actually succeeds

refund accepted asynchronously

duplicate request submitted

provider outage

3DS challenge completed after customer session expires

payment accepted but internal order update fails

PSP B unavailable during staged migration

A custom integration needs to know how the business recovers from ambiguity.

---

Rollback Needs to Be Designed Before Cutover

A migration plan that only works when everything goes correctly is incomplete.

Before moving traffic, answer:

What condition triggers rollback?

For example:

• authorisation falls below threshold;
• payment error rate exceeds threshold;
• webhooks stop processing;
• settlement files fail;
• fraud behaviour changes unexpectedly; or
• operational incidents exceed tolerance.

Then answer:

Can we actually route traffic back?

If the new integration changes database structures irreversibly, rollback may be far harder than the project team assumes.

---

Find Your New Processor

The MAS Payment Migration Control Table

For a significant migration, I would want something like this in the project governance.

That gives a CFO, CTO and project team a shared definition of progress.

---

Don't Make the Next PSP Migration as Hard as This One

One of the most useful outcomes from switching provider can be improving the architecture for the future.

A merchant does not need to build a full payment-orchestration platform.

But it may be worth reducing provider-specific logic in core business systems.

Instead of:

Order system → PSP A

consider:

Order system → internal payments service → PSP

The internal layer can standardise concepts such as:

• payment;
• authorisation;
• capture;
• refund;
• payment method;
• token;
• provider;
• merchant account;
• settlement identifier.

Then the provider-specific adapter handles the API differences.

This doesn't make future migrations effortless.

It can make them considerably less invasive.

---

A PSP-Agnostic Architecture Does Not Mean a PSP-Agnostic Business

This distinction matters.

Even beautifully abstracted code cannot remove differences in:

• underwriting;
• acquiring;
• tokens;
• 3DS;
• fraud;
• payment methods;
• settlement;
• network relationships;
• local acquiring;
• terminals; and
• commercial terms.

The aim should therefore not be:

“make all PSPs interchangeable.”

They aren't.

The aim is:

“avoid unnecessarily hard-coding one provider into every business process.”

---

Should You Build Multi-PSP Capability While You Are Migrating?

Sometimes.

If the merchant has already done the difficult work of creating a second payment integration, it is reasonable to consider whether both should remain available.

Possible benefits include:

• resilience;
• regional routing;
• payment-method coverage;
• acquiring optimisation;
• commercial leverage; and
• reduced future switching dependence.

But multi-provider architecture also adds:

• routing logic;
• more reconciliation;
• multiple contracts;
• duplicated operational processes;
• testing;
• monitoring;
• reporting complexity; and
• additional engineering ownership.

It should have a commercial or resilience purpose.

Our guide to acquirer-agnostic payment gateways and multi-acquirer architectures looks at this in more detail.

---

When Should the Commercial Decision Happen?

Before the engineering project.

But not too far before it.

There is little value negotiating an attractive PSP rate and signing a long-term agreement before engineering has established whether:

• required APIs exist;
• tokens can migrate;
• recurring flows work;
• payment methods are supported;
• reconciliation is usable;
• the integration effort is acceptable; and
• the migration timeline is realistic.

Likewise, engineering should not spend six months integrating a provider before the business knows whether the commercial arrangement works.

The commercial and technical evaluation should overlap.

---

Find Your New Processor

The Cheapest PSP Can Become the Most Expensive Migration

Imagine two proposals.

Provider A

Expected annual saving:

£180,000

Migration cost:

£450,000

Major token work required.

New reconciliation build.

Provider B

Expected annual saving:

£140,000

Migration cost:

£120,000

Existing token import process.

Simpler finance integration.

The provider with the greater annual saving does not automatically create the stronger business case.

Calculate:

ongoing economics + migration cost + operational impact + payment performance

together.

This is the same principle we use in our high-volume payment strategy work.

---

What Should the Board See Before Approving a PSP Migration?

Not 200 pages of API specifications.

A board-level decision should be able to answer:

Why are we moving?

Cost, performance, functionality, geography, resilience or strategy.

What financial improvement do we expect?

Including reasonable assumptions.

What does migration cost?

Including engineering and operational work.

What is the payback period?

Where the rationale is financial.

What could disrupt revenue?

Critical migration risks.

How will stored customers be handled?

Especially recurring-payment businesses.

Can we run both providers?

And for how long?

What does rollback look like?

What constitutes a successful migration?

What remains with the old provider after cutover?

A project that cannot answer these questions probably isn't ready for final approval.

---

Where Merchant Advice Service Fits Into a Custom PSP Migration

Merchant Advice Service is not a software-development agency.

Our role sits earlier in the decision.

For established merchants, we can help work through:

current payment architecture

commercial requirements

processing volume

provider capabilities

token/migration constraints

international requirements

acquiring structure

multi-provider options

and

the realistic routes available

before a business commits to the wrong payment-provider architecture.

That matters because the most expensive outcome is not necessarily paying an extra few basis points.

It can be spending months integrating a provider that never fully met the requirement.

Where appropriate, MAS can then introduce relevant payment providers for detailed commercial and technical evaluation.

You can read more about How Merchant Advice Service Works and How MAS Researches and Compares Payment Providers.

Sources & Further Reading

Adyen — Import Data From Another Payment Provider
Adyen's current documentation describes staged payment-data migration, dual-PSP processes and the technical/compliance work involved. Adyen payment-data migration documentation

Stripe — Request a Payments Data Import
Stripe's current migration guidance describes parallel operation between old and new processors, customer/payment-method mapping and protecting customer-data updates during migration. Stripe payment-data migration documentation

Stripe — Webhooks
Current technical documentation covering retries, event ordering, duplicate events, asynchronous handling and webhook security. Stripe webhook documentation

---

Related Merchant Advice Service Guidance

• Payments Strategy Library
• High-Volume Merchant Processing
• Changing Payment Gateway: Stored Cards, Tokens and Recurring Payments
• Acquirer-Agnostic Payment Gateways
• How Enterprise Merchants Improve Payment Authorisation Rates
• How High-Turnover Businesses Audit Payment Fees
• Should You Switch From Adyen?
• Worldpay Contract Renewal: Renegotiate or Switch? 

---

Find Your New Processor

Editorial and Commercial Disclosure

Merchant Advice Service is an independent payments information, comparison and provider-matching service.

MAS may receive commission or a referral fee from some payment providers where a business chooses to proceed following an introduction. This does not determine the factual information, technical considerations or provider capabilities included in this guide.

Payment providers referenced within this article are used as examples of current migration processes and technical documentation. Their inclusion does not represent a ranking or recommendation.

Migration capability, token portability, API functionality, webhooks, acquiring compatibility and stored-payment migration processes vary between providers and can change.

Payment migrations can involve technical, PCI DSS, contractual and regulatory considerations specific to the business. Specialist technical, legal or compliance advice should be obtained where appropriate.

Merchant Advice Service does not provide software-development services and does not guarantee the successful technical implementation of a payment-provider migration.

Merchant Advice Service does not make payment-provider underwriting decisions or guarantee merchant-account acceptance.

Provider information last checked: 25 August 2026

This guide provides general payments information and should not be treated as technical, legal, regulatory or financial advice.

---