Headless Commerce Payments: Integrating a Gateway Into a Custom Front End
Headless commerce payments explained: how to pick a gateway integration that keeps PCI scope small and stops charges with no matching order.

Photo: Pixabay
On this page 6 sections
- How Headless Commerce Payments Differ From a Platform Checkout
- Headless Commerce Payment Gateway Options for Collecting Card Details
- PCI in Headless Commerce: Keeping Scope Small on a Custom Front End
- Wallets and Saved Cards Need Their Own Wiring in a Headless Build
- Order Sync: Wiring the Payment API to Your Headless Store
- Testing and Monitoring a Headless Checkout
Key takeaways
- Decide who renders the card fields before anyone designs the checkout page, because that choice sets your PCI scope.
- An iframe does not remove all PCI work. The page that loads it, and every script on that page, still matters.
- Send the amount and an idempotency key from your server, never from the browser, so retries can't double-charge and shoppers can't edit prices.
- Run a nightly job that matches gateway transactions to orders. It catches charges with no order before the customer calls about them.
Headless commerce payments work best when your custom front end never touches a raw card number. Build the storefront however you like, but let your payment gateway's hosted components collect card details and run authentication, and have your server talk to the gateway only with tokens. Get that split right and your PCI compliance work stays close to what it was on a platform checkout. Get it wrong and one design shortcut can turn your whole web app into a system that handles card data.
The first decision, and the one that shapes everything after it, is who renders the card fields. Make it before anyone designs a checkout screen.
How Headless Commerce Payments Differ From a Platform Checkout
On a standard hosted storefront, the platform owns checkout from the card form to the confirmation email. You adjust settings, and the platform carries most of the security burden.
Going headless separates the storefront (a custom web app, often with a native mobile app beside it) from the commerce back end that holds products and orders. The two talk through APIs. That gives you design freedom. It also hands your team payment jobs the platform used to handle quietly. Card details have to be collected in a way that keeps them off your servers. Your server has to authorize and capture charges through the gateway's API. And every payment result has to land on the right order, even when a browser crashes mid-checkout.
Native apps add their own wrinkle. They usually rely on the gateway's mobile SDK, which tokenizes the card inside the app before anything reaches your back end. That SDK has its own release schedule, so budget for keeping it current alongside the web integration.
Some brands go only partly headless. They build a custom storefront but send shoppers to the platform's own hosted checkout at the payment step. That is the lowest-effort path, and it keeps most payment responsibility with the platform. The cost is a visible handoff and less control over the final screens. Some platforms also limit which gateways their hosted checkout supports, so confirm that before you commit.
If the line between the gateway and the account that settles your money is fuzzy, read payment gateway vs. merchant account for online stores first. A headless build touches both.
Headless Commerce Payment Gateway Options for Collecting Card Details
Most gateways give a headless store a few ways to collect payment details. The right one depends on how much design control you need and how much compliance work you can carry.
| Pattern | How it works | Design control | PCI burden on you | Wallets and 3-D Secure |
|---|---|---|---|---|
| Redirect or hosted payment page | Shopper leaves your site for a gateway-hosted page, then returns | Low: logo and colors, sometimes CSS | Lightest | Handled by the gateway page |
| Drop-in payment component | Gateway's prebuilt UI loads inside your page | Medium: theming options | Light, but your page still matters | Usually built in |
| Hosted fields | Each card input is a small gateway iframe placed inside your own form | High: you control layout and surrounding UI | Light to moderate, and your page matters more | You wire them up yourself |
Hosted fields appeal to design-led brands because the checkout looks native. They also carry the most integration code. Your team builds every error state and validation message around them, and often the wallet buttons and the 3-D Secure challenge window too. Drop-in components get you most of the look with far less code. Redirects are the safe default for a first launch or a small team.
One pattern sits outside the table on purpose: building your own card inputs and posting the card number to your own server or API. Some teams do it for pixel-perfect control. It pulls your servers, and often your hosting and logging stack, into full PCI scope. For a brand that sells goods, there is rarely a business reason to accept that.
PCI in Headless Commerce: Keeping Scope Small on a Custom Front End
PCI DSS is the card industry's data security standard. The PCI Security Standards Council writes it, and your acquiring bank enforces it under card network rules. It is not federal law, but your merchant agreement requires it. Most e-commerce merchants prove compliance with a self-assessment questionnaire (SAQ), and which questionnaire you complete depends on how card data reaches the gateway.
Teams often assume an iframe takes their site out of scope. It doesn't. The iframe keeps the card number away from your code, and that cuts your scope a great deal. But your page decides which iframe loads and what surrounds it. A compromised script on that page could swap the real field for a fake one or lay a lookalike form over it. Current PCI DSS guidance puts increasing focus on controlling and monitoring the scripts that run on payment pages for exactly this reason. Confirm the specific requirements that apply to you with your processor or assessor.
In general terms, a full redirect to a gateway-hosted page tends to put you in the shortest questionnaire. Embedded fields keep scope small, but your payment page carries obligations of its own. Once your own systems receive card numbers, you face the long questionnaire or more. Eligibility rules have changed between versions of the standard, so confirm your questionnaire with your processor or a qualified security assessor before launch.
These habits keep scope small on a custom front end:
- Keep the checkout route lean. Marketing tags and chat widgets don't belong on the page that hosts payment fields, and neither do heatmap or testing tools. Load them on every other route.
- Lock down what can run. A Content Security Policy that allows only the gateway's domains and your own makes injected scripts much harder to slip in.
- Store tokens, never card numbers. Your database, logs and error tracker should only ever see gateway tokens and the last four digits.
- Calculate the amount on the server. The browser should send a cart or order ID, and your server looks up the total. If the browser sends the price, a shopper with developer tools can change it.
PCI scope is a compliance question with contractual and legal consequences. Treat this section as general information and confirm your obligations with a qualified assessor.
Wallets and Saved Cards Need Their Own Wiring in a Headless Build
Wallets are where headless builds most often break quietly. On a hosted checkout they just work. On a custom front end you set them up yourself.
Apple Pay and Google Pay. On the web, wallet buttons usually come through your gateway's component or SDK. Apple Pay on the web generally requires you to register the domains that show the button. A new headless domain is easy to miss, and so is a staging site or a separate checkout subdomain, so check your gateway's documentation for each one. In native mobile apps, wallets use the phone's in-app payment sheet and a separate configuration. Our guide to adding Apple Pay, Google Pay and PayPal to your checkout walks through setup. If you sell physical goods inside your own app, using your own processor for in-app payments explains where app store billing rules do and don't apply.
Buy now, pay later. BNPL providers usually run their own approval flow in a modal or redirect, approve the shopper, then pay you. In a headless build that means a second SDK on the front end and a second set of webhooks on the back end. Orders paid this way should wait for the BNPL provider's confirmation before they move to paid, not your card gateway's.
Saved cards. Gateways keep the card in a vault and return a reusable token. The card networks have rules for stored credentials. You need the customer's agreement to store the card, and the first and later transactions must be flagged correctly as card-on-file. A team building "save this card" from scratch should confirm with the gateway exactly which API fields each type of transaction needs.
3-D Secure. When an issuer challenges a purchase, the challenge window has to render inside your front end, including on small phone screens. Test it early. The MannyPay 3D Secure page describes authentication options, and 3D Secure for online stores explains the chargeback liability shift.
Order Sync: Wiring the Payment API to Your Headless Store
On a hosted platform, the order and the payment are created together. In a headless store they live in two systems that can disagree. The most expensive failure is a charge with no order: the customer paid, the browser died before the confirmation page loaded, and your back end never recorded the sale.
Here is an illustrative flow that prevents it. Assume a gateway that supports idempotency keys and a commerce back end that accepts webhooks. An idempotency key is a unique ID that tells the gateway, "If you've seen this request before, return the first result instead of charging again."
- The shopper clicks Pay. Your server creates the order with a status of pending payment and an amount taken from the cart, not from the browser.
- The hosted field turns the card into a token and hands it to your front end.
- Your server sends an authorization request with the token, the server-side amount and an idempotency key derived from the order ID.
- The gateway approves, but the shopper's connection drops before the confirmation page loads. They hit Pay again.
- Your server repeats the request with the same idempotency key. The gateway returns the original approval and does not create a second charge.
- The gateway's webhook reaches your server and the order moves to paid. If the webhook fails, the gateway retries it, and your handler ignores duplicates.
- Each night, a job compares the day's gateway transactions with paid orders. Any authorization without a matching order gets attached to its order or voided before it settles.
Not every gateway handles idempotency the same way. Some rely on a duplicate-transaction time window instead, so ask yours how it works. The nightly match also gives your finance team clean data for reconciling processor payouts to orders.
Decide capture timing at the same time. Stores that ship later often authorize at checkout and capture at fulfillment. That logic now lives in your back end, not the platform's, so build alerts for authorizations that are close to expiring.
Testing and Monitoring a Headless Checkout
Test against the gateway's sandbox before launch, and give the failure cases as much attention as the happy path:
- Declines across several decline codes, along with the error message shoppers see for each
- 3-D Secure challenges that fail or time out, on phones as well as desktop
- Wallet payments on real devices, on every production domain
- Webhooks that arrive twice or out of order
- A network drop between authorization and confirmation, the scenario in the order flow above
After launch, track approval rate by payment method and watch for spikes in specific decline codes. Your webhook failure queue deserves an alert, and so does any change to the scripts loading on the checkout route. Headless checkouts with permissive APIs attract bots, so velocity limits and CAPTCHA triggers belong in the build from day one. See stopping card testing attacks on your checkout for controls that work.
Your first task this week: pick one of the integration patterns above and write down every script that will run on the payment page. MannyPay offers online payment processing and payment gateways such as Authorize.Net and NMI. If you want to talk through gateway and processing options for your build, request a free quote and a MannyPay specialist will respond within one business day.
This article is for general educational purposes and is not legal, tax or financial advice. Card network rules and state laws change; confirm current requirements for your business.


