Payment Gateway API: The Complete Developer's Guide (2026)

What Is a Payment Gateway API?

A payment gateway API is a set of HTTPS endpoints your application calls to authorise card transactions, capture funds, issue refunds, and store payment credentials — the programmatic interface that connects your software to the global payment network.

Every time a business takes a card payment online, a payment gateway API is involved. Strip away the checkout UI, and you will find a POST request going to a gateway endpoint, a JSON response coming back, and a webhook arriving shortly after to confirm the final status.

Your implementation choice at the API layer also determines your PCI DSS compliance tier — a decision that shapes your annual audit scope and security architecture.

Payment Gateway vs Payment Processor vs PSP

These three terms are often used interchangeably, but they refer to different layers of the payments stack:

Most modern providers are vertically integrated — they function as gateway, processor, and PSP in one. When you integrate their API, you are accessing all three layers simultaneously.

Why Integrate at the API Layer?

Integrating at the API layer gives you full control over checkout UI, error handling, how payment events flow into your CRM or order management system, and which payment methods appear at checkout. The tradeoff is PCI DSS scope: how you implement the API determines whether your servers stay out of scope entirely or get drawn into a full compliance audit.

How a Payment Gateway API Works

A payment gateway API processes a transaction by receiving a signed POST request from your server, routing it through the card network to the issuing bank, and returning a structured approval or decline — typically within two to three seconds.

Here is the full flow:

1. Customer initiates payment. The customer enters card details on your checkout page, or selects a saved card or digital wallet. If your integration uses client-side tokenisation, the card number never reaches your server.

2. Token is created. The gateway's JavaScript library captures card data in the customer's browser and exchanges it for a one-time payment token. Your server only ever sees the token.

3. Your server sends the API request. Your backend sends an HTTPS POST to the gateway endpoint, including the token, transaction amount, currency, an idempotency key, and authentication credentials. The request body is JSON; the headers carry a digital signature confirming the request has not been tampered with in transit.

4. The gateway validates and routes. The gateway checks the signature, validates the request, and forwards the authorisation request to the relevant card network (Visa, Mastercard, UnionPay, etc.), which routes it to the customer's issuing bank.

5. The issuing bank responds. The bank checks the account balance, applies fraud scoring, and returns an approval or decline code.

6. Your server receives the response and acts. The API returns a structured JSON response: a transaction ID, a status, and if declined, a reason code. Your server updates its records accordingly.

Synchronous vs Asynchronous Responses: The 3D Secure Case

Not all payment API responses mean a transaction is complete. A synchronous response gives an immediate SUCCESS or FAILED. An asynchronous response returns REQUIRES_ACTION — which typically signals a 3D Secure (3DS2) challenge.

When this happens, your frontend must surface an authentication URL or challenge flow to the customer before the payment can proceed. This is a common failure point in cross-border integrations: if your code only handles the SUCCESS path, any transaction requiring 3DS authentication silently fails — and the customer never completes payment. This is why building order fulfilment logic around webhook events, not the initial API response, is the correct architecture.

API Keys: Publishable vs Secret

Payment gateway APIs issue two types of credentials:

• Publishable key — safe to embed in frontend JavaScript. Used to create tokenised payment method IDs in the browser without sending raw card data to your server.

• Secret key — used only on your backend to confirm, capture, and refund payments. Treat this like a password to your merchant account. Store it in your secrets manager, never in source code, and rotate it if a developer leaves.

Webhooks: The Real Source of Truth

A timeout on your API call does not mean the payment failed — it means you do not know what happened. The card may already be charged.

Payment gateway APIs use webhooks to push event notifications when something happens: a payment succeeds, a refund is processed, a chargeback is filed. Your webhook handler must verify the signature on every incoming event, check for duplicate event IDs, and update order state based on the confirmed webhook — not the original API response.

Types of Payment Gateway APIs

Payment gateway APIs are categorised by the payment action they perform, with each type mapping to a distinct set of endpoints and a specific business use case.

Most providers bundle these into a unified API rather than requiring separate integrations for each action type — reducing the number of credentials, documentation sets, and failure modes you need to manage.

Payment Gateway API for US and European Merchants Expanding into Southeast Asia

For US and European merchants entering Southeast Asia, a payment gateway API must support local digital wallets and real-time bank transfers — not just Visa and Mastercard — to reach consumers across Indonesia, Thailand, the Philippines, Malaysia, and Singapore.

This is not a niche consideration. According to an IDC InfoBrief commissioned by 2C2P (How Southeast Asia Buys and Pays 2025), digital wallets were the leading payment method in Indonesia, Malaysia, and Vietnam in 2023, and by 2028, mobile wallets and domestic payments are projected to account for 94% of total e-commerce payment value in Southeast Asia.

For a merchant integrating a card-only gateway, consumers in these markets either use an international card (lower penetration, higher friction) or abandon the purchase.

The key local payment methods across Southeast Asia and East Asia include:

What One Integration Can Cover

Rather than integrating each local method separately — each with its own API contract, credential set, reconciliation format, and failure mode — payment orchestration routes every transaction through a single API layer connecting to local gateways, wallets, and bank transfer networks across markets.

Antom's unified payment API extends that same coverage — including the local digital wallets listed above — across 100+ settlement currencies, all through a single integration. For merchants expanding internationally, this replaces a multi-year gateway integration roadmap with one API connection.

How to Integrate a Payment Gateway API: Steps, PCI Scope, and Common Pitfalls

Integrating a payment gateway API involves five steps — from obtaining credentials to handling live webhook events — and your implementation choice at step one determines your entire PCI DSS compliance scope.

Step-by-Step Integration

Step 1: Create an account and get your API credentials.
Create an account with your payment gateway provider and retrieve both your publishable and secret API keys from the developer dashboard. Always start with sandbox credentials for testing. For Antom, this begins at the Antom Dashboard.

Step 2: Add the gateway's client-side library to your checkout page.
Embed the provider's JavaScript SDK on your payment page to capture and tokenise card data in the browser, ensuring raw card data never reaches your server. This single decision keeps you eligible for SAQ A — the lowest PCI DSS compliance tier.

Step 3: Build the server-side API request.
Assemble the payment request — token, amount, currency, idempotency key, and signed authentication credentials — and send it as a JSON-encoded HTTPS POST to the gateway endpoint.

Step 4: Test every scenario in the sandbox environment.
Run your full integration through successful payments, declines, 3DS challenges, timeout edge cases, refunds, and webhook retries. A good sandbox uses separate endpoint domains — not just a test_mode flag — and triggers webhook events just as production does.

Step 5: Go live and monitor webhooks in production.
Switch to production API credentials and endpoint domains. Confirm your webhook handler verifies signatures and checks idempotency, and configure alerting for webhook delivery failures from day one.

PCI DSS Scope: Which SAQ Applies?

PCI DSS is the security standard governing how card data must be handled, with periodic updates to reflect evolving threats — always verify you're building against the current version before going live.

Your integration architecture determines your compliance tier:

Practical recommendation: use your gateway's client-side JS library and target SAQ A. It is achievable for most e-commerce implementations and significantly reduces your annual compliance overhead.

Four Integration Failure Modes to Avoid

1. Treating a timeout as a failed payment.
If your API call times out before receiving a response, the transaction status is unknown — not failed. The card may already be charged. Query the gateway using your original idempotency key before taking any other action.

2. Processing webhook events without idempotency checks.
Gateways retry webhooks when your endpoint returns a non-200 response or times out. If your handler is not idempotent, you risk double-fulfilling orders or double-processing refunds. Track event IDs and skip events already processed.

3. Not handling the 3DS challenge path.
When a gateway returns REQUIRES_ACTION, your frontend must render the challenge flow. An integration that only handles the SUCCESS path silently drops transactions requiring authentication — a common cause of conversion loss on EU and UK card transactions.

4. Logging raw card data by accident.
If your error handling or logging middleware captures the full API request body, card numbers can end up in your log store — immediately pulling that system into PCI DSS scope. Sanitise inputs at the SDK level and audit anything flowing into observability tooling.

Go-Live Readiness Checklist

Before switching to production credentials, confirm all of the following:

• Card data never touches your server (tokenisation in browser via JS SDK)

• Idempotency key included with every payment request

• Webhook handler verifies signature before processing any event

• Webhook handler checks for duplicate event IDs before updating order state

• Full test suite completed in sandbox: success, decline, 3DS challenge, timeout, refund

• Error logging sanitised — raw card fields excluded from request body logs

• 3DS challenge flow rendered to the customer in the frontend, not just success path handled server-side

• Production webhook delivery failure alerting is configured

How to Choose a Payment Gateway API: The 6-P Framework

Choosing a payment gateway API comes down to six dimensions — what we call the 6-P Framework — and the right weight for each depends on your business model, transaction volume, and target markets.

P1: Payment Methods — Local and Global Coverage

Does the API cover the payment methods your customers actually use? Cards are the starting point. The real differentiator is local coverage: digital wallets, real-time bank transfers, buy now pay later, and national payment schemes that consumers in your target markets prefer over cards.

Antom's unified API delivers that same broad coverage through a single integration, including major local wallets across Asia-Pacific, Europe, and Latin America.

P2: PCI Path — Which SAQ Your Integration Enables

Does the API's architecture allow SAQ A compliance for your team? Specifically: does it provide a client-side JavaScript library that tokenises card data in the browser before your server ever sees it? If the integration requires your server to handle raw card numbers, your compliance costs increase substantially.

P3: Programmability — SDK Quality, Documentation, and Sandbox

Good documentation means: a real sandbox that behaves like production, clear reference documentation for every endpoint and error code, and SDKs in your team's preferred languages. Antom provides SDKs for Python, PHP, and Java, with a sandbox environment using separate endpoint paths from production.

P4: Processing Reliability — Uptime, Webhooks, Idempotency, and Dispute Tooling

Check whether the gateway guarantees at-least-once webhook delivery with a retry policy, publishes its signature verification method clearly, and supports idempotency keys on payment requests. Also, evaluate whether the API exposes endpoints for chargeback notifications and evidence submission — manually handling disputes through email is a hidden operational cost that scales badly.

Antom's payment infrastructure operates at 99.999% system uptime.

P5: Price and FX — Settlement Currencies and FX Transparency

Confirm: how many currencies the API supports for authorisation, how many settlement currencies are available, and what the FX rates and timing are. A gateway that authorises in 140+ currencies reduces cart abandonment from currency mismatch and simplifies reconciliation across markets.

P6: Performance — Smart Routing and Authorisation Rate Impact

Does the API dynamically route each transaction through the optimal processing path to maximise authorisation rates? Smart routing — selecting the best acquirer, payment method, or processing path for each transaction — is the difference between payment infrastructure that simply processes transactions and one that actively recovers revenue.

FAQ

What is the difference between a payment gateway API and a payment processor?

A payment gateway API handles the secure transmission and routing of payment data — your code talks to the gateway, and the gateway talks to financial networks. A payment processor handles the actual movement of funds between the issuing bank and the merchant's account after authorisation. Most modern providers operate as both, so when you integrate their API, you are accessing both functions through a single connection.

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

Yes. The API itself has no user interface — it is a set of HTTPS endpoints your code calls. If you want a payment integration without writing backend code, you need a hosted payment page, a checkout link, or a no-code plugin. Antom offers Shopify and WooCommerce plugins that require no development work.

How do I keep my website out of PCI DSS scope when using a payment gateway API?

Use the gateway's client-side JavaScript library to tokenise card data in the customer's browser before it reaches your server. With this approach, your server only handles a one-time token —making you eligible for SAQ A, the lowest PCI DSS compliance tier.

How do I test a payment gateway API before going live?

Use the sandbox environment provided by your gateway. A good sandbox uses separate endpoint domains (not just a test_mode flag), provides test card numbers simulating different approval and decline scenarios, and triggers webhook events just as production does. Run your integration through every scenario — approvals, declines, 3DS challenges, refunds, and webhook retries — before switching to live credentials.

Can one payment gateway API handle 300+ payment methods across multiple countries?

Yes. Unified payment APIs operating as payment orchestration layers connect to hundreds of local gateways, wallets, and bank transfer networks through a single API contract. Antom's API covers 300+ payment methods across 200+ markets and 100+ currencies from one integration.

What is a real-world example of a payment gateway API?

Antom's unified payment API is a real-world example: a set of HTTPS endpoints that lets merchants authorise transactions, process refunds, and reach local wallets like GrabPay, GCash, DANA, PromptPay, and PayNow — alongside hundreds of other payment methods worldwide — through a single integration. Payment gateway APIs also come in specialised forms: subscription APIs for recurring billing, payout APIs for marketplace disbursements, and 3D Secure authentication APIs for SCA-compliant card flows.

Getting Started with a Payment Gateway API

A payment gateway API is the technical foundation of every modern checkout. The difference between a good integration and a costly one comes down to three decisions: the PCI compliance path you design from day one, how you handle webhooks and failure states, and whether the API you select can reach your customers where they actually pay.

If your business operates across borders — or plans to — that last point matters more than most API evaluations account for. Covering global card networks is the starting point. Covering the local wallets, real-time bank transfers, and national payment schemes that consumers in high-growth markets prefer is what determines whether your international checkout actually converts.

To explore how Antom's unified payment API delivers this level of global coverage from a single integration — complete with a sandbox environment and SDKs for Python, PHP, and Java — contact the Antom team.