Checkout — WordPress.com Purchase Flow

Customer-facing checkout UI. Related billing areas: client/me/purchases/ (Classic), client/dashboard/me/billing-purchases/ (Dashboard).

Project Knowledge

Directory Structure

client/my-sites/checkout/
├── src/
│   ├── components/
│   │   ├── checkout-main.tsx           # Top-level orchestrator
│   │   ├── item-variation-picker/     # Billing cycle selector (name misleads — not "variants")
│   │   └── wp-contact-form/           # Contact form (varies by product type — see Checkout Steps)
│   ├── payment-methods/               # One UI component per processor
│   ├── hooks/use-create-payment-methods/  # Generates PaymentMethod[] from cart + server config
│   └── lib/
│       ├── wpcom-store.ts               # @wordpress/data store (not Redux — checkout-specific state)
│       ├── leave-checkout.ts            # navigate() trap — see pitfall #6
│       └── *-processor.ts              # One per payment method (13 files)
├── get-thank-you-page-url/          # 800+ lines, exhaustive tests — see pitfall #5
└── checkout-thank-you/              # Post-purchase pages (8+ variants)

Checkout Steps

Three hard-coded steps (not extensible without changes here):

1. Review Order
2. Contact Details — Form varies by cart contents:
   • No domains → billing address only
   • Domain registration → full ICANN contact details
   • Google Workspace → company name + billing address
   • Contact type determined by getContactDetailsType(responseCart) from wpcom-checkout
3. Payment Method

The sidebar/summary view is NOT a step — visibility is manually managed via isSummaryVisible state to prevent it from blocking form submission.

Checkout State

• Redux — global state (site, user, notices)
• @wordpress/data store (wpcom-store.ts) — checkout-specific: contact details, VAT, domain validation results, form touched fields
• useFormStatus() from composite-checkout — LOADING, READY, SUBMITTING
• useTransactionStatus() — NOT_STARTED, PENDING, COMPLETE, REDIRECTING, ERROR

Payment Processing

Processors must handle four response paths: immediate success, redirect (PayPal/WeChat), 3DS challenge (Stripe), and polling (PIX). Not all paths apply to all processors.

Package Boundaries

Architectural Decisions

1. Thank-you URL generated before transaction — For redirect payment methods (PayPal, Bancontact), the thank-you URL is generated and passed to the processor BEFORE the transaction starts. Uses :receiptId placeholder, replaced by /me/transactions endpoint on return.

2. Contact validation is two-step — Form validation (required fields, format) then async domain registration validation (WPCOM backend). Both must pass.

Adding a Payment Method

Seven touchpoints required (follow an existing implementation like Razorpay):

1. Payment method component — src/payment-methods/{name}.tsx, export create{Name}PaymentMethod() returning a PaymentMethod object ({ id, paymentProcessorId, label, activeContent, submitButton })
2. Processor function — src/lib/{name}-processor.ts, signature: async (submitData, options, translate) => PaymentProcessorResponse
3. Register processor — Add to processor map in src/components/checkout-main.tsx
4. Create hook — src/hooks/use-create-payment-methods/use-create-{name}.ts, optionally gate with isEnabled('checkout/{name}') for gradual rollout
5. Register hook — Call in use-create-payment-methods/index.tsx, add result to paymentMethods array
6. Slug mapping — Add bidirectional mapping in packages/wpcom-checkout/src/translate-payment-method-names.ts (e.g., 'pix' ↔ 'WPCOM_Billing_Ebanx_Redirect_Brazil_Pix')
7. Feature flag — (Optional) Add to config/{environment}.json for gradual rollout; remove once fully enabled

Steps 6-7 are the ones agents miss — without slug mapping the method never appears.

Common Pitfalls

1. Checkout links MUST include redirect_to and cancel_to params — Missing these causes broken back/cancel navigation.

2. Cart key matters — Wrong cart key = wrong cart. 'no-site' vs site ID vs undefined have different behaviors. See packages/shopping-cart/README.md.

3. Checkout URL format — Products use slugs, domain meta uses colon separator. Example: /checkout/example.com/personal,domain_reg:example.com. Don't construct URLs manually — use existing helpers.

4. Payment method filtering — Not all methods are available everywhere. filterAppropriatePaymentMethods() in packages/wpcom-checkout/src/ handles country/currency/product filtering. Don't bypass this or hardcode availability.

5. Thank-you page routing is 800+ lines with 20+ branches — Routing logic is in get-thank-you-page-url/index.ts with exhaustive unit tests. The code explicitly warns: "IF YOU CHANGE THIS FUNCTION ALSO CHANGE THE TESTS." Don't add new thank-you routes without updating both.

6. navigate() silently fails for /setup/ routes — navigate() uses page.show() which doesn't work for Stepper routes. Use window.location.href for cross-origin or setup redirects. See src/lib/leave-checkout.ts.

7. 3DS challenges not guaranteed — Stripe 3D Secure may or may not trigger. Processors must handle both paths (direct success and challenge flow).

8. Gift purchases bypass everything — Check cart.is_gift_purchase first. Gift purchases skip all upsell logic and route to a separate thank-you page.

9. Atomic sites use .wpcomstaging.com — Thank-you URL logic replaces .wordpress.com with .wpcomstaging.com for Atomic sites.

10. Siteless purchases — Some products (Akismet, Jetpack, Marketplace) use temporary sites (siteless.{jetpack|akismet|marketplace.wp|a4a}.com). Guard with purchase.isAttachedToHoldingSite. Never query site data for these.

11. Transferred purchases — Always check ownership before allowing purchase actions.