PCI DSS Headless eCommerce & Secure Checkout

Transactional Security: PCI DSS Headless eCommerce Architecture

Executive Summary

This is how ERPStack builds headless eCommerce platforms whose PCI DSS scope is deliberately small. Online retail faces 2 pressures at once: card fraud and conversion loss from slow pages. The architecture answers both by decoupling the storefront from the payment network — a pre-rendered Next.js catalog served from the edge on Vercel, and a checkout that hands cardholder data straight to the gateway without it ever touching your infrastructure or your PostgreSQL database. The current standard is PCI DSS v4.0.1.

Payment Flow and Cardholder Data Isolation

Storefront decoupling. Product and category pages are pre-rendered by React Server Components and served from edge cache, so the browser begins painting before any PostgreSQL query runs. Only cart and secure checkout routes reach the database, and those are small indexed queries. Raw card data never touches the Next.js web tier at all.

Client-side tokenisation. Checkout renders the processor's own fields — Stripe Elements or the Adyen SDK — inside an isolated iframe. The primary account number goes from the shopper's browser directly to the gateway; the storefront receives a token, the card brand, and the last 4 digits.

Ledger security. The transactional ledger stores payment status, gateway token, and card indicators only, encrypted at rest with AES-256 and defined with Drizzle ORM. UPDATE and DELETE are revoked on the ledger for every PostgreSQL role, so order history is append-only by construction — an Immutable Audit Trail rather than a log file.

Inventory integrity. Stock synchronises both ways with your ERP or third-party logistics provider over webhooks carrying idempotency keys, so a retried delivery cannot double-decrement inventory. Checkout reserves stock at authorisation and releases it on timeout, which is what actually prevents overselling in a flash sale.

Ingress Verification at the Edge

// Edge ingress guard on Vercel: origin validation, rate limiting,
// payload sanitisation. Card-testing traffic is blocked before the gateway.
import { NextRequest, NextResponse } from 'next/server';

export async function verifyCheckoutIngress(req: NextRequest) {
  const origin = req.headers.get('origin') ?? '';
  if (!ALLOWED_ORIGINS.has(origin)) {
    return NextResponse.json({ error: 'Blocked ingress' }, { status: 403 });
  }
  const verdict = await rateLimit(req); // per-IP and per-card-fingerprint
  return verdict.allowed ? NextResponse.next() : NextResponse.json({ error: 'Rate limited' }, { status: 429 });
}

RBAC restricts transaction detail to finance roles, and Zod validates every checkout payload at the API boundary before it reaches business logic.

The Commercial Arithmetic

A platform commission of 2% on 2 million dollars of annual turnover is 40,000 dollars a year — roughly the cost of building a custom storefront outright. Below that volume a hosted platform is usually the rational choice; above it, the commission is financing someone else's roadmap. ERPStack charges a fixed build fee and takes no percentage of revenue, so the only recurring costs are your payment processor's per-transaction rate and hosting, typically under 500 dollars a month on serverless infrastructure.

Operational Outcomes

Systems that never see a PAN fall outside most of PCI DSS v4.0.1, which is what shrinks the assessment. Sub-100ms catalog responses, because the expensive rendering happened at build time rather than per request. And margin that stays with the merchant instead of scaling with someone else's fee schedule.

Stack and Boundaries

The storefront runs on Next.js and TypeScript with PostgreSQL behind Drizzle ORM, served from the Vercel edge and described in Terraform for your own AWS account. RBAC is enforced in the Next.js API layer, Redis holds session and cart state but 0 card data, and Zod validates 100% of API boundaries. Semgrep SAST, Vitest, and Playwright run in GitHub Actions on every commit, with Sentry for error telemetry. ERPStack operates 0 of it: after handover no ERPStack account reaches your PostgreSQL cluster or your Vercel and AWS keys.