x402 for Agentic E-commerce with Partial/Full Refund + Cancelation, and Returns

Abstract

x402 is an open standard for internet-native payments: a resource server responds 402 Payment Required, the client resubmits with a signed payment payload, and a facilitator verifies and settles it. Its most widely deployed scheme, exact, moves one authorized amount for one resource, once, and by the specification's own account has no built-in mechanism for returning funds. A second scheme, auth-capture, does support a refund, but as a scalar amount on one payment, gated by whichever facilitator or contract holds a capture-authorizer role, inside a fixed time window. Neither scheme, nor any other in the spec, defines a multi-item cart, a stateful checkout session, or an identity bound to the payment distinct from the signing wallet. This paper specifies x402 Direct, three primitives layered on top of x402's settlement leg rather than inside it: a signed checkout session that prices a real multi-line cart before any money moves, an agent-facing initiation route that expresses a partial refund, a damaged-goods return, and a full-order cancellation as one primitive with different inputs, and a non-custodial reverse settlement signed by the merchant's own wallet. The full loop, checkout through cancellation, is proven end to end on Base mainnet against a live commerce backend with real USDC, and every claim resolves to a transaction hash or a signature independently verifiable against a published key. The specification anticipated the need for a reverse leg: an auth-capture scheme was merged on 2026-05-13, and its reference TypeScript package shipped a client on 2026-05-29. That package states, as of this writing, that it "currently ships the client only" and that "server and facilitator support follow in a later change." The loop documented here settles real value on Base mainnet today, on the exact rail, without escrow infrastructure and without any party but the merchant able to sign a refund.

What x402 solves, precisely

The x402 flow is short by design. A client requests a resource; the server returns 402 with the terms it accepts; the client signs a payment payload against one of those terms and resubmits; a facilitator verifies the payload and settles it on-chain; the server serves the resource. Four schemes govern how settlement itself behaves: exact transfers the stated amount immediately. upto transfers up to a client-authorized maximum, settled for actual usage. batch-settlement accepts a commitment now and settles it later, in bulk, through a channel, voucher store, or billing cycle, built for volume where per-request on-chain settlement does not make sense. auth-capture holds funds in escrow or sends them direct, with a capture-authorizer able to void, capture, or refund inside a deadline.

Every one of the four is a payment scheme: it governs how value moves for a single authorized amount. None defines a cart, an authorization spanning more than one priced line. None defines a checkout session, a stateful object that survives across a quote, a line-item selection, and a settlement. None binds an identity to the request beyond the wallet whose signature the scheme verifies. That is not a gap in the engineering; it is the correct scope for a payment protocol, the same way a card network's authorization message is not supposed to know what is in a shopping cart or who is buying, a merchant's own checkout stack sits on top of the rail for that.

Agent commerce needs that stack too, and it needs the identity to mean something specific: a KYA-equivalent credential the merchant's own server can verify, not just recover a wallet address from a signature.

Three primitives, layered on the settlement leg

x402 Direct adds three things above x402's settlement leg. None require a change to the x402 spec; each is a layer a resource server and its client agree to speak before the 402 challenge fires.

• 1. Checkout sessiona stateful object, created and completed under RFC 9421 HTTP Message Signatures, that prices an arbitrary number of line items from a live commerce backend (goods, shipping, and jurisdiction-correct tax) before advertising the one exact-scheme payment requirement the client ultimately signs. The cart is negotiated above x402; the money still moves through it, once, for the summed total.
• 2. Agent-facing refund and cancellation initiationone route, signed the same way the checkout was, that a buyer's agent calls to open a ticket against a specific, already-settled order. An optional line-item selection makes it a partial refund; omitting the selection makes it a full-order cancellation; the reason is a string the agent supplies and the merchant reviews, so the same primitive covers a pre-shipping change of mind and a post-delivery damage claim without a separate code path for either.
• 3. Non-custodial reverse settlementthe merchant's own wallet, the same account that received the original payment, signs the ERC-3009 send-back client-side. The protocol layer verifies the signature, checks it against the order it claims to settle, and relays it through a facilitator. It never holds a key that could sign one.

The technical specification

Every request below is drawn from the real, on-chain-settled run in the validation report below; the shapes are exactly what shipped, not an illustrative simplification.

• Create. POST /ucp/v1/checkout-sessions, RFC 9421 signed. Body: a line-item array (product_id, quantity) and a fulfillment destination. Response: a session id, status ready_for_complete, and a payment_handlers object naming every rail the site has configured, the x402 handler carrying the server-priced pay_to, amount_atomic, network, and EIP-712 domain the client must sign against. The session advertises every rail it has configured and privileges none; a Boson-escrow-only site and an x402-only site both create successfully.
• Complete. POST /ucp/v1/checkout-sessions/{id}/complete, RFC 9421 signed, carrying the buyer's ERC-3009 TransferWithAuthorization for the exact amount and domain the create response advertised. Settlement moves the funds and creates the order in the merchant's own commerce backend, buyer wallet stamped on it, in the same call.
• Refund or cancel, initiate. POST /ucp/v1/checkout-sessions/refund, RFC 9421 signed, body {order_id, reason, refund_line_items?}. Authorization is bound to the order's real site id server-side, never to the caller's self-asserted identity, so a forged claim of ownership cannot open a ticket on an order it does not own. Moves no money; opens a ticket the merchant can review.
• Refund or cancel, approve. The merchant's own client signs an ERC-3009 send-back from its own pay_to to the order's stamped buyer address, for an amount the server derives from the merchant's own commerce order, never from the agent's request. The protocol layer checks signer equals pay_to, destination equals the stamped buyer, and amount equals the derived total, before relaying it to a facilitator.

Where this sits relative to what already exists

Security model

• Non-custodial by construction, not by policy. The only two keys that ever sign a money leg are the buyer's, at checkout, and the merchant's own, at refund. The protocol layer verifies signatures; it produces none.
• Ownership is bound server-side. A refund ticket is opened against the site the settled order actually belongs to, resolved from the order record, never from a claim the caller's request makes about itself.
• The amount is never agent-set. A line-item selection is advisory input, validated against what was actually ordered; the number that gets signed is read from the merchant's own commerce order at approval time.
• A shared ledger caps every refund path together. A partial refund, a second partial refund, and a full cancellation on the same order are checked against one running total, so no combination of agent-initiated requests can exceed what was captured.
• Replay-proof. Every ERC-3009 authorization carries a single-use nonce consumed on-chain; a facilitator independently re-verifies a signature before broadcasting it.
• Reviewed adversarially before shipping. The merchant-signed reverse-settlement path was reviewed across independent attack lenses before its mainnet run, each finding checked by independent review passes; the one real functional gap found (a dead end for a merchant with no managed signer configured) was fixed before merge, not disclosed as a residual risk.

Why this belongs in the open, not in one company's stack

x402 Direct is deliberately not a fork, a competing payment scheme, or a reason to leave the spec. It is evidence for a specific, narrow claim: that exact plus a checkout-session layer plus an agent-facing initiation route plus a non-custodial reverse leg is enough to run real commerce, cart through cancellation, without a merchant ever handing custody of a refund key to anyone. That claim is falsifiable by exactly the same tools that verify the rest of x402: a transaction hash, a signature, a published key.

The open question worth the Foundation's attention is narrower than a whole new scheme: whether an identity credential distinct from the signing wallet, and a line-item-aware refund initiation bound to a real commerce order, belong as a documented extension pattern above exact, the way auth-capture documents a different, escrow-based answer to a related but distinct problem. This paper and the validation report it precedes are offered as the worked example.

On precedence, stated carefully because it is checkable. We are not claiming to have invented refunds on x402; the specification's own auth-capture scheme describes an escrow-based answer, and it was merged before this work was proven. What we can document is narrower and, we think, more useful: as of 2026-07-23, the reference implementation of that scheme ships a client with server and facilitator support explicitly deferred, and we are not aware of another agent-initiated refund and cancellation loop settling real value on x402 in production. The loop in the validation report below did that on Base mainnet, non-custodially, on the exact rail. If someone else got there first, the same standard of proof should settle it: a transaction hash, a signature, a published key.

References

1. x402 Foundation. x402 protocol specification. github.com/x402-foundation/x402, specs/.
2. x402 Foundation. Scheme: exact. specs/schemes/exact/.
3. x402 Foundation. Scheme: auth-capture. specs/schemes/auth-capture/scheme_auth_capture.md and scheme_auth_capture_evm.md.
4. x402 Foundation. Scheme: upto. specs/schemes/upto/scheme_upto.md.
5. x402 Foundation. Scheme: batch-settlement. specs/schemes/batch-settlement/scheme_batch_settlement.md.
6. Base. commerce-payments contract stack (AuthCaptureEscrow). github.com/base/commerce-payments.
7. Universal Commerce Protocol. Specification and documentation. github.com/Universal-Commerce-Protocol/ucp.
8. Circle. USDC EIP-3009 transferWithAuthorization / receiveWithAuthorization.
9. IETF. RFC 9421, HTTP Message Signatures.
10. Facet, LLC. x402 Direct mainnet validation: UCP-signed checkout, merchant-approved refund, and agent-initiated cancellation on Base mainnet. Appended below.

Setup: all public, all on-chain

What base x402 is, and what sits on top of it

The checkout: a real 2-item cart, UCP-signed, real USDC

• CartHCF-CARD x 1 ($3.00) + HCF-BDAY x 1 ($15.00) = $18.00 goods + $9.00 delivery + $1.49 Texas sales tax = $28.49 landed, advertised by the checkout session and matched exactly by the on-chain charge.
• Checkout session941f29a3-712f-4055-b60a-31594cd2251b, status ready_for_complete, advertised pay_to 0x0BE0574bD5Fbd20E6187e6f3B6A889791699CcC3, advertised amount 28490000 atomic USDC.
• Settletx 0x20d5e6084ea6c3798057d2139dd392fe5aaa01462f48e843dbc197cb4b763d6c, block 48999141, $28.49 USDC buyer to merchant, status success. Creates a real WooCommerce order (order 135), buyer wallet stamped on the order for the refund legs below.
• Buyer identitya single-use Facet KYA (ES256 JWT, type kya+jwt, issuer issuer.facet.llc), fresh per call, expired minutes after issuance.

Partial refund by line selection: the card, pre-shipping

• Ticketb7c7c94a-4d59-45ea-ba17-0ab7775f1764, reason "buyer requested a partial refund (card line)".
• Send-backtx 0x66e658fda738384f7f558e7428241e5e91457fb95e8a2eca0bc6f995d8b7efee, block 49024328, $3.25 USDC (the $3.00 line plus its $0.25 tax) merchant to buyer, status success.
• Left capturedthe flower line and the $9.00 delivery fee.

Post-delivery damaged return: the arrangement, after shipping

• Ticket327c3094-56ba-4b3c-a2ad-b2a516ed38b6, reason "delivered damaged: arrangement arrived wilted".
• Send-backtx 0x63b0660bfee828d78198b0c9dad31634b6329cbdecdc327278ce59df65a3f3c1, block 49026760, $16.24 USDC (the $15.00 line plus its $1.24 tax) merchant to buyer, status success.
• Signature captureissued over the same RFC 9421-signed route, from the same platform key, as the other two requests in this report. The raw request bytes for this specific call were not retained in this run; the ticket record and the on-chain settlement above are independently verifiable without them.

Agent-initiated cancellation: a full order, before fulfillment

• OrderWoo order 138, a single-item purchase (HCF-CARD x 1, $3.00 goods + $9.00 delivery + $0.25 tax = $12.25 landed), settled the same way as section 02.
• Ticket180b65b3-2808-4489-8cf5-f44932596b1a, reason "buyer cancelled the order before fulfillment (full refund)", no line selection supplied.
• Send-backtx 0x0370b28b629336725be8f72f7657ae3955262365442be57127fd06408e6731e9, block 49027308, $12.25 USDC, the full captured total including delivery, merchant to buyer, status success.

The signature inventory: nothing is unsigned

Guarantees: why the agent controls no money

• The refund signer must equal the merchant's own pay_to. Checked before anything is signed, so a send-back can only ever move funds out of the wallet that received the original purchase. It cannot be pointed at a different wallet, and Facet holds no key that could sign one anyway.
• The destination is the order's stamped buyer wallet. Never a field in the agent's request. An agent can propose which line to refund; it cannot propose where the money goes.
• The amount is server-derived, never agent-set. The taxed total is read from the merchant's own commerce order at approval time. A partial selection is advisory input, validated against the ordered line items; the number that gets signed comes from the merchant's own books.
• A shared budget ledger caps every refund path together, per order. A card partial, a flowers partial, and a would-be third claim on the same order are all checked against one running total, so no combination of requests can ever exceed what was captured.
• The ERC-3009 nonce is single-use on-chain. A captured send-back signature cannot be replayed; the facilitator independently re-verifies the signature before broadcasting.
• Gasless on every leg. The buyer signs to buy, the merchant signs to refund, and a relayer broadcasts and pays gas both ways.

Summary and how to verify