Payment API Integration
Most businesses choose a payment provider before they design their payment architecture.
That can be backwards.
The discussion often starts with:
Which PSP has the best API?
Which provider supports the payment methods we need?
Which gateway is cheapest?
Those questions matter.
But for an established ecommerce, SaaS, subscription or platform business, there is another question worth answering first:
How much of our business do we want to build directly around one payment provider?
Because a payment API can eventually touch far more than checkout.
Over time it may become connected to:
customer accounts → stored cards → subscriptions → authentication → refunds → fraud → webhooks → finance → reconciliation → reporting
At that point, changing payment provider is no longer simply a procurement exercise.
It becomes a technology migration.
The best time to think about payment-provider portability is therefore before the first provider becomes deeply embedded across the business.
This guide is primarily for established businesses designing or rebuilding a bespoke payment integration, particularly companies expecting significant transaction volume, international expansion, recurring payments or more complex payment requirements.
For the wider enterprise-payment picture, explore the Payments Strategy Library and our High-Volume Merchant Processing guide.
Key Takeaways
A good payment API integration should do more than successfully authorise a card.
Before selecting a PSP, businesses should decide:
- how payment data will be collected;
- whether checkout is hosted, embedded or more deeply customised;
- what PCI DSS scope the chosen implementation creates;
- how customers and payments will be identified internally;
- how stored payment credentials will work;
- whether recurring payments are required;
- how 3D Secure will be handled;
- how asynchronous payment events will be processed;
- how duplicate transactions will be prevented;
- how refunds and partial captures will work;
- how payment status will reach the order system;
- how finance will reconcile settlement;
- whether multiple legal entities are involved;
- what international requirements exist;
- what happens if the PSP becomes unavailable;
- how difficult switching provider would be later; and
- whether the architecture should eventually support more than one PSP.
The important distinction is:
The payment provider's API should connect to your business.
Your business should not unnecessarily become an extension of the payment provider's API.
Find Your New Processor
The Payment API Is Not the Payment Architecture
A payment API is simply one way for your systems and a payment provider to communicate.
Your actual payment architecture is wider.
For example:
Customer
↓
Website / app
↓
Checkout
↓
Internal order system
↓
Payment service
↓
PSP
↓
Acquirer / card network / issuer
And then, after the payment:
PSP
↓
Webhook
↓
Internal payment state
↓
Order / subscription / fulfilment
↓
Finance / reporting / reconciliation
A business can replace the PSP in that diagram.
It becomes much harder when every other layer has been built using provider-specific assumptions.
An API can provide much greater control over the payment experience, but the underlying gateway and provider still need to match the business's functionality, currencies, risk profile and processing requirements. See our Payment Gateways guide for the broader considerations involved in selecting a payment setup.
The First Decision Is Not Which API to Use
It is:
How Much Payment Complexity Do You Actually Want to Own?
There is a spectrum.
At one end, the payment provider can control most of the payment page.
At the other, the business can build a highly customised checkout and directly integrate a large amount of payment logic.
Neither is automatically better.
A more controlled integration may offer:
- greater checkout flexibility;
- more control over UX;
- more sophisticated payment logic;
- deeper product integration; and
- more opportunities to optimise.
But it may also increase:
- technical ownership;
- security responsibilities;
- maintenance;
- PCI DSS considerations; and
- provider dependency.
The right answer depends on what the business actually needs.
A technically strong API does not automatically make a provider commercially suitable for the merchant. Businesses choosing which PSP should sit behind the integration can use our Ecommerce Payment Providers UK guide to compare acquiring, pricing, settlement, risk appetite and wider provider fit.
Hosted Checkout vs Embedded Components vs Direct API
This should be an architecture decision, not merely a design preference.
Hosted Payment Page
The customer is directed to, or pays through, a page provided largely by the PSP.
Potential advantages include:
- faster deployment;
- reduced payment-page development;
- simpler maintenance;
- provider-managed payment UI; and
- potentially reduced PCI DSS scope.
The trade-off can be less control over the checkout journey.
Embedded Payment Components
The payment form appears more naturally within the merchant experience, while sensitive payment elements are supplied by the payment provider.
This can offer a middle ground between:
control
and
outsourcing sensitive card-data handling.
However, implementation detail matters.
The PCI Security Standards Council states that SAQ A eligibility for ecommerce implementations depends on all payment-page elements used to collect and process card data originating from PCI DSS-compliant third-party providers, alongside the other eligibility requirements.
Read the PCI Security Standards Council guidance
That means:
“We use an iframe” does not equal “PCI no longer applies to us.”
More Direct API Integration
A business may want greater control over payment behaviour and UI.
This can be appropriate for sophisticated businesses with:
- bespoke checkout;
- complex subscriptions;
- marketplaces;
- multiple payment methods;
- custom payment routing;
- mobile applications;
- high transaction volume; or
- specialist payment workflows.
But the more payment logic the merchant controls, the more important architecture and security become.
MAS View
Choose the least complex integration that still delivers the business requirement.
Complexity should earn its place.
Find Your New Processor
Don't Let the PSP Become Your Customer Database
This is one of the easiest architectural mistakes to make.
Imagine the PSP creates:
Customer ID: cus_828261
The development team stores that identifier and starts using it throughout the business.
Soon:
subscriptions
refunds
billing
customer support
and
reporting
all depend directly on cus_828261.
That works perfectly while the business uses that provider.
Then the company changes PSP.
The new provider generates:
Customer ID: ABC9271
Now the merchant has a migration problem.
A more portable approach is usually to maintain your own customer identity.
For example:
Internal customer: CUSTOMER-10027
and then map:
CUSTOMER-10027 → PSP A customer ID
or eventually:
CUSTOMER-10027 → PSP A ID + PSP B ID
The same principle applies to:
- orders;
- subscriptions;
- payment methods;
- payments;
- refunds; and
- mandates.
Own the Business State - Not the PSP's Vocabulary
Payment providers describe transactions differently.
One might use:
PaymentIntent
another:
Payment
another:
Transaction
another:
Order
Likewise, one system may expose:
authorised
while another differentiates several separate payment stages.
Your business should know what it means by:
PAYMENT_PENDING
PAYMENT_AUTHORISED
PAYMENT_CAPTURED
PAYMENT_FAILED
PAYMENT_REFUNDED
and then translate provider-specific states into those internal states.
This sounds like a development detail.
Strategically, it matters.
It means your:
- order management;
- fulfilment;
- finance;
- customer service; and
- subscription systems
are connected to your payment model, not permanently to Provider A's terminology.
Payment Status Is Often Asynchronous
One of the biggest mistakes in payment API design is assuming the immediate API response is always the final truth.
It may not be.
Payment methods can involve:
- authentication;
- external redirects;
- bank confirmation;
- delayed processing;
- fraud checks; or
- subsequent status changes.
Adyen's current integration documentation, for example, warns that a payment result returned synchronously can later change and recommends using webhook information when updating order-management systems.
Read Adyen's payment-result guidance
This is why a mature payment integration needs to understand:
request/response
and
asynchronous events
as two different things.
Webhooks Should Be Treated as Core Infrastructure
Webhooks tell your application that something has happened after the original API request.
That might include:
- payment authorised;
- payment captured;
- payment failed;
- refund completed;
- dispute opened;
- token created;
- recurring payment completed; or
- settlement information becoming available.
For established businesses, webhooks should not be treated as:
“a URL that receives payment notifications.”
They are part of the payment architecture.
Stripe's current documentation covers webhook security, event handling and asynchronous payment events in detail.
Read Stripe's webhook documentation
Find Your New Processor
Design Webhooks to Survive Real-World Behaviour
Your webhook infrastructure should expect things to go wrong.
Ask:
What if the event arrives twice?
Payment systems can redeliver events.
The business logic should therefore be capable of recognising that it has already processed the relevant event.
What if business logic fails after receiving the event?
The payment event should not simply disappear.
What if the webhook endpoint is temporarily unavailable?
There needs to be a recovery mechanism.
What if events arrive in an unexpected sequence?
Payment state should still resolve correctly.
What if an attacker sends a fake webhook?
The event should be authenticated before being trusted.
Adyen, for example, recommends HMAC signature verification when securing webhook messages.
Read Adyen's webhook-security guidance
Idempotency Sounds Technical Until a Customer Gets Charged Twice
Imagine this sequence:
- Customer clicks Pay.
- Your application sends the payment request.
- The PSP authorises it.
- Your application loses the network connection before receiving the response.
- Your system assumes the request failed.
- It sends the payment again.
Without appropriate safeguards, the customer could potentially be charged twice.
This is where idempotency becomes important.
Stripe's API, for example, supports idempotency keys so supported requests can be retried without unintentionally performing the same operation twice.
Read Stripe's idempotency documentation
Other enterprise payment APIs also provide mechanisms designed to prevent duplicate request processing.
The business principle is straightforward:
Network uncertainty should not become duplicate customer charges.
MAS View
If you're assessing payment APIs, ask developers:
“What happens if we don't know whether the first request succeeded?”
The answer tells you far more about integration quality than the provider's demo checkout.
Stored Cards Need a Strategy Before You Store the First One
Tokenisation makes repeat payments much easier.
But it creates a long-term architectural decision.
A token might be required for:
- subscriptions;
- memberships;
- one-click checkout;
- card-on-file purchases;
- hotels;
- travel;
- marketplaces;
- SaaS billing;
- no-show payments; or
- other merchant-initiated transactions.
The important questions include:
Who creates the token?
Where is it stored?
What customer reference does it connect to?
Can it be used across multiple merchant accounts?
Can it be used internationally?
Can it move if we change provider?
Is it a PSP token or network token?
What happens when the underlying card expires?
Those questions are much easier to answer during architecture design than during a future PSP migration.
For the migration side of this, see our guide to moving stored cards, payment tokens and recurring payments between payment providers.
The Token Should Not Become the Customer
The same portability rule applies here.
Do not let:
PSP_TOKEN_123456
become the identity of the customer's payment method throughout the business.
Instead, consider something conceptually like:
Internal payment method: PM-10986
mapped to:
Provider A token: TOK-89762
Later, if required:
Provider B token: CARD-78121
Now internal systems can request:
Charge PM-10986
without every application needing to know which PSP generated the current token.
This is the beginning of payment abstraction.
It does not make providers completely interchangeable.
But it reduces unnecessary dependency.
Recurring Payments Need More Than a “Subscription API”
Simply asking:
“Does your API support subscriptions?”
doesn't go far enough.
An established subscription business should ask:
- how the initial payment is authenticated;
- how credentials are stored;
- how subsequent off-session payments work;
- how merchant-initiated transactions are identified;
- what happens when authentication is required later;
- whether Account Updater or network-token functionality is available;
- how failed payments are retried;
- whether billing logic sits with the PSP or the merchant;
- how upgrades and downgrades work; and
- what happens to subscriptions if the PSP changes.
There is a strategic decision here.
Do you want the PSP to own:
subscription billing logic + payment
or primarily:
the payment itself?
The more billing logic is delegated to one PSP, the more complex future migration may become.
For more on the payment requirements themselves, see our Subscription Payment Processing guide.
Should Billing Logic Live With the PSP?
There are good reasons to use provider billing products.
They can reduce development and provide:
- invoicing;
- subscription schedules;
- retries;
- proration;
- dunning;
- tax integrations; and
- customer portals.
For many businesses, that is sensible.
But larger SaaS organisations should understand the dependency created.
If your:
subscription state
pricing rules
invoices
payment retries
and
customer payment credentials
all live primarily in Provider A, changing provider can become a much bigger project.
That does not mean:
Don't use provider billing.
It means:
Know what you're outsourcing.
For software companies, the API is only one part of the decision. Platforms that also want control over branding, merchant onboarding and payment revenue should read our guide to white-label payment processing.
3D Secure Is Part of the Product Journey
3D Secure is often treated as something the PSP “handles”.
Technically, that may largely be true.
Commercially, authentication affects:
- checkout friction;
- payment success;
- fraud;
- exemptions;
- soft declines; and
- conversion.
An API evaluation should therefore consider:
- browser flows;
- app flows;
- challenge handling;
- redirects;
- exemptions;
- soft declines;
- recurring payments;
- payment retries; and
- what data can be analysed afterwards.
The question isn't simply:
“Do you support 3DS?”
Most enterprise payment providers do.
The more useful question is:
“How will authentication behave in our actual customer journeys?”
Find Your New Processor
Refunds Should Be Designed at the Same Time as Payments
A surprising number of payment projects focus heavily on:
take payment
and treat:
refund payment
as a later feature.
For a mature business, refunds may involve:
- full refund;
- partial refund;
- several partial refunds;
- cancellation before capture;
- refund after partial capture;
- refund to original payment method;
- customer-service permissions;
- asynchronous completion;
- reconciliation; and
- reporting.
Your internal systems should understand which transaction is being refunded and why.
If the business later adds a second PSP, it also needs to know:
which provider owns the original payment.
Hospitality and Travel May Need Authorisation and Capture Separately
Not every business wants:
authorise → capture immediately.
Hotels, travel businesses, rentals and certain marketplace models may need:
authorise now → capture later
or:
authorise amount → adjust or capture an eligible amount later.
That means the API needs to support the payment lifecycle appropriate to the business.
Before provider selection, establish whether you need:
- immediate capture;
- delayed capture;
- partial capture;
- multiple captures where supported;
- cancellation;
- incremental authorisation; or
- pre-authorisation.
This is exactly why sector-specific payment design matters.
For hotel groups, see our Hotel Group Payment Strategy guide.
For booking platforms, see our Payment Providers for Booking Systems guide.
Reconciliation Is Part of the API Requirement
Finance is often brought into API projects far too late.
The developers prove:
payment works.
Then finance asks:
How do I match this to the bank deposit?
An enterprise payment integration should establish upfront:
- settlement reports;
- payout identifiers;
- payment references;
- fee reporting;
- gross versus net settlement;
- refunds;
- chargebacks;
- multiple currencies;
- merchant-account identifiers;
- legal entities; and
- how these data points enter finance systems.
For a high-volume merchant, a technically elegant checkout that creates manual finance work is not a good payment integration.
Design the Transaction Reference Before Finance Needs It
A simple example:
Your order system contains:
ORDER-92816
The PSP contains:
TXN-7887239
Your bank settlement contains:
SETTLEMENT-826
Your finance system contains:
INV-728261
Can finance trace:
ORDER-92816 → TXN-7887239 → SETTLEMENT-826
without manually searching three systems?
If not, payment architecture and reconciliation architecture are disconnected.
That becomes much more painful at scale.
Multiple Legal Entities Should Be Designed Early
This becomes particularly important for businesses expanding internationally.
A group might have:
UK Ltd
France SAS
Germany GmbH
US Inc
Each may need:
- its own merchant account;
- local acquiring;
- local settlement;
- different currencies;
- separate reporting; and
- different payment methods.
If the integration assumes:
one PSP account → one merchant → one bank account
international growth can require substantial rework.
Instead, the architecture should understand concepts such as:
business entity
merchant account
country
acquiring region
settlement currency
from the beginning where future expansion is realistic.
Don't Choose an API Based Only on Developer Experience
Developer experience matters.
Clear documentation, good SDKs and a useful sandbox can materially reduce implementation cost.
But a beautifully documented API cannot compensate for a payment provider that does not meet the underlying commercial requirement.
The API review should happen alongside questions about:
- acquiring;
- pricing;
- authorisation;
- international coverage;
- merchant sectors;
- local payment methods;
- settlement;
- underwriting;
- platform structure; and
- future commercial strategy.
This is especially important for established businesses where payments already represent significant revenue.
For a broader view of provider selection at scale, read our High-Volume Merchant Processing guide.
Find Your New Processor
A Better Payment API Evaluation Scorecard
Instead of simply scoring:
documentation / ease of integration / cost
consider:
| Area | Question |
|---|
| Checkout |
Can we build the customer experience we require? |
| Security |
What card data touches our systems? |
| PCI |
What validation scope does the implementation create? |
| Payment state |
Can we model asynchronous transactions safely? |
| Webhooks |
Are events secure and manageable? |
| Idempotency |
Can uncertain requests be retried safely? |
| Tokens |
What do we own and what is portable? |
| Recurring |
Can our billing model work properly? |
| 3DS |
How will authentication affect real customer journeys? |
| Refunds |
Are post-payment operations complete? |
| Reconciliation |
Can finance trace payment to settlement? |
| Entities |
Can the architecture support our corporate structure? |
| Geography |
Can it support future markets and local acquiring? |
| Portability |
What happens if we change PSP? |
| Resilience |
What happens when the provider is unavailable? |
| Multi-PSP |
Could another provider be added later if required? |
That is a far more useful enterprise procurement document.
Should You Build a Payment Abstraction Layer?
Not every merchant should.
For a relatively straightforward business using one provider with no intention of changing, building an internal payment layer can create unnecessary complexity.
But it may warrant consideration where:
- payment volume is substantial;
- several products use payments;
- multiple countries are involved;
- more than one PSP may eventually be needed;
- the business has complex recurring payments;
- payments are strategically important;
- provider-switching risk matters; or
- several engineering teams need a common payment service.
The basic idea is:
Business systems
↓
Internal payment service
↓
Provider-specific adapter
↓
PSP
The internal payment service understands concepts such as:
authorise
capture
refund
store payment method
while the adapter translates those instructions into the API language of the current provider.
Payment Abstraction Does Not Make PSPs Identical
This is important.
Provider A and Provider B may differ materially in:
- acquiring;
- tokenisation;
- fraud;
- local payment methods;
- authentication;
- settlement;
- APIs;
- card-network relationships;
- recurring-payment logic; and
- underwriting.
You cannot abstract away every difference.
Nor should you.
The objective is to separate:
business logic that belongs to your organisation
from:
implementation logic that belongs to the PSP.
Should You Integrate More Than One PSP From Day One?
Usually not without a clear reason.
Every extra PSP adds:
- development;
- testing;
- routing;
- monitoring;
- reporting;
- reconciliation;
- support; and
- commercial management.
However, enterprises may have legitimate reasons to design for multiple providers, including:
- resilience;
- local acquiring;
- international expansion;
- payment-method coverage;
- optimisation;
- negotiating leverage; or
- specialist requirements.
The useful design principle is not necessarily:
Build two PSPs now.
It may simply be:
Do not make adding PSP two unnecessarily difficult later.
For businesses considering that route, see our Acquirer-Agnostic Payment Gateways guide.
What Happens If the PSP Is Down?
This is a board-level payment question disguised as an engineering question.
If the provider becomes unavailable:
Can checkout continue?
Can payment requests queue?
Can transactions be routed elsewhere?
Can customers retry safely?
Will duplicate payments be created?
What happens to asynchronous events?
How does customer service know payment status?
For some merchants, several minutes of payment downtime is tolerable.
For others, it could represent substantial lost revenue.
The resilience requirement should reflect the business.
Your Sandbox Test Is Not a Production Test
Payment-provider sandboxes are useful.
They do not reproduce every production condition.
A serious launch plan should test more than:
payment succeeded
and
payment declined.
Use scenarios such as:
- timeout after request;
- duplicate request;
- authentication required;
- authentication abandoned;
- soft decline;
- webhook delayed;
- webhook duplicated;
- webhook invalid;
- refund;
- partial refund;
- delayed capture;
- customer closes browser;
- provider error;
- recurring payment;
- expired payment method;
- international card;
- alternative payment method;
- reconciliation.
Versioning and Provider Change Need Ownership
Payment APIs evolve.
SDKs change.
Authentication mechanisms change.
Features get deprecated.
Someone within the business needs to own:
- API versions;
- SDK versions;
- release notes;
- certificate or credential expiry;
- webhook changes;
- deprecated endpoints;
- testing;
- provider notices; and
- production monitoring.
A payment integration is not:
build once → finished.
It is infrastructure.
The Best API May Not Be the Best Payment Provider
This is probably the most important procurement point.
A CTO may favour Provider A because the API is excellent.
Finance may favour Provider B because its commercial proposal is cheaper.
Payments may favour Provider C because acquiring performance is stronger.
Operations may need Provider D because of a particular integration.
The correct decision sits between them.
For an established merchant, the payment-provider review should consider:
commercial fit
technical fit
payment performance
operational fit
and
future architecture
together.
The provider should not win simply because:
the developers liked the documentation.
And it should not win simply because:
procurement got the lowest rate.
Remember, integrated payments do not always require a bespoke API build. Depending on the software and provider, businesses may also use pre-built connectors, plugins, middleware or supported platform integrations.
For the wider merchant strategy, including EPOS, ERP, CRM and other business systems, see our Integrated Payments Solutions UK guide.
The MAS Future-Switch Test
Before signing with a payment provider, ask:
If we changed this provider in three years…
Would we need to replace:
checkout?
tokens?
subscriptions?
customer IDs?
billing?
webhooks?
fraud?
finance reporting?
terminals?
acquiring?
all of the above?
Then ask:
Do we need all of those dependencies?
Some will be unavoidable.
Others may simply be consequences of implementation choices.
MAS View
The aim is not to eliminate payment-provider dependency.
That is unrealistic.
The aim is to understand it and avoid creating more dependency than the business actually requires.
If you already have a bespoke payment integration and are now considering moving provider, our separate guide to changing PSP with an existing payment integration looks at token migration, parallel running, webhooks, testing and controlled cutover in more detail.
How Merchant Advice Service Approaches Complex API Requirements
Merchant Advice Service does not design or build payment APIs.
Our role is helping businesses establish the payment requirement before provider selection.
For established merchants, that can include understanding:
- processing volume;
- existing or proposed architecture;
- checkout requirements;
- recurring payments;
- tokens;
- international expansion;
- local acquiring;
- multiple entities;
- payment methods;
- split payments;
- existing software;
- future migration requirements;
- commercial structure; and
- whether provider flexibility matters.
Only once those requirements are clear does comparing payment providers become genuinely useful.
Where appropriate, MAS can introduce providers whose technical and commercial capabilities warrant further evaluation.
You can also read How Merchant Advice Service Works and How MAS Researches and Compares Payment Providers.
