Understand agentic checkout

Understand how hosted checkout, MCP tools, buyer approval, Tempo MPP, and x402 divide commerce control and payment authority.

Agentic checkout has two decisions: how the agent controls commerce and who completes payment. Orderboost owns catalog, checkout, and order state. Model Context Protocol (MCP) exposes that state as tools. Machine Payments Protocol (MPP) can also pay the exact hosted checkout URL after Orderboost collects its required buyer information.

Current implementation

Orderboost ships hosted buyer checkout, a Tempo MPP verifier and completion endpoint for that hosted URL, and MCP checkout with exact approval. The agent supplies its Tempo wallet and spending policy. Orderboost does not ship built-in x402 checkout settlement. Page Guard supplies a separate host callback for protected resources.

Assign one job to each public surface

Orderboost keeps commerce state separate from tool transport and payment authority:

The validation gate evaluates Orderboost approval and the selected payment path together. A payment credential or settled payment can’t bypass a required purchase grant.

Orderboost returns money as integer minor units. For example, USD 15.00 is 1500. Treat the Orderboost response as authoritative instead of calculating totals in the agent.

Choose the shortest valid path

Use hosted checkout unless the integration needs direct checkout control:

Hosted checkout avoids agent OAuth and caller-managed purchase grants. A human can pay on the page, or a Tempo wallet can use the MPP endpoint carried by the checkout response.

Open hosted checkout from a product URL

The Node SDK resolves the selected variant, opens hosted buyer checkout, and polls a read-only status capability until an order exists:

import { purchaseWithAgent } from "@orderboost/sdk/agent/node";

const productUrl = "https://merchant.example/products/arc?Color=Gray";
const { orderId } = await purchaseWithAgent(productUrl, {
	apiBaseUrl: "https://api.orderboost.example",
	quantity: 1,
	selected: [{ label: "Gray", name: "Color" }],
});

The hosted page collects buyer details and payment. The SDK returns the final order identifier. It doesn’t expose a checkout mutation capability or purchase grant to the caller.

Complete checkout through MCP

An advanced agent uses Orderboost’s MCP tools for catalog lookup, checkout creation, approval, and completion:

OAuth permits protected checkout operations. It doesn’t permit payment. The purchase grant binds the approved merchant, checkout revision, quote, amount, currency, OAuth client, approver, expiration, and tokenized payment reference.

Fetch current state after each mutation or approval. Any mutable change invalidates the earlier purchase grant. Reuse one idempotency key only when retrying the same completion.

Pay the hosted checkout URL with Tempo MPP

When buyer-checkout creation returns mpp.endpoint, first post only the exact checkoutUrl. Orderboost returns 422 with missing qualification paths before it can request payment. Resend the required customer, fulfillment, and billing address fields with one stable Idempotency-Key. Orderboost requotes and locks the checkout, then returns the live MPP challenge.

The caller cannot choose amount, token, chain, recipient, checkout ID, quote hash, or purchase grant. The challenge is derived from the current checkout and merchant Tempo wallet. A conforming client validates the live terms, authorizes the charge, and retries the identical request.

Require Payment-Receipt, checkout.status: completed, and orderId before reporting success. Follow Pay a hosted checkout with Tempo MPP for the complete Tempo client flow.

Call other paid resources only when advertised

MPP and x402 can also protect pages or APIs. For those resources, use only the endpoint and schema declared by live resource documentation. Orderboost’s built-in MPP checkout route does not imply x402 support and does not authorize a different merchant endpoint.

Recover without paying twice

Reconcile Orderboost checkout and order state after an ambiguous timeout:

• Treat a changed or expired payment requirement as a new policy decision
• Retry a mutation only with its original idempotency key
• Never forward payment credentials across an untrusted redirect
• Never let payment settlement bypass required human approval
• Require a completed Orderboost order before reporting checkout success

Read the MPP HTTP transport and x402 HTTP 402 documentation for protocol-specific behavior.