Payment APIs: complete guide to integration & best practices

If you’ve ever tried to add a new provider, launch in a new country, or fix failing payments under pressure, you already know: payments are never ‘just an integration’. Payment APIs, and the way you structure them, can either lock you into one provider or give you the freedom to route, optimise, and scale.

This article gives you a practical tour of payment APIs: what they are, how they work, and how to roll them out in a way that stays flexible over time.

What is a payment API?

A payment API is an interface that allows businesses to connect their applications to payment processing networks and services. It serves as a bridge between your app or website and external payment services such as gateways, processors, banks, and digital wallets.

Instead of building integrations with card networks, acquirers, and banks yourself (plus maintaining compliance and uptime), you lean on payment providers who expose all of that through APIs you can call in a few lines of code.

How payment APIs work: a step-by-step view

Let’s walk through what typically happens during a card transaction:

1. Customer submits payment. They hit ‘Pay’ on your checkout. On the front end, you collect their card or wallet details — usually through secure fields hosted by the payment provider, so raw card data never touches your servers.
2. Data is tokenised and sent to the API. The provider converts card details into a token. Your backend calls the payment API with that token, the amount, currency, and other metadata (order ID, customer ID, etc.).
3. Gateway sends the request to the card network. The payment gateway sends the request to the acquirer/processor, which passes it to the card scheme (Visa, Mastercard, etc.), and then on to the cardholder’s issuing bank.
4. Bank checks and approves/declines. The issuer checks the balance/credit, runs fraud checks, and either approves or declines. In regions where Strong Customer Authentication (SCA) is mandated (for example, under PSD2 in Europe), the customer may be required to complete 3D Secure or another SCA step.
5. Authorisation response comes back. The result flows back via the same chain to your payment provider, which then returns a response to your system: approved, declined, error, etc. Your app updates the order state accordingly.
6. Capture and settlement. In immediate capture, authorisation and capture are one step. In two-step flows, you authorise first and capture later. Captured transactions are then settled in batches, and funds appear in your merchant account on a schedule.
7. Post-payment events. Refunds, chargebacks, payouts, recurring charges, and subscription renewals are all triggered and tracked through additional API calls and webhooks.

All of this typically happens in seconds from the user’s perspective. Under the hood, the API orchestrates many moving parts.

The main types of payment APIs

API types can be viewed from different angles — interface style, integration pattern, or underlying rails. In this article, we describe them through the most practical lens: how the integration is implemented in real payment stacks.

REST API

REST (Representational State Transfer) is the most common merchant-facing API type in modern payment systems. It is HTTP-based, typically uses JSON, and follows a resource-oriented model.

REST APIs are widely used to create and manage payments, handle captures, refunds, and reversals, manage payouts and balances, and access transaction and settlement data.

SOAP/XML API

SOAP (Simple Object Access Protocol) is an older, more rigid API standard widely used in banking and legacy payment systems.

While less popular for new merchant integrations, SOAP is still commonly used for bank integrations, card network and processor connections, and regulated financial environments where strict, contract-based integrations are required.

Importantly, SOAP does not represent different payment logic. It often exposes the same functionality as REST, just through a more formalised interface.

H2H / ISO 8583

H2H (host-to-host) integrations using ISO 8583 operate at a much lower level of the payment stack. This is not a web API, but a financial messaging protocol used for card authorisations, reversals, clearing and settlement, as well as ATM and POS transactions.

ISO 8583 is the global backbone of card payments, even though it is usually hidden behind higher-level APIs and gateways.

SDK APIs (JS/mobile)

SDKs are developer-friendly wrappers around backend payment APIs with strict scope limitations. They act as abstraction layers that collect sensitive payment data, perform client-side validation and encryption, tokenise payment methods, and simplify frontend and mobile integration.

SDKs rely on backend APIs underneath and exist to improve security, UX, and developer experience — not to introduce new payment flows.

Webhook API

Webhooks are event-driven callbacks designed for asynchronous communication. Instead of requesting data, the payment platform pushes notifications when something happens, such as a payment succeeding or failing, a refund being completed, a chargeback being created, or a payout being processed.

Webhooks are essential for building reliable payment logic because many payment events are asynchronous, delayed, or initiated by external actors (issuers, schemes, banks).

GraphQL API

GraphQL is an alternative API paradigm focused on flexible data access. In payments, it’s most commonly used for dashboards and reporting, analytics and monitoring tools, and internal admin interfaces.

GraphQL rarely handles payment execution itself. Instead, it provides efficient access to complex payment data models.

Ready to start your success story?

See our platform in action, share your challenges, and find a solution you’ve been looking for.

Get started

Payment API integration options

Different integration styles exist for a reason. Which one you choose depends on your team, timelines, and the strategic role of payments in your business.

Direct server-to-server API integration

In a direct server-to-server setup, the merchant’s backend communicates directly with the payment provider’s API over secure channels, typically using REST or SOAP.

How it works: your backend creates and manages payment requests. The payment state is tracked via API responses and webhooks. Key logic — like routing, retries, and reconciliation — is handled server-side.

This model is preferred by larger merchants, platforms, and PSP-like businesses that need bespoke checkout experiences or advanced flows such as subscriptions, split payments, or marketplace settlements.

A direct server-to-server API integration gives you the most flexibility, security and control — but it’s also the heaviest lift. You get full extensibility, yet you’re signing up for more build and maintenance work, plus owning the security and compliance side.

Vadym Berezdetskyi

Head of Engineering at Corefy

Client-side SDKs combined with backend APIs

This model splits responsibilities between the client and the server. SDKs handle sensitive data collection and UX, while the backend API manages payment creation, confirmation, and business logic.

How it works: card or wallet details are collected via the SDK, tokenised on the client side, then sent to your backend. The backend uses the token to complete the payment via API.

This approach is common in e-commerce and mobile apps. It reduces PCI scope, accelerates frontend development, and still gives you backend control over payment flows, order logic, and post-payment actions.

Hosted checkout (redirect or iframe)

Hosted checkout moves the sensitive parts of the flow to a provider-managed payment page, either through a redirect or an embedded experience such as an iframe.

How it works: you create a checkout session via API. The customer completes payment on the provider’s side. You receive the result via return URL and webhooks.

Teams often choose hosted checkout when speed and compliance simplicity are priorities — such as for MVPs or early-stage products. It offers the fastest go-live path and lowest implementation overhead. The trade-off is reduced flexibility: the checkout flow and experience depend on the provider’s design and availability.

Unified orchestration API

A unified orchestration API creates a single point of integration across multiple payment providers, removing the need to build and maintain separate connections.

How it works: the merchant sends transactions to a single API, while routing, failover, retries, and optimisation rules are managed centrally across providers.

This setup is ideal for businesses using multiple PSPs, expanding globally, or focused on optimising approval rates and uptime. It reduces operational complexity at scale, streamlines provider onboarding, and centralises control over routing and payment logic.

Core components of payment APIs

The end-to-end payment experience is built from a set of standard building blocks working together. Let’s walk through the core parts you’ll find in most modern payment APIs.

1. Authentication & security

Before a payment system lets you move money, it needs to verify your identity. This happens through:

• API keys or OAuth tokens to verify your app or server
• Signed requests / JWTs to prevent tampering
• Extra safeguards like IP allowlists or mTLS in higher-risk setups

Why it matters: payments handle sensitive data and real funds. Strong authentication keeps fraudsters out and protects merchants and customers.

2. Payment intent or charge

This is the main ‘start a payment’ endpoint. Most modern APIs use a payment intent model: you first create an intent, then move it through a series of steps until the payment either succeeds or definitively fails.

A typical payment creation request includes the amount and currency, payment method type, customer or order reference, and capture settings — for example, whether the payment should be captured immediately or authorised now and captured later.

Why it matters: this component defines your checkout flow and how flexible you can be with things like authorisation, delayed capture, or retries.

3. Payment methods

A payment API needs a safe way to collect, store, and reuse payment instruments. That typically includes cards, digital wallets, bank rails (SEPA, ACH, local transfers), alternative payment methods, and crypto rails.

Most providers solve this by tokenising sensitive details (such as card numbers): they replace sensitive details with secure tokens that your system can use for future charges, refunds, or subscriptions. This keeps raw data off your servers, reduces your PCI scope, and meaningfully improves your overall security posture.

Why it matters: flexible payment method support expands where you can sell and who can pay.

4. Customer/payer objects

Instead of treating every transaction as a one-off, mature APIs let you create customer profiles.

A customer object usually stores:

• Identity basics (name, email, country)
• Linked payment methods
• Transaction history
• Metadata (your internal IDs, VIP tags, etc.)

Why it matters: customers enable subscriptions, one-click checkout, smarter retries, and cleaner reporting.

5. User actions & 3DS/SCA handling

Many payments can’t be completed without extra customer steps, especially in regulated regions. Payment APIs support 3D Secure for cards, Strong Customer Authentication (SCA) in Europe, redirects or in-app challenges.

That’s why payments often move into a status like ‘requires_action’, and your app needs to send the user through verification before confirming the final result.

Why it matters: good handling of these flows is critical for conversion and compliance.

6. Refunds, voids & reversals

Things change: people cancel orders, returns happen, mistakes get made. Payment APIs include endpoints for:

• Void / cancel (before settlement)
• Refund (after capture)
• Partial refunds
• Reversals on some bank rails

Why it matters: refunds are part of customer trust. If your API makes them hard, support costs climb and UX suffers.

7. Payouts

If your product pays money to sellers, partners, or users, payouts become a core module. Payout APIs manage:

• Destination accounts (bank, wallet, etc.)
• Payout creation and tracking
• Batching and fees
• Balance checks

Why it matters: payouts are essential for marketplaces, platforms, and PSPs — and they need the same reliability as collections.

8. Webhooks & event notifications

Payments don’t always finish instantly. Banks, issuers, and APMs can respond seconds or even hours later. Webhooks notify your system about key events like:

• Payment success or failure
• Refund completed
• Chargeback opened
• Payout delivered or rejected

Why it matters: without webhooks, your system would constantly ‘poll’ for updates and still risk missing outcomes.

9. Status queries & reporting

A payment platform isn’t complete unless you can retrieve what happened. This includes:

• Fetching a payment by ID
• Checking current and past statuses
• Settlement and fee breakdowns
• Balances and ledger exports

Why it matters: clear reporting supports efficient dispute handling and optimisation.

10. Idempotency & safe retries

Networks fail, requests time out, and users often refresh pages. That’s why payment APIs use idempotency keys — a simple way to guarantee that if you retry the same request, you don’t create duplicate charges.

Why it matters: it protects both your revenue and your users from accidental double payments.

11. Routing & provider abstraction

In more advanced setups — especially when multiple PSPs are involved — payment APIs often include a routing layer. Routing can:

• Choose a provider based on rules (geo, currency, cost, success rate)
• Trigger fallback/cascading if a provider fails
• Split traffic for A/B testing

Why it matters: routing boosts resilience and can raise approval rates without changing the customer experience.

12. Risk & compliance hooks

Finally, most payment APIs include fraud and compliance touchpoints such as:

• Risk checks
• Velocity limits
• Black/white lists
• KYB/KYC statuses for regulated flows

Why it matters: risk tooling protects approval rates and reduces losses without blocking good customers.

Best practices for payment API implementation

Choosing a payment API is only half the job. How you implement it has a huge impact on your approval rates, user experience, and how much pain (or peace) your teams live with day to day. Below are the best practices that blend architecture, security, and operations.

Design for abstraction

Even if you start with a single provider, design as if you’ll add more later.

• Normalise key objects: define your own internal models for payments, refunds, customers, subscriptions, etc. Map provider-specific responses to these models.
• Separate configuration from code: keep API keys, routing rules, and supported payment methods in configuration, not hard-coded.

This gives you flexibility to change providers, add new acquirers, or plug in a payment orchestrator without rewriting your entire stack.

Prioritise security and compliance

A few non-negotiables:

• Don’t handle raw card data if you don’t have to. Use hosted fields, tokenisation, and PCI-compliant SDKs from your provider.
• Rotate keys and credentials. Store API keys in a secret manager, enforce rotation, and use separate keys per environment.
• Use strong authentication. Enforce HTTPS everywhere, enable mTLS or IP whitelisting where available, and follow least-privilege for internal access.
• Align with standards. Use the provider’s tools for PCI DSS, PSD2 SCA, and local regulatory requirements instead of rolling your own logic.

Build for reliability and graceful failure

Payment flows will fail sometimes — banks time out, issuers go down, 3DS pages misbehave. Design for that reality.

• Idempotency everywhere. Use idempotency keys for payment creation, refunds, and payouts so retries don’t create duplicates.
• Retry with care. Implement exponential backoff for network errors, but don’t retry blindly on declines or customer errors.
• Fallback scenarios. Show clear, actionable messages when payments fail and offer alternative methods instead of a generic “error occurred.”
• Monitor upstream incidents. Subscribe to your providers’ status pages and integrate them into your alerting.

Invest in observability and analytics

• Log the full payment journey. From ‘Pay’ click to final status: attempts, 3DS steps, redirects, callbacks, and webhooks.
• Capture metadata. Store order IDs, customer IDs, checkout variant, device, and payment method. These fields are gold for debugging and optimisation.
• Track key metrics. Authorisation rate, 3DS success, decline reasons, chargeback rate, and time to settle.
• Keep dashboards close to the teams. Product, risk, and finance should have views tailored to their needs.

This is what allows you to spot issues like a sudden spike in ‘do not honour’ declines or a broken redirect flow.

Design robust webhook handling

For many payment APIs, webhooks are where the “truth” of the transaction arrives.

• Verify signatures. Never trust a webhook payload without validating its authenticity.
• Make handlers idempotent. Webhooks can be delivered more than once; your logic should handle duplicates safely.
• Fail fast but retry-friendly. Return appropriate HTTP codes so the provider can retry on transient failures.
• Decouple heavy work. Use queues or background jobs to process notifications (e.g., invoicing, emails) instead of doing everything in the webhook handler.

Solid webhook handling keeps your system in sync with the actual state of payments and disputes.

Optimise the customer experience

The best integration from a developer’s point of view can still be a poor checkout for customers.

• Minimise friction. Only ask for the necessary fields. Lean on wallets and saved payment methods where possible.
• Respect local expectations. Show relevant local payment methods, currencies, and languages based on location or preferences.
• Design for mobile first. Many payments happen on small screens. Test 3DS, redirects, and modals on real devices.
• Avoid ‘dead ends.’ Always provide a clear path to try again, choose another method, or contact support.

Plan for lifecycle events

Taking money is only part of the story; you need a clean process for everything that happens after.

• Standardise refunds. Decide where refunds are initiated (support tools, admin panel, ERP) and integrate those systems with your payment API.
• Sync chargebacks and disputes. Use webhooks or scheduled jobs to keep your internal records aligned with provider dispute statuses.
• Reconcile automatically. Build or use tools to match transactions, payouts, and fees across your payment API, bank statements, and accounting systems.

Well-implemented lifecycle flows reduce manual work and finance headaches.

Start small, then iterate and expand

Trying to launch every payment method, provider, and country at once is a recipe for delays and complexity.

• Phase 1: Core countries, 1–2 payment methods, simple flows.
• Phase 2: Add local methods, improve routing, and refine 3DS and risk rules.
• Phase 3: Optimise conversion, experiment with multiple acquirers, and automate more of the back office.

Each phase should include a feedback loop from data, users, and internal teams.

How payment orchestration simplifies implementation

If your payment setup is simple and you only work with one provider, integrating their payment API is usually straightforward. But as you grow, expand into new markets, and add more PSPs, things get messy fast — you’re suddenly dealing with different APIs, auth schemes, webhook formats, and error codes.

That’s where payment orchestration really pays off. It gives you a single, unified layer to connect all providers, so you integrate once and manage everything centrally instead of rebuilding the same logic for each PSP.

A good orchestration platform standardises authentication, request and response structures, webhook behaviour, error codes, and payment lifecycle events. This can cut integration timelines from months to weeks (or even days) and removes much of the pain of handling fragmented, provider-specific logic.