Apple Pay on Optimizely Commerce: A Solutions Architect's View

A three-part series

This is the first of three posts on implementing Apple Pay on Optimizely Commerce. Part 2 covers the developer implementation guide, and Part 3 covers the QA/testing guide.

Architecture at a glance

• Customer’s browser – Apple Pay JS, payment sheet UI
• Storefront checkout – Optimizely Commerce
• Merchant validation API ↔ Apple Pay servers – mutual TLS session validation
• Payment gateway – existing PSP, charges token
• Order / commerce pipeline – same flow as every payment method

Legend: gray = your systems, coral = third-party services (Apple Pay servers, payment gateway).

The diagram above is the whole story in one picture. Five stages, two colors: your own systems in gray, third parties in coral. Everything else in this post is justification for why it’s shaped that way.

The one architectural decision that mattered

Apple Pay isn’t a payment method in the conventional sense — it’s a new front door into an order pipeline you already have. The temptation on a project like this is to treat Apple Pay as a parallel checkout path with its own session handling, its own order creation, its own everything. We didn’t do that, and it’s the single decision I’d defend hardest in a design review.

Instead, Apple Pay terminates at the payment gateway boundary exactly like every other payment method already does. The merchant validation handshake — the part that’s genuinely Apple-specific — lives in one isolated component. Once a payment token comes back, it re-enters the same order pipeline that PayPal, Google Pay, and card payments already use. Looking at the diagram: the bottom stage, “Order / commerce pipeline,” doesn’t know or care which stage above it the order came through.

This matters for two reasons:

• Blast radius. A bug in Apple Pay’s merchant validation can’t corrupt an order, because it never touches order logic — it either produces a valid token or it doesn’t. Conversely, an order pipeline bug isn’t payment-method-specific, so it gets caught regardless of which method QA happens to be testing with.
• Future cost. The next payment method (and there’s always a next one) follows the same pattern: isolated client/validation layer in, same token-based handoff out. You’re not accumulating N parallel checkout implementations.

Where the engineering effort actually went

Looking at the diagram, the unglamorous middle stage — the merchant validation API talking to Apple Pay servers over mutual TLS — is where almost all the real effort landed. Everything above and below it (the browser button, the gateway charge, the order pipeline) is comparatively well-trodden ground.

Mutual TLS authentication using a certificate issued to your specific merchant ID is unforgiving: the failure mode is a generic handshake error with no actionable detail from either side. Diagnosing it meant building out certificate-pipeline logging (subject, thumbprint, private key validity, which crypto API actually returns a usable key) before the network call, because once the handshake fails, there’s no further diagnostic surface to lean on. That’s the kind of thing that’s invisible in a project plan (“integrate Apple Pay” — one line) and accounts for a disproportionate share of the actual calendar time.

The practical takeaway for anyone scoping similar work: budget the certificate/TLS handshake as its own line item, separate from “build the button” and “wire up the gateway.” It is not the same size of task as the rest combined.

What “done” actually required

Two things that didn’t show up in the original ticket but turned out to matter:

• UI consistency across payment methods. Icon sizing, label alignment — cosmetic, but on a checkout page, visual inconsistency reads as untrustworthy, and trust is the entire value proposition of adding a payment method in the first place.
• The Terms & Conditions link. Apple Pay and Google Pay’s consent checkboxes were both pointing at a placeholder link, while PayPal’s correctly pulled from CMS-managed content. A payment method isn’t “done” when its own button works — the surrounding consent and compliance affordances need the same scrutiny as the happy path, and they’re easy to miss because the page still looks finished.

Where to go next

Building this yourself? Part 2 has the actual code — certificate reassembly, the TLS handshake checklist, the controller, the .well-known static file gotcha.

Testing this on a project? Part 3 covers how to verify merchant validation, simulate failure states, and the device/browser matrix you actually need (it’s smaller than people assume).