Keep your existing store and add hosted payment sessions, with server-owned pricing, explicit agent access, verified orders, and recoverable fulfillment.
You can add AI agent-ready checkout to an existing website by placing a payment adapter between your store's order backend and a hosted payment session. Keep the catalog, cart rules, inventory, tax calculation, and fulfillment process. Let the hosted service handle payment interaction, then have your backend verify the resulting payment against the store order before releasing goods or access.
This works when your store provides the extension points needed to create a pending order and mark it paid from trusted backend evidence. It does not mean pasting in a payment button makes every AI agent a supported buyer. Agents also need an explicit route to request a purchase, understand its terms, and pay with authorized funds.
The useful boundary is narrow: replace the payment interaction you do not want to build, without replacing the business system that decides what the customer bought.
Keep the store in charge of the purchase
Start with what remains yours. Your existing store should still decide which product or variant is available, what quantity can be sold, whether a discount applies, where the order can ship, and what the final total is. A hosted session receives a purchase your backend has already priced; it should not become an alternate catalog that silently disagrees with the store.
For an existing checkout, the new work usually has three integration points: a backend operation that creates the payment session, a browser or agent entry that receives the payment handoff, and a backend payment-verification operation that feeds the existing fulfillment workflow. Those are architectural responsibilities, not a claim that every store platform exposes an identical API.
If you control the application backend, those operations can live in a small adapter module. If the site is mostly static, an authenticated serverless service can hold merchant credentials and communicate with the order system. It still needs access to authoritative pricing and a way to record payment. A serverless function that merely forwards whatever total the browser supplies does not establish that authority.
A closed commerce platform may require a supported payment extension, app, or order-management integration. Check that boundary before promising an additive checkout. If the platform cannot accept an externally verified payment or preserve an external session reference, you may need more integration work than the website itself suggests. A payment link cannot bypass those restrictions responsibly.
Keep the existing payment lane available during rollout. An agent-assisted buyer may still prefer a human card checkout, and a wallet user may lack the token or native gas needed for the new lane. Offering another payment method is different from forcing a migration.
Both lanes must converge on the same store purchase. If the buyer opens a card flow and a crypto flow for one cart, your backend should prevent the order from being fulfilled twice and detect a second payment for operational review. That guard belongs in your order system; two independent hosted pages will not necessarily know that they represent the same purchase.
Create the payment session from a frozen store quote
The session-creation request should begin with product identifiers and customer context, not a buyer-supplied payable total. Your backend authenticates the request, loads current product data, validates quantity and inventory, applies eligible discounts, and calculates any shipping and tax required for that order. It then stores a purchase snapshot with the total it is prepared to honor.
Consider an illustrative store selling a digital asset pack. The cart total is 24.50 after an eligible discount. Record the pack version, customer entitlement destination, price version, total, and quote expiry before creating the session. An agent sending a different amount must not change the entitlement or price. For physical goods, the same snapshot also needs the selected shipping service and validated delivery details; payment cannot repair an incomplete shipping quote.
GOAT Flow's dynamic DIRECT checkout uses a merchant-authenticated POST /api/v1/checkout/sessions request. The merchant comes from the API key. The server SDK exposes createCheckoutSession(...) and returns a checkout ID, URL, type, and expiry. Merchant credentials stay on your backend; the payer does not need them.
The following TypeScript sketch uses the documented server interface. It is illustrative, not a complete HTTP handler or an executed integration. Check your installed package's exports and target service contract; a repository example does not establish release publication. The sketch assumes the store has already authenticated the buyer, persisted the quote, and validated every outgoing value against the active deployment's signing-input policy.
In a real adapter, the price and reference come from the persisted quote rather than constants. Save the returned session ID and expiry against that purchase before returning the payment handoff. Use a stable purchase reference when retrying creation, but do not assume a reference alone supplies your database's uniqueness or concurrency guarantees. Confirm the deployment's reuse behavior and serialize conflicting attempts in your own backend.
There is a material authentication constraint to resolve before deployment. The current Flow API reference documents a legacy HMAC signing format that joins scalar values with & and =; it is not unambiguous for arbitrary values containing those delimiters. The active deployment must enforce a consistent allowed-value policy before authentication and request handling. Using the SDK handles expected serialization, but does not itself fix that protocol constraint. Do not forward unrestricted product names, metadata, or redirect parameters into signed requests.
Keep personal information out of public session metadata and display items. Flow excludes privateMetadata from the public session view, but that is not a reason to copy your entire customer record into it. Retain delivery and identity data in the store wherever practical, and send only the references needed for correlation.
Let the hosted page handle payment, not fulfillment
After session creation, your browser opens the opaque checkout ID or follows the returned URL. GOAT Flow Hosted Checkout is a top-level page, opened as a popup, tab, or redirect; it is not an iframe to embed inside your store layout. Treat the checkout handle as a bearer capability and avoid leaking it into analytics events, support transcripts, or broadly accessible logs.
For an asynchronous session request, a redirect is often easier to manage than a popup. Browsers commonly block a window opened only after an awaited network request. If you use a tab, open it synchronously from the buyer's click and navigate it after the session response. If a popup's opener connection fails, avoid leaving two active payment windows while starting a replacement handoff.
The hosted service reads the session terms, connects the buyer's wallet, and offers eligible payment choices. In the documented DIRECT lifecycle, choosing a token and binding the session creates the actual payment order. The session therefore exists before that order: your store purchase ID, hosted checkout ID, and bound payment order ID are distinct identifiers, even when they all describe one intended purchase.
The public DIRECT payment moves an ERC-20 token from the payer's wallet to the merchant's configured receiving address. It is not an escrow deposit followed by a merchant payout. You do not need to deploy an optional merchant callback contract merely to use this public checkout path. Accepted assets, receiving addresses, service fees, and limits depend on the merchant and active environment, not on every token or contract example present in the repository.
Keep the session and order state models separate. Hosted-session states describe whether the session is open, bound, completed, expired, or cancelled. The linked order has its own payment statuses. A front-end state transition can update the page without becoming your store's paid transition.
In particular, onSuccess, a success redirect, or a message from the checkout window must not trigger shipment or entitlement issuance. Show a payment-checking state while the store backend verifies payment. If the browser closes immediately after a successful transfer, the backend should still finish reconciliation without waiting for that browser to return.
Hosting removes wallet connection, transfer UI, and much of the payment-status presentation from your application. In return, the buyer crosses an external page boundary and depends on that service's availability. Your store still needs a useful pending-order page and an operational path for payments whose confirmation outlives the browser interaction.
Give agents an explicit path, not just a payment button
A hosted browser checkout and a machine-payable purchase are different interfaces. A shopping agent can request a server-priced purchase and hand the user its checkout URL. That is a valid assisted flow, but the user may still need to connect a wallet and authorize the payment. Describe it as assisted checkout rather than claiming unattended payment.
For headless payment, identify the exact client and supported purchase surface. GOAT Flow's public QuickPay discovery surface publishes merchant payment information and fixed-price products. Its PayKit library documents a fixed-product payment path driven by a trusted merchant link and manifest. That is useful for a merchant-configured item; it does not establish that the same command can consume an arbitrary dynamic-cart checkout ID from your store.
There is also a correlation boundary: the documented PayKit fixed-product client does not currently expose a clientReferenceId option. A store integration that needs customer-specific entitlements, shipping, discounts, or cart reservations must explicitly solve how the agent's purchase maps to those business records. Do not assume a publicly discoverable product key carries that context.
For dynamic carts, you can design an authenticated merchant purchase tool that uses the existing cart rules and returns a payment handoff. Unattended payment additionally requires a verified machine-client adapter for the returned terms and a supported way to recover payment status. Until that adapter is established for your deployment, use a human handoff instead of pretending the hosted UI is a headless API.
Protocol labels do not remove this work. Generic x402 specifies payment message types and scheme/network logic, with transport bindings layered around them. An HTTP 402 response alone does not prove a client and service agree on the protocol version, schema, payment scheme, network, or verification behavior. Check those exact contracts before advertising generic x402 compatibility; the core specification also leaves client budget management and session handling outside its scope.
Machine Payments Protocol, or MPP, is another independent protocol. GOAT Flow's current MPP profile uses dedicated JSON challenge and verification endpoints and a profile-specific signed receipt for paid resources. It is not the generic MPP protected-resource Challenge/Credential retry exchange. A receipt-protected API route is also not the same job as buying a physical cart through a hosted session. Do not add that profile to the integration simply because both involve machine payments.
AgentKit belongs on the action/runtime side. Its documented policy engine gates network access, action support, write permissions, and risk-level confirmation; it does not replace the merchant's order adapter. Those gates should not be described as a complete shopping budget. Enforce per-purchase limits, aggregate spending limits, permitted recipients, and allowed assets in the payer's trusted execution or wallet layer, before a transfer is submitted. Product descriptions and model prompts are not the enforcement location.
The decision is therefore concrete: offer a hosted handoff for assisted purchases, a verified fixed-product route where it fits, or a separately validated machine adapter for dynamic carts. Name the supported client path rather than promising that all agents can pay.
Verify the bound order on the trusted backend
Your fulfillment trigger should accept a purchase reference and resolve its payment evidence through a trusted backend source. For Flow, that can be an authenticated order-status read or an authenticated webhook whose contract has been confirmed for the deployment. Do not invent a universal webhook event name, signing header, payload shape, or retry schedule from a browser SDK example.
If the webhook contract is unavailable or incomplete, implement backend status reconciliation rather than treating an unsigned inbound notification as authoritative. Such a notification can prompt a trusted read without being accepted as proof itself. Your adapter also needs a trusted way to obtain and persist the checkout-session-to-order relationship; do not substitute an arbitrary order ID sent by the payer. Confirm that correlation path with the deployed API or webhook contract before automating delivery.
The backend then compares the payment record with the frozen store purchase. It must establish the expected order and merchant, chain, token contract, amount in atomic units, and successful payment status. Verify the configured recipient through trusted payment terms or the relevant on-chain transfer evidence where required. A familiar token symbol or a transaction hash supplied in a browser request is not enough.
For the illustrative 24.50 purchase, suppose the selected deployment-enabled token has six decimals and the bound quote requires 24.50 units of that token. The expected atomic amount is 24,500,000. That calculation assumes those exact quoted terms; it is not an assertion that every accepted token has six decimals or that a dollar-priced cart automatically converts one-to-one into any token. Check the returned denomination and token contract before payment and again when matching its evidence.
Flow's server order waiters treat PAYMENT_CONFIRMED and INVOICED as successful terminal states. A DIRECT order can reach INVOICED before polling observes the earlier confirmation state. Do not leave a matching paid order stuck because your integration recognizes only one of those documented success values. Conversely, do not treat an unknown status, session binding, or failed status lookup as payment confirmation.
After successful verification, use an atomic store transition to record payment once and schedule fulfillment. A database uniqueness constraint on the fulfillment entitlement or purchase, together with a transactional outbox or equivalent durable queue, is one implementation design. It protects against two workers processing the same event concurrently and against a crash after payment recording but before delivery scheduling. These are merchant-side controls, not guarantees supplied by the hosted page.
Keep payment evidence and delivery evidence separate. The historical getOrderProof response includes a field named signature, but the API reference identifies it as a recomputable Keccak256 digest, not a cryptographic signature or attestation. It does not cover the payload's status. It is neither a signed payment receipt nor proof that a customer received goods. When independent payment verification is required, inspect the relevant on-chain transaction and transfer details; record your own entitlement issuance or shipment evidence for delivery.
The return page can ask your backend for the store's current purchase status. That makes it useful without giving it authority to mark the order paid.
Recover the purchase without creating a second payment
The most dangerous failure is an ambiguous one. Suppose the asset-pack buyer submits a transfer, the wallet returns a transaction hash, and the status request times out. The customer sees no confirmation. Creating a new session and immediately paying it again can turn a status-service problem into two transfers for one entitlement.
Preserve the original purchase, session, bound order, and known transaction hash. Resume status reads for the same intent with bounded backoff. If the wallet replaced the transaction, reconcile the original and replacement evidence instead of assuming a local exception means no funds moved. A timeout is a reason to investigate the existing payment, not a reason to authorize another one.
The documented PayKit reuse behavior follows that distinction: reused sessions are resumed or polled rather than automatically paid again. Apply the same principle in your merchant adapter, while checking the exact retry behavior of the client you actually deploy. Do not transplant a fixed-product client's flags or status model into a different session interface without verification.
Expiry also needs an explicit policy. A quote timer can stop new purchases at an old price, but it cannot reverse a transfer already broadcast. If an expiring session has a known transaction, keep it in reconciliation until the backend can determine the outcome. A local expiry message alone should not cause the store to discard payment evidence or tell the buyer to pay again.
For limited inventory, align the reservation deadline with the payment window and define what happens if payment confirms after stock has been released. You may need to honor the reserved purchase, offer a substitute with consent, or arrange a refund. Those are merchant business decisions. DIRECT has no escrow release for you to cancel, and a refund is a separate operational transfer requiring authorization and reconciliation.
Delivery failure is another branch. If the 24.50 payment is verified but entitlement issuance fails, keep the purchase paid and retry the delivery operation using the same fulfillment key. Do not send the buyer back through checkout. A support view should distinguish payment pending, payment matched, delivery pending, and delivery complete so staff do not solve the wrong problem.
Duplicate webhook deliveries and repeated browser returns should converge on that same state, not create more fulfillment jobs. If an event conflicts with a later trusted order read, investigate rather than blindly applying events in arrival order. Preserve enough non-secret correlation data for an operator to follow the purchase across systems.
This recovery design sacrifices an immediate binary answer during ambiguous failures. The benefit is avoiding unnecessary second payments and lost paid orders. Give the buyer an order reference and a pending-status page, and assign ownership for reconciliation that exceeds the automated retry window.
Pilot one payment lane before expanding it
Begin with one product or a controlled cart cohort whose fulfillment rules are already understood. Confirm the target merchant is configured for DIRECT checkout and the required hosted capability. Verify the installed SDK release, service origins, enabled chain/token pairs, receiving addresses, decimals, limits, fees, and redirect allowlist in that environment. Repository examples and candidate package versions are not deployment evidence.
Before automatic delivery, test the payment-entry boundaries: a tampered browser total, a wrong token or chain, a mismatched order ID, a rejected wallet request, insufficient gas, and a blocked popup. Then test recovery after a closed browser, duplicate notifications, a late confirmation, and a failed fulfillment worker. Also validate the signing-input policy and authenticated webhook contract, or the backend polling alternative. These are acceptance tests to perform, not results reported here.
Test the agent path separately from the human path. An agent producing a checkout URL proves assisted handoff, not unattended transfer. A successful fixed-product payment does not prove a dynamic cart retains customer identity or shipping context. Decide which path you can support operationally and describe only that capability.
Keep a rollback that disables new hosted-session creation while reconciliation continues for sessions already issued. Removing the button must not strand customers who have paid. Retain the existing checkout for unsupported wallets, unavailable assets, and buyers who need a different payment method.
Hosted sessions are a poor shortcut when your platform cannot reconcile external payments, your buyer base needs only conventional recurring billing, or the purchase requires dispute or escrow protections this DIRECT flow does not supply. For a compatible store, the pilot is ready to expand when a purchase stays traceable from frozen quote through matched payment and recoverable delivery, even after the browser disappears.
