Payment gateway API: how it works and what to compare

A payment gateway API is the set of endpoints a business calls to authorize a card payment, then capture, void or refund it, to store the card as a token, and to receive the outcome by webhook. It sits between the checkout page and the processor and acquiring bank that move the money. This guide covers the core calls, PCI DSS scope and the terms worth comparing.

What a payment gateway API does

Most gateway APIs expose four operations under different names. Authorize reserves funds on the card, capture collects them, void cancels an authorization before settlement, and refund returns money after settlement. Authorize.net models all four as transactionType values: authOnlyTransaction, priorAuthCaptureTransaction, voidTransaction and refundTransaction.

Splitting authorization from capture is usually a per-request setting. On Stripe a business sets capture_method to manual on a PaymentIntent, which instructs Stripe to “authorize the amount but not capture it”; if the authorization expires uncaptured, “the funds are released” and the payment status changes to canceled (Stripe). How long the capture window runs depends on the card brand and the transaction type, and providers document it differently.

Sources for the rows: Stripe, Braintree and Authorize.net.

Voids and refunds are not interchangeable. Braintree allows a void while a transaction is Authorized or Submitted for Settlement and tells a merchant that does not want to settle it: “you should void it to avoid a misuse of authorization fee”; once the transaction is Settling or Settled, a refund is required instead (Braintree). Authorize.net states that once a transaction settles it cannot be voided, and that by default a merchant can refund a settled transaction within 180 days of settlement (Authorize.net). Stripe lets a business cancel a payment before it completes at no cost, allows several partial refunds up to the original amount, may charge a fee on a refund after success, and sends refunds only back to the original payment method (Stripe).

Gateway, processor and acquirer: who does what

Visa puts the gateway at the front of the chain: payment gateways are “the front-end technology built into websites or apps” that secures checkout, while a payment processor is the set of “back-end systems” that let banks and card networks exchange data for authorization, and the acquiring bank holds the funds in a merchant account (Visa). Visa’s developer glossary defines an acquirer as “A Member that signs a Merchant” and enters the resulting transaction receipt into Interchange, and a payment service provider as an entity that gives merchants the ability to accept electronic payments (Visa).

Gateways describe themselves the same way. Authorize.net says it “acts as a bridge between your company and the financial entities” that oversee processing and settlement, and that it does not store the merchant’s funds (Authorize.net). A gateway account alone therefore does not let a business accept cards: Authorize.net approves the gateway account automatically on application, while approval of the merchant account “can be immediate or take from one to five business days or more” (Authorize.net).

Software platforms that pass a gateway API through to their own users sit in a different pattern, covered in embedded payments. Profiles: Stripe Connect, Adyen for Platforms.

Tokenization, vaulting and network tokens

Adyen defines tokenization as replacing sensitive data such as the card number with a token stored in the Adyen Vault, and says of the result: “Tokens reduce your security risks and lowers your PCI DSS scope.” Its Sessions flow, Adyen writes, “qualifies you for the simplest form of PCI validation (SAQ A)” (Adyen).

Network tokens come from the card networks instead. Visa Token Service replaces a 16-digit Visa account number with a token carrying a surrogate account number and cryptographic data, and Visa’s FY2025 annual report states: “As of September 30, 2025, Visa has provisioned more than 16 billion tokens.” (SEC filing, November 6, 2025). On June 4, 2024 Visa said it had issued more than 10 billion tokens since the technology’s 2014 launch, with over 8,000 issuers enabled for tokenization (Visa). Mastercard, whose tokenization service also started in 2014, announced on June 11, 2024 a commitment to 100% e-commerce tokenization in Europe by the end of the decade and said the service then “secures 25% of all e-commerce transactions globally”, its own figure (Mastercard). On June 10, 2026 Visa announced richer token data on transaction type, where a token is used and who pays, plus a “token assurance signal” evaluated across a token’s lifecycle from provisioning and behavioral history (Visa).

A vault token belongs to the provider that stores the card. The provider documentation used here does not publish terms for moving stored tokens to another provider, so treat portability as a contract question rather than a documented feature. Businesses that route across more than one gateway handle it at the payment orchestration layer. Profiles: Spreedly, Primer.

3-D Secure and EMV 3DS

EMVCo, which owns the specification, describes EMV 3DS as a card-not-present fraud prevention technology in which the merchant sends transaction, payment method and device data to the issuer to “confirm that the consumer making the purchase is the actual cardholder” (EMVCo). The result is not always a challenge screen: the frictionless flow “enables issuers to accept transactions without challenging cardholders” on a real-time risk assessment of transaction, cardholder history, device and IP data (EMVCo, October 10, 2024).

Versions matter in procurement. EMVCo released EMV 3DS 2.3.1 on September 29, 2022, stating that it “is effective immediately and replaces EMV 3DS 2.3.0” and adding data elements for Secure Payment Confirmation and out-of-band authentication; EMVCo’s documentation page lists the Protocol and Core Functions Specification v2.3.1.1. Both generations are still in play: an EMVCo Letter of Approval dated May 20, 2026 tests against “the EMV 2.2.0 and/or 2.3.1 Specifications”.

When 3DS fires is a gateway setting. Stripe triggers it automatically where regulation requires, such as Strong Customer Authentication in Europe, on an issuer soft decline, or through Radar and API rules; wallets and off-session payments may not support 3DS, and Stripe also sells standalone 3DS for use with another payment service provider (Stripe).

Idempotency keys, webhooks and sandboxes

Payment requests get retried, so key limits and lifetimes belong in the integration design.

Stripe saves the first result, including a 500 error, and returns it on retries, while reusing a key with different parameters returns an error. Adyen scopes keys to the company account and does not check them across regional endpoints; concurrent duplicates return HTTP 422 or 409 with error 704. Checkout.com caches only 2xx responses, applies the header to payments, captures, refunds and voids, and returns 409 on concurrent duplicates.

Webhooks carry the asynchronous half of a payment. Stripe sends events as HTTPS JSON for cases such as a bank confirming a payment or a customer disputing a charge, and recommends verifying each event with the Stripe-Signature header, the endpoint secret and the raw request body (Stripe webhooks, signature verification).

Sandboxes differ in scope and even protocol. Stripe sandboxes are isolated test environments where test cards such as 4242 4242 4242 4242 simulate success, declines, disputes, refunds and 3DS, and where “these transactions don’t move funds” (Stripe). Authorize.net publishes a separate sandbox endpoint at https://apitest.authorize.net/xml/v1/request.api and notes that its API “is not based on REST”: JSON is translated into XML elements, so element order must match the reference (Authorize.net). Adyen’s Checkout API offers a Sessions flow with one server request to /sessions and an Advanced flow with three: /paymentMethods, /payments and /payments/details (Adyen).

PCI DSS scope: hosted fields or direct API

The integration style decides which Self-Assessment Questionnaire a merchant completes and how many PCI DSS requirements come with it. The table below is from the PCI Security Standards Council’s SAQ Instructions and Guidelines v4.0.1 r1, April 2025.

The PCI SSC lists e-commerce merchants that accept account data on their website, and merchants with electronic storage of account data, among the SAQ D examples (PCI SSC, April 2025). SAQ A eligibility is strict about delivery: all elements of the payment page reaching the customer’s browser must originate “only and directly from a PCI DSS compliant TPSP/payment processor”, and if any element originates from the merchant’s website, SAQ A does not apply (PCI SSC SAQ A). SAQ A r1 added a further criterion, that “the merchant has confirmed that their site is not susceptible to attacks from scripts”; the PCI SSC’s FAQ 1588 says this can be met through techniques like Requirements 6.4.3 and 11.6.1 or by confirmation from the iframe provider, applies it to embedded pages rather than redirects, and puts the requirements in effect on April 1, 2025 (PCI SSC, February 28, 2025).

Providers publish their own mapping. Checkout.com states that Flow, its Hosted Payments Page, Payment Links, Frames and mobile SDKs need SAQ A, while “Our Full Card API with your own integration platform” needs SAQ D (Checkout.com). Braintree lists Hosted Fields and Drop-in as SAQ A integrations and itself as a validated Level 1 PCI DSS service provider (Braintree). Stripe says a business handling untokenized card data directly “might be required to meet more than 300 security controls in PCI DSS”, its own figure, that it is certified annually as a PCI Level 1 Service Provider, and that the card type, last four digits and expiry it returns are out of PCI scope (Stripe). Stripe’s per-integration SAQ mapping is not published in the pages used here.

Published pricing

The order of rows carries no meaning, and each figure is the provider’s own published rate as of August 5, 2026.

Sources for the rows: Stripe, Adyen pricing and Adyen Visa fees, PayPal Braintree fees, Authorize.net and Checkout.com.

What to compare when choosing a payment gateway API

• Authorization window per brand and transaction type. Stripe documents 5 to 7 days for card-not-present authorizations, Braintree up to 30 days for a Mastercard preauthorization, Authorize.net 30 days for Authorization Only.
• Void and refund boundaries. Ask at which status a void stops working, whether a misuse-of-authorization fee applies, and how long after settlement a refund is allowed.
• Idempotency key limit and lifetime. 255 characters and 24 hours on Stripe, 64 characters and at least 7 days on Adyen, 72 hours on Checkout.com, and the error code a concurrent duplicate returns.
• SAQ level per integration. A hosted or embedded form can put a merchant in SAQ A at 27 requirements; a direct card API can mean SAQ A-EP at 139 or SAQ D.
• Token storage and network tokens. Where the card sits, what the provider states about PCI scope, and whether network tokens from Visa or Mastercard are supported.
• 3DS control. Which version the provider supports, what triggers a challenge, and whether standalone 3DS can be used with another provider.
• Webhook verification and sandbox coverage. Signed events with a documented verification path, plus test cards that reproduce declines, disputes and 3DS.
• Published pricing or a quote. Stripe, Adyen, Braintree and Authorize.net publish rates; Checkout.com does not.

More in the payments guides.