The walkthrough › Chapter 8 — Integration Guide
CHAPTER 8 of 11

Integration Guide

Step-by-step: add x402 paywalls and multi-rail payments to an existing content site that simply serves pages.
[   ]

Coming Soon

Chapters 1–7 prove each capability in isolation. Chapter 9 surveys the agentic commerce protocol landscape. This chapter is the bridge between them — the practical walkthrough that turns the demos into a working integration on your own site.

PLANNED

What This Chapter Will Cover

An end-to-end walkthrough for a publisher who already runs a content site (static HTML, Node.js, .NET, WordPress, or other CMS) and wants to add x402 paywalls plus multi-rail payment options without rewriting their stack.

Section 1 — The Starting Point

An honest baseline: a publisher with a content site, no payment integration, no crypto knowledge. What they have, what they don't, what they're worried about. Sets up the journey realistically.

Section 2 — Choose Your Path (the Configurator)

Walk through the Gateway Configurator wizard to answer five questions about platform, what you're selling, payment methods, audience, and scale. Out the other side: a recommended config and integration checklist tailored to the publisher's setup.

Section 3 — Stand Up the Gateway

  1. Provision the gateway (cloud or on-prem)
  2. Configure the wallet address that receives payments
  3. Define paywall rules in appsettings.json (per-path pricing, asset, network)
  4. Configure payment processors if using fiat rails (Stripe, Braintree)
  5. Test the gateway end-to-end on devnet before going live

Section 4 — Wire Your Site

  1. Choose your integration mode: reverse proxy (no code changes), middleware (drop-in NPM/NuGet package), or client-side overlay (script tag)
  2. Point your premium content paths at the gateway
  3. Add the JS client for browser-side payment UX
  4. Configure access cookies, expiration, and re-payment flows

Section 5 — Test on Devnet

  1. Run the test wallet through the full payment flow
  2. Verify on-chain that the transaction hit the right wallet
  3. Confirm the access cookie was set and content unlocks
  4. Test edge cases: failed payment, expired cookie, paywall bypass attempts

Section 6 — Go Live

  1. Switch the network configuration from devnet to the production network
  2. Update the wallet address to the production receiving wallet
  3. Configure real payment processor keys (Stripe live, etc.)
  4. Apple Pay domain verification (if applicable)
  5. Monitor first transactions, verify settlement

Section 7 — Operate

Day-2 operations: monitoring, A/B testing paywall pricing, updating paywall rules without redeploying, handling refunds, reading the seller dashboard.

Section 8 — Common Pitfalls

Distilled lessons from real publisher integrations: wallet UX gotchas, mobile considerations, fiat-vs-crypto routing decisions, and the pre-flight checks that prevent payments from getting stuck.

Why This Chapter Matters

Every demo asks "okay but how do I actually use this?" — this chapter answers that question with a real walkthrough, not a sales pitch. The configurator wizard generates the recommendation; this chapter walks the actual integration. By the end, a publisher should have a clear map from their current state to a live, paywalled site running on the x402 gateway.

Available Now

While Chapter 8 is being written, the building blocks already exist:

← Chapter 7: QR Pay The walkthrough ↑ Chapter 9: Agentic Commerce →