By E-commerce 4 Internet Marketers Editorial
A headless storefront separates the shopping interface from commerce services and payment processing. It gives a merchant more control over speed, content, and checkout design, but removes the platform’s default checkout as a single source of truth. For a merchant using a high-risk processor, that can turn a routine card payment into a coordination problem involving a cart, a tokenization service, a gateway, a fraud system, and several asynchronous webhooks.
The stable pattern is to keep card data out of the storefront and make payment state explicit. The browser creates a short-lived token or payment method through an approved gateway component. A server then submits that token with a server-side order reference. The commerce platform remains responsible for the cart and order, while the processor remains responsible for authorization, capture, and risk decisions.
Why headless checkouts stress high-risk processors
High-risk processing has tighter scrutiny around fraud signals, velocity, reserves, and disputes. A headless build can obscure those signals when the frontend sends incomplete billing data, changes totals after authorization, or retries without an idempotency key. A spinner can hide an approval, and a second attempt can create a duplicate authorization.
There is also a timing gap. A gateway may return an intermediate state, request 3DS authentication, or settle through a webhook later. Do not treat the first API response as the final order state. Record a payment attempt and gateway transaction ID, then move the order only when the result is verified.
WooCommerce Store API from cart to payment
WooCommerce’s Store API handles customer-facing product, cart, and checkout operations. It is unauthenticated and scoped to the current customer session, while write operations use a nonce. Start with a cart request, retain the returned Cart-Token when issued, and send it on later calls so the server can associate requests with the same cart.
The checkout request goes to /wp-json/wc/store/v1/checkout. The client supplies customer and shipping details plus a payment method and the gateway-specific payment_data. The field may carry a one-time nonce, device data, or redirect result. Tokenize card details with hosted fields or a gateway SDK first. Never put a raw primary account number in payment_data, logs, analytics events, or a custom API proxy.
Use the Store API Nonce header for operations that require it, keep the Cart-Token private to the session, and validate the final order response on the server. If the gateway starts a 3DS challenge, preserve the checkout and payment attempt IDs while the customer completes the challenge. A successful browser redirect is not proof of capture. Confirm the transaction through the gateway and WooCommerce order data before showing a paid confirmation or releasing fulfillment.
Shopify Storefront Cart and checkoutUrl
Shopify’s Storefront API supports cart creation and updates through GraphQL. Use the Cart API rather than older Checkout API examples. After adding lines and buyer identity, request checkoutUrl and send the buyer to Shopify checkout. Shopify then controls supported payment, tax, address, and authentication steps while the custom storefront retains its product experience.
That handoff works when a high-risk gateway is available through Shopify’s supported payment ecosystem, but it is less flexible than a custom processor call. A private Storefront token does not make an arbitrary gateway compatible. Confirm gateway, market, currency, fraud review, and 3DS behavior before building around it.
After checkout, treat webhooks as the system of record for order progression. For HTTPS deliveries, verify the X-Shopify-Hmac-SHA256 value against the raw request body and the app client secret before parsing or trusting the payload. Record X-Shopify-Webhook-Id to make processing idempotent, and use the event ID when correlating deliveries from multiple subscriptions. Queue the event, return HTTP 200 quickly, and reconcile an order when a payment or fulfillment transition is missing.
BigCommerce GraphQL checkout then Payments API
BigCommerce headless builds can use Storefront GraphQL to create a cart, add lines, set checkout details, and obtain a checkout identifier. Collect only the data needed for checkout, then send payment through a secure gateway component and the server-side BigCommerce Payments API.
A key detail is the paymentAccessToken. Obtain and use it through the current BigCommerce GraphQL and Payments API flow instead of exposing broad store credentials in the browser. Keep it short-lived, bind it to the intended checkout where supported, and never reuse it as a general API credential.
Model the result as a state machine. Checkout can exist before payment, the Payments API can return an intermediate or declined result, and the order can change after the processor responds. Store checkout ID, order ID, payment attempt ID, amount, currency, and gateway reference. After a timeout, query payment and order state before retrying to avoid a duplicate authorization.
Authorize.Net tokenization and AVS
Authorize.Net Accept.js sends payment details from the browser to Authorize.Net and returns a one-time nonce. The server uses it in createTransactionRequest instead of receiving the card number. Accept Hosted provides a hosted form for lower PCI scope with a redirect or embedded experience. Both fit a headless checkout without moving raw card data through the storefront backend.
Keep the nonce short-lived and remove card fields before application submission. Send the billing address for Address Verification Service when needed, or use the hosted form’s postal code. The postal code in the transaction request takes precedence over the nonce value. Capture AVS and define a review policy. AVS is a signal, not a replacement for 3DS or velocity controls.
3DS and SCA patterns mapped to platforms
3DS authentication is a possible branch, not an error. In WooCommerce, the gateway should return challenge or redirect instructions through checkout and bring the customer back to the same payment attempt. Shopify hosted checkout handles 3DS for supported methods and gateways, so test the exact configuration instead of adding a second challenge layer.
For BigCommerce, keep the payment token and checkout context while the Payments API or gateway completes authentication. Set final order status from the post-authentication result. For Authorize.Net, use supported 3DS or a provider that returns authentication outcome with tokenized data.
SCA applies to many European card payments, but exemptions are not guaranteed. Support frictionless and challenge outcomes, preserve return URLs, and log authentication, liability shift, and gateway IDs. Never fulfill from a success URL alone. Distinguish a failed, abandoned, or timed-out challenge from a decline.
Webhook reconciliation checklist
Use a durable payment-attempt record and reconcile it with these checks:
- Verify the signature before parsing each gateway or platform webhook.
- Deduplicate by the provider event or delivery ID.
- Compare order ID, cart or checkout ID, currency, amount, and customer reference.
- Record authorization, capture, void, refund, chargeback, and dispute transitions separately.
- Make fulfillment depend on a verified captured or otherwise approved state.
- Retry transient failures with a bounded queue and exponential backoff.
- Run a scheduled poll for payments created locally without a matching webhook.
- Alert on mismatched totals, duplicate captures, stale pending payments, and missing events.
Practical checklist for a stable launch
Start with one platform, one gateway, one currency, and a small 3DS test set. Use hosted fields or checkout so raw PAN data never reaches the application. Generate an idempotency key per payment attempt, keep secrets and private tokens on the server, and redact payment data from logs.
Before launch, test approved, declined, duplicate, timeout, refund, chargeback, and abandoned challenge paths. Confirm refresh cannot create a second order. Verify webhook signatures with the raw body, replay a delivery safely, and test recovery after a gateway approval with a browser network error. Document review release ownership and how support traces cart ID to gateway transaction ID.