Payment Gateway API (Payments / Card Payment API) Explained

What Is a Payment Gateway API?

A payment gateway API is the set of HTTP endpoints your code calls to authorise a card transaction, capture funds, refund a customer, or store a card on file. Strip away the marketing wrapper around any modern payment platform and there's an API at the bottom of it: a POST /charges, a webhook for status updates, an authentication header carrying your secret key.

The reason businesses integrate at the API layer rather than redirecting to a hosted payment page is control. With an API integration you decide what the customer sees, when 3D Secure prompts appear, how errors are handled, and how the payment record flows into your CRM, billing system, or call-centre desktop. The trade-off is PCI scope: how the API is designed -- and where card details enter the request -- determines whether your servers stay out of scope (tokens, hosted fields) or get pulled in (raw card data passing through your application).

Every gateway you've heard of -- Stripe, Adyen, Worldpay, Braintree, a major UK payment provider, Mollie -- ships an API. The marketing pages talk about checkout buttons and one-tap payments, but underneath, every transaction your business takes runs through HTTP requests against documented endpoints. Understanding the API is how you understand the gateway.

How a Payment Gateway API Works

At a technical level, a payment gateway API works through a series of requests and responses between the merchant's system and the gateway provider's servers.

The Basic Transaction Flow

When a customer is ready to pay, the merchant's application sends a request to the payment gateway API containing the transaction details: the amount, the currency, the customer's card details (or a token representing stored card details), and any additional information required for fraud screening or authentication. The gateway receives this request, validates it, and forwards it to the relevant card network and issuing bank for authorisation.

Within seconds, the gateway receives a response -- approved, declined, or requiring additional authentication (such as 3D Secure). It passes this response back to the merchant's application, which can then display the appropriate result to the customer.

What a Real Request Looks Like

A typical authorisation request is a JSON POST against an HTTPS endpoint. It carries an amount in the smallest currency unit (pence, not pounds), a currency code, a payment method reference (either a tokenised card or a one-time payment method ID created client-side), an idempotency key, and a customer reference. The response carries a transaction ID, a status (succeeded, requires_action, failed), a decline code if relevant, and -- if 3D Secure was triggered -- a URL or client-side action your front-end needs to handle before re-submitting.

The body is small. Most of the complexity sits in handling the response paths properly: a successful auth needs storing, a 3DS challenge needs surfacing to the customer, a soft decline needs a retry policy, a hard decline needs a clean error message and an alternative payment option offered. The gateway gives you the building blocks; your application decides what to do with them.

Key API Functions

A payment gateway API typically provides endpoints for several core functions:

• Authorisation -- checking that the card is valid and the funds are available, and placing a hold on the amount
• Capture -- confirming the transaction and initiating the transfer of funds from the customer's account to the merchant's account
• Sale -- combining authorisation and capture into a single step for immediate payment
• Refund -- returning all or part of a payment to the customer
• Void -- cancelling an authorised transaction before it has been captured
• Tokenisation -- converting card details into a token for secure storage and future use
• Query -- checking the status of a transaction
• Mandate creation -- registering a customer's authorisation for future recurring or merchant-initiated transactions
• Dispute and chargeback endpoints -- reading dispute notices and uploading evidence
• Settlement and reconciliation -- pulling the daily payout file showing which transactions cleared and when funds land in your bank account

Authentication and Security

API requests are authenticated using API keys, tokens, or other credentials that identify the merchant and confirm they are authorised to use the gateway. All communication between the merchant's system and the gateway is encrypted using TLS. The gateway provider handles PCI DSS compliance for the transaction processing, but the merchant needs to ensure that their own systems are secure, particularly if they are handling card data before sending it to the gateway.

Most modern gateways now issue two kinds of credentials: a publishable key safe to embed in browser-side JavaScript (used to create one-time payment method IDs without sending raw card details to your server), and a secret key your back-end uses to confirm and capture payments. Treat the secret key like a password to your merchant account, because that's effectively what it is. Rotate it if a developer leaves. Store it in your secret manager, never in source control. Scope it down to the permissions you actually need if your gateway supports restricted keys.

Webhooks and Notifications

Most payment gateway APIs support webhooks -- automated notifications sent from the gateway to the merchant's system when something happens. For example, the gateway can notify the merchant when a payment is confirmed, when a refund is processed, or when a chargeback is filed. Webhooks allow the merchant's system to react to events in real time without constantly polling the gateway for updates.

Webhooks are where naive integrations break. The API call to take a payment is the easy bit. What's harder is correctly handling the asynchronous events that follow: a payment that succeeded synchronously but later got reversed by the issuer, a 3DS challenge that completed in a different browser tab, a subscription renewal that failed three days after you scheduled it. Your webhook handler needs to verify the signature on every incoming event, look up the related transaction in your database, decide whether the event is new or a duplicate, and update state accordingly. If it doesn't, your data will drift from the gateway's data, and you'll find out about it from an angry customer.

PCI DSS Scope and API Integrations

How you wire your application to the API decides which PCI DSS Self-Assessment Questionnaire applies to you, and roughly how much money and time your annual compliance cycle eats.

SAQ A: Card Data Never Touches Your Servers

If you use the gateway's client-side tokenisation -- a JavaScript library that captures the card directly in the customer's browser and returns you a one-time token -- the raw PAN, expiry, and CVV never reach your application. Your server only sees the token. You're typically eligible for SAQ A, the shortest questionnaire, with the lightest set of controls. This is the right architecture for most online merchants.

SAQ A-EP: Your Page, Their Iframe

If you host the checkout page but embed the gateway's iframe or hosted field for the card inputs, you fall under SAQ A-EP. The card data still doesn't reach your servers, but you're responsible for the page that contains the field -- and any script that runs on it could potentially intercept the card. PCI DSS v4.0.1 added explicit requirements (6.4.3 and 11.6.1) for inventorying and integrity-checking the scripts on payment pages. Plan for those.

SAQ D: Card Data Hits Your Servers

If your code ever sees the raw PAN -- because you're collecting card data via a form your server renders and then forwarding it to the gateway over the API -- you're in SAQ D territory. That's the long form, with hundreds of controls, network segmentation requirements, quarterly ASV scans, and a much bigger compliance bill. There are legitimate reasons to be in SAQ D (some agent-assisted workflows, some legacy integrations), but for most businesses, the right move is to redesign the integration so the gateway captures the card directly.

The Telephone Channel Wrinkle

Card details captured by phone agents are an edge case that catches many businesses out. If the agent hears the digits and types them into a virtual terminal, the agent's desktop, the call recording, and your phone system are all in PCI scope. Pause-and-resume call recording mitigates the recording problem but doesn't help the agent's screen. DTMF masking sidesteps the whole issue by having the customer key digits on their phone keypad while the tones are intercepted before they reach the agent or the recording -- the gateway API call goes out from a PCI-scoped service, not from the agent's desktop. The reduction in scope is usually the whole reason businesses adopt it.

Why Payment Gateway APIs Matter for Businesses

Full Control Over the Payment Experience

With an API integration, the business controls every aspect of the payment experience -- the design, the flow, the error messages, and the confirmations. This allows them to create a smooth, branded checkout process that matches the rest of their application. There are no redirects to external pages, no jarring transitions, and no limitations imposed by a hosted payment form.

Flexibility and Customisation

APIs are building blocks. They can be combined and configured to support virtually any payment workflow. A business might use the API to build a subscription billing engine, a marketplace payment system, an instalment plan, or a custom invoicing solution. The gateway handles the payment processing, and the business logic sits in the merchant's own application.

Automation

APIs enable payment automation. Recurring charges can be triggered by the merchant's billing system. Refunds can be processed automatically based on return policies. Payment status updates can flow into accounting systems, CRMs, and customer communication platforms without manual intervention. This reduces errors, saves time, and scales efficiently as transaction volumes grow.

Multi-Channel Support

A single payment gateway API can power payments across multiple channels -- a website, a mobile app, an in-store terminal, and a telephone payment system. This gives the business a unified view of all transactions and simplifies reconciliation, reporting, and customer service.

Real-World Examples

A UK Energy Supplier Handling Payment Calls

An energy supplier with about 300 contact-centre agents takes a steady volume of phone payments -- top-ups for prepayment customers, settlement of bills for vulnerable customers who don't bank online, payment plans negotiated with customers in arrears. The team used to read card numbers to agents who typed them into a virtual terminal that called the gateway's authorise endpoint directly. Every agent desktop and the entire call-recording archive were in PCI scope.

The redesign kept the same gateway and the same API. What changed was the layer in front of it. Agents now stay on the line and the customer enters card digits on their phone keypad. The digits never reach the agent's screen or the call recording. A PCI-scoped intermediary service receives the keypad input, builds the authorise request, and calls the same gateway endpoint the virtual terminal used to call. The gateway response is mapped back to the agent's CRM screen as a clean "Paid" or "Declined" status. Agents kept the same workflow; the supplier dropped from SAQ D to SAQ A-EP.

A B2B SaaS Running Card-Not-Present Subscriptions

A subscription billing system charges customers automatically every month. The first charge runs interactively -- the customer enters card details on the signup page, the browser tokenises them via the gateway's JavaScript library, and the server calls the API with the resulting token plus a flag saying "save this for future use." The gateway returns a customer ID and a payment-method ID, which the application stores.

Renewals run server-side. A cron job iterates yesterday's expiring subscriptions, calls the gateway's POST /payment_intents with the stored payment-method ID, and listens on the webhook channel for the result. Most clear immediately. A few trigger soft declines and get retried 24 hours later. A few hit hard declines and trigger a dunning email asking the customer to update their card. The whole renewal pipeline runs without any human touching it -- and because the raw card never reached the application server even on the first charge, the company stays in SAQ A scope.

An Online Retailer Handling Authorise-Then-Capture

A clothing retailer authorises the card the moment the customer places the order but only captures funds when the warehouse confirms the items have shipped. Two API calls, separated by potentially several hours: an authorise that places a hold, and a capture that triggers the actual movement of money. If the warehouse can't fulfil, the retailer calls void or partial-capture instead. This pattern is invisible to the customer but means the business never charges for items they can't ship -- a small change that materially reduces refund volume and chargeback risk.

Common Failure Modes

Webhook Replay and Idempotency

Gateways retry webhooks when your endpoint returns a non-2xx response or times out. If your handler isn't idempotent, you'll double-credit refunds, double-fulfil orders, or send duplicate emails. Every webhook handler needs to track event IDs and skip ones it's already processed. Treat webhooks as "at least once" delivery and design accordingly.

Timeouts on the Authorise Call

A timeout doesn't mean the transaction failed. It means you don't know what happened. The customer's card might have been charged. The right response is to query the gateway with the idempotency key from your original request -- if the gateway received and processed the request, the query returns the same transaction. If you instead retry blindly, you risk double-charging.

3D Secure Without a Plan

3D Secure 2 challenges have to be rendered to the customer, not the server. If your integration is server-only, you have nowhere to surface the challenge. The customer drops off, the auth never completes, and you have a "requires_action" payment sitting in your database that never finishes. Handle 3DS at design time; don't bolt it on after a regulatory deadline.

Storing Card Data You Said You Wouldn't

If your error logs capture full request bodies and a developer logs the auth request, the PAN ends up in your log store. Now your log store is in PCI scope. Sanitise inputs at the SDK level, scrub structured logging, and audit anything that flows into observability tooling. PCI DSS v4.0.1 control 3.4.1 forbids storage of sensitive authentication data after authorisation; control 3.5.1 requires PAN to be unreadable wherever stored. Logs count as "stored."

Trusting the Reference, Not the Webhook

Some integrations show a "Payment received" page based on the client-side gateway response. That's fine for UX, but the server-side source of truth has to be the webhook (or a server-side capture call you control). Otherwise a customer can fake the response and trigger order fulfilment without paying. Always confirm money received via a server-to-server signal before releasing value.

Payment Gateway APIs and Telephone Payments

Payment gateway APIs are the foundation of most telephone payment solutions, even if the people using them do not interact with the API directly.

Powering Agent-Assisted Payments

When an agent takes a payment over the phone using a virtual terminal or a DTMF-based payment system, the underlying technology is communicating with a payment gateway API. The customer's card details -- captured either by the agent typing them in (less secure) or by the customer entering them on their phone keypad (more secure) -- are sent to the gateway API for processing. The gateway authorises the payment and returns the result, which the agent sees on their screen.

Building Custom Phone Payment Workflows

For businesses with specific requirements, the payment gateway API allows them to build custom telephone payment workflows. For example, a utility company might build an automated phone payment system that looks up the customer's account, states the balance, and processes the payment -- all through API calls. An insurance company might integrate the payment gateway with their claims system so that settlement payments are initiated automatically.

Integration with CRM and Telephony Systems

Payment gateway APIs can be integrated with CRM platforms, ticketing systems, and telephony infrastructure. This means that when a customer calls, the agent can see their payment history, process a new payment, issue a refund, or set up a recurring payment -- all within the same interface they use for managing the customer relationship. The API handles the payment processing behind the scenes.

IVR Payment Integration

Interactive Voice Response (IVR) systems use payment gateway APIs to process payments collected through automated phone menus. The customer navigates the IVR, enters their card details on their keypad, and the IVR system sends the details to the payment gateway API for processing. The entire transaction happens without any human involvement, providing 24/7 payment capability.

Choosing an Integration Pattern

Direct API vs Hosted Fields vs Redirect

A direct API integration gives you maximum control and maximum PCI burden. Hosted fields (gateway-rendered card inputs embedded in your page) give you most of the visual control with much less scope. A full redirect to a hosted payment page is the lowest control and the lowest scope. For most businesses the right answer is hosted fields plus a direct API for everything that isn't the card capture itself -- refunds, captures, customer management, subscription management. You get a unified branded checkout without dragging your application into SAQ D.

Single Gateway vs Orchestration

If you operate in one country with one card mix, a single gateway is fine. If you operate internationally, with local payment methods that differ by country, or you want failover between processors during outages, you need a payment orchestration layer -- either a third-party orchestrator or your own routing logic. Building orchestration in-house is more work than people expect because every gateway models the same concepts slightly differently; what one calls "authorize" another calls "create payment intent." Plan accordingly.

Tokenisation Strategy

Network tokens -- card numbers re-tokenised by the card networks themselves -- have higher authorisation rates and survive card reissuance better than gateway-specific tokens. If you're building a recurring billing system, ask whether your gateway supports network tokenisation. The difference in failed-renewal rate is real money.

Regulatory Context

PCI DSS v4.0.1

PCI DSS v4.0.1 is the current standard. v4.0 went live in March 2024, the transition deadline for the new "future-dated" requirements passed in March 2025, and v4.0.1 (a minor clarifying update) is what assessors work to as of 2026. The big API-relevant changes are the script-control requirements for payment pages (6.4.3, 11.6.1), the explicit treatment of e-commerce skimming attacks, and stricter MFA requirements for access into the cardholder data environment. If your last assessment was against v3.2.1, work through the gap analysis before your next renewal.

Strong Customer Authentication (UK and EU)

SCA under PSD2 requires two factors for most card-not-present transactions in the UK and EU. The gateway API exposes this as 3D Secure 2: the auth call either succeeds outright (low-risk, exempted) or returns a "requires_action" status with a challenge URL or client-side action. Your integration has to handle the challenge path or you'll lose conversions on every transaction the issuer flags. There's no opt-out -- SCA is mandatory for in-scope transactions and the issuers enforce it.

US Context

The US doesn't have an SCA equivalent. PCI DSS still applies. Card networks publish their own technical standards and chargeback rules, which the gateway abstracts away from you. 3D Secure is optional in the US and shifts chargeback liability when used. The same gateway API works on both sides of the Atlantic; the rules around what counts as a successful transaction differ.

Practical Considerations

Development Resources

Integrating a payment gateway API requires software development skills. You will need developers who can work with RESTful APIs, handle JSON data, implement error handling, and manage security credentials. The complexity of the integration depends on how sophisticated your payment workflow needs to be -- a simple one-off payment is straightforward, while a multi-currency subscription platform with instalment plans and partial refunds is significantly more involved.

Documentation and Support

The quality of a gateway provider's API documentation makes a huge difference to the development experience. Look for thorough, well-organised documentation with code examples in multiple programming languages, a sandbox or test environment for development, and responsive technical support for when things go wrong.

Testing and Sandbox Environments

Never test payment integrations with real card data. Use the gateway provider's sandbox environment, which simulates real transactions without moving actual money. Test all scenarios -- successful payments, declined cards, network timeouts, 3D Secure challenges, refunds, and edge cases. Thorough testing prevents costly errors in production.

PCI DSS Implications

How you integrate with the payment gateway API affects your PCI DSS scope. If your application collects card details and sends them to the API, your systems are in scope for PCI DSS. If you use techniques like tokenisation or redirect-based approaches to keep card data off your servers, you can significantly reduce your compliance burden. Discuss the optimal architecture with your gateway provider and your PCI assessor.

Versioning and Maintenance

Payment gateway APIs evolve over time. Providers release new versions, deprecate old endpoints, and update security requirements. Plan for ongoing maintenance of your integration, including monitoring for deprecation notices and testing against new API versions before they become mandatory.

Observability

You can't run a payment integration you can't see. Instrument every gateway call with a span that records latency, response code, decline reason if any, and a hash of the idempotency key. Alarm on authorisation rate drops, latency spikes, and webhook failure spikes. The gateway has a status page; subscribe to it and route it into your incident channel. A payment integration that quietly fails for 20 minutes during a peak hour can cost more than the entire monthly gateway bill.

Frequently Asked Questions

What's the difference between a payment gateway API and a payment processor API?

The lines blur. Historically, the gateway sat between the merchant and the processor -- the gateway translated the API request into the format the processor's network needed. Today most modern providers are vertically integrated: Stripe and Adyen are both gateway and processor. The API you call is "the gateway" in the colloquial sense, regardless of who clears the funds behind it.

Do I need a developer to use a payment gateway API?

Yes. The whole point of the API is programmatic access -- there's no UI on the API itself. If you want a no-code option, you're looking at a hosted payment page, a checkout button, or a billing platform like Recurly or Chargebee that wraps the gateway API for you. Those still exist; they're just a layer above the raw API.

How do I keep my application out of PCI scope while using a payment gateway API?

Use the gateway's client-side tokenisation library. The card is captured directly in the customer's browser (or on the customer's phone, in a telephone-payment context) and never touches your server. Your code only ever handles tokens. With this architecture you can typically complete SAQ A, the shortest PCI questionnaire.

What happens if the gateway times out before returning a response?

You don't know whether the transaction went through. Don't retry blindly -- query the gateway using the idempotency key from your original request. If the gateway received the request, the query returns the same transaction (whatever its outcome). If it didn't, the query returns nothing and you can safely retry. This pattern is non-negotiable for production integrations.

Are webhooks reliable enough to be the source of truth?

Webhooks are at-least-once delivery. They will sometimes arrive twice, sometimes arrive out of order, and occasionally fail to arrive at all (network blip, your endpoint down). Treat them as a fast notification channel and back them up with periodic reconciliation against the gateway's transaction list. Your books should match the gateway's books by the end of every day.

Can a payment gateway API handle telephone payments?

The same API that handles your website payments handles telephone payments. What changes is where the card data is captured. A keypad-based capture flow (DTMF masking) sends the digits to a PCI-scoped intermediary that builds the API request; the gateway endpoint and response format are identical to a web transaction. There's no separate "phone API" -- there's one API and several capture front-ends.

How do I handle 3D Secure on a server-only integration?

You can't, fully. SCA challenges have to be rendered to the customer's device. If your integration has no front-end (e.g. an IVR system), you have to route SCA-required transactions to a fallback channel where the customer can complete authentication -- often an SMS link or a callback. Plan for this case before SCA blocks 5-10% of your phone payments.

What's the difference between a token and a network token?

A gateway token is a reference issued by your payment provider that points at the card number stored in their vault. It works at that gateway only. A network token is issued by the card scheme itself (Visa, Mastercard) and references the underlying card account; it survives card reissuance, generally has higher authorisation rates, and travels between processors. If your provider supports network tokens, use them for recurring transactions.

How often will the API change?

Major gateways version their APIs and support multiple versions in parallel. Stripe pins your account to the version you signed up on; you upgrade explicitly. Others auto-upgrade and announce deprecations. Either way, plan for at least one breaking-change migration every 18-24 months and budget developer time accordingly. The cost of running an aged, never-touched integration is paid at the moment your version gets sunset.

Can I switch gateway providers later if I've built directly to one API?

Yes, but it's work. The transactions, customers, payment methods, and webhooks all model the same concepts in slightly different ways. The realistic options are (a) a clean re-platform with a migration window for existing customers, (b) a parallel run where new business goes to the new gateway and old subscriptions roll off the old one, or (c) an orchestration layer abstracting both. Plan for at least a sprint of integration work; budget more for production stabilisation and recon.