Understand Orderboost button flows
Follow each Orderboost launcher from configuration and browser press through authentication, hosted checkout, cart continuation, tipping, or paid-resource unlock.
A Orderboost button expresses one intent. The initialScreen and displayMode settings are related, not freely interchangeable. Choose a supported surface for the intent; neither setting changes who owns prices, checkout state, authentication, or payment.
Map intent to supported behavior
Orderboost derives launcher copy from the flow. Configure size (xs, sm, md, or lg), radius, variant, icon treatment, and color through the public widget configuration. Set initialScreen, and OrderboostWidget renders the corresponding label. Sign-in is intentionally compact: its default or requested md size resolves to the xs 32px treatment, while commerce launchers retain the standard md size.
| Intent | initialScreen |
Launcher label | Supported surface |
|---|---|---|---|
| Account | sign-in |
Sign In | Local modal or page, then account popup |
| Immediate purchase | buy-now |
Buy Now | Hosted popup/page or local callback surface |
| Current cart | cart |
Cart | Local floating, modal, or page surface |
| Contribution | send-tip |
Tip Now | Hosted popup/page or local callback surface |
| Paid resource | payment-gate |
Pay $0.05 Now (example) | Full-page guard with host callback |
Add to Cart is not a Orderboost checkout launcher. It changes store-owned cart state. The separate Cart launcher reads that state and continues it into checkout.
Route intent to a surface
The runtime resolves intent first, then uses only the compatible delivery path:
Do not configure a standalone Sign In button with displayMode: "popup". That mode selects hosted checkout and requires checkout presentation plus a commerceSession. Sign In starts from a local launcher and opens the separate account popup.
Use a server-backed commerceSession for hosted Buy Now or Tip. Hosted full-page mode also requires commerceSession.checkoutUrl; without it, displayMode: "page" renders the local page surface. Cart remains local until onCheckoutContinue, and Page Guard remains a local full-page callback surface.
Follow sign-in end to end
Sign-in uses the account popup, not the checkout popup. The merchant backend exchanges the returned authorization code and creates its own HTTP-only application session.
The browser result is not the merchant session. Exchange it on the backend, keep tokens out of browser storage, and update signedIn only after that exchange succeeds.
Follow hosted checkout end to end
Buy Now and Tip use the same hosted-session protocol. A tip changes checkout presentation and fulfillment needs, not the security boundary.
Pre-open a popup synchronously inside the button press, before awaiting checkout creation. This avoids browser popup blocking. While a named popup remains open, the launcher changes to Press to find window and focuses that window instead of opening a duplicate.
For full-page delivery, Orderboost prepares the same durable link in the background and navigates the current tab after the press. The hosted document uses a fragment secret so the capability does not enter HTTP request logs or referrers.
A stable Buy Now permalink contains only a canonical product URL and quantity, so it can be published or unfurled without disclosing a bearer secret. Its GET renders product-specific metadata without creating checkout state. The buyer’s browser then POSTs that intent and receives a hosted checkout URL. That fragment-secret URL is also reusable when the merchant intentionally shares it: the first buyer claims the seed checkout and later buyers receive newly quoted, isolated checkout sessions from the same immutable item template.
Continue a host-owned cart
Orderboost does not duplicate the store cart. The host maps current lines into Orderboost presentation data and remains responsible for quantity changes until checkout continuation.
The hosted checkout revalidates every item, price, and availability result. Cart totals displayed before continuation are informative; the newly created checkout is authoritative.
Unlock a paid page
Page Guard is an implemented user interface and callback boundary. It does not include an MPP or x402 wallet, signer, verifier, facilitator, or paid endpoint.
Configure Page Guard with initialScreen: "payment-gate" and paymentGate.protocol set to mpp or x402. Do not use the legacy x402 configuration or x402-gate screen for new integrations.
Keep these boundaries intact
- Browser checkout does not use MCP OAuth, a handoff code, or an agent purchase grant.
- Account sign-in and checkout open separate hosted documents with separate capabilities.
- Page Guard does not perform a paid HTTP handshake unless the host callback supplies one.
- Page Guard is the only browser flow that may connect and pay with an anonymous wallet. Checkout crypto/wallet methods and direct transaction approval require a server-backed Orderboost session.
- MPP and x402 never appear beside Card or Crypto in buyer checkout.
- Prices and order completion remain server-authoritative in every presentation mode.
Build each flow in Integrate Orderboost checkout in React. Compare browser and agent ownership in Compare checkout paths.