x402
Paying a Storeware shop in USDC on Base with an x402 payment, at a shop that has turned it on.
x402 is how a client pays for something over HTTP without a person: the seller states a price, the client signs a stablecoin transfer, and a facilitator settles it on chain. A Storeware shop can take an x402 payment in USDC on Base, with no card and nobody in the loop.
Storeware speaks x402 version 2 only. A version 1 X-PAYMENT header is not read.
Which shops take it
x402 is off for every shop until its merchant turns it on. A shop offers it only when all of these hold:
- the merchant has opted in, and the shop has a verified deposit address, issued by Stripe on the shop's own account;
- the basket is priced in US dollars;
- something is left to pay after any store credit;
- the shop pays no platform fee on its sales.
So do not assume it. Read the checkout: if the x402 handler is there, the shop takes it for that basket, and if it is not, it does not.
Paying a checkout
- Read the checkout session. Over ACP, look in
capabilities.payment.handlersfor the handler namedai.storeware.x402, with idstoreware_x402. Itsconfigis a complete x402PaymentRequired: the amount left to pay after store credit, in atomic USDC units, and the address to pay. Over UCP, the handler is in the shop's profile, with the network, token and address but no amount: pay what the session has left to pay. A UCP session with store credit on it says what that is in astore_creditmessage. - Sign an EIP-3009
transferWithAuthorizationfor exactly that amount, to exactly that address, on the network named inaccepts[0].network. Base iseip155:8453. - Complete the checkout with the base64 payload as the credential's token, and
x402as its type.
| Door | Where the payment goes | Where the receipt comes back |
|---|---|---|
| ACP, over REST or MCP | payment_data.instrument.credential.token, base64 | The checkout session |
| UCP, over REST or MCP | payment.instruments[].credential.token, base64 | The UCP answer |
| x402's own MCP convention | _meta["x402/payment"], as JSON | _meta["x402/payment-response"] |
POST https://api.storeware.ai/api/x402/buy | The PAYMENT-SIGNATURE header, base64 | The PAYMENT-RESPONSE header |
The handler's two schemas are published: config.schema.json for its config, and instrument.schema.json for what an agent sends back.
Buying in one request
POST https://api.storeware.ai/api/x402/buy is a plain x402 endpoint, and an x402 client that has never heard of Storeware can use it. It is meant for one item that needs no delivery, such as a download. A physical good needs an address and a delivery rate, which is what a checkout session is for.
POST https://api.storeware.ai/api/x402/buy
Authorization: Bearer swa_...
Content-Type: application/json
{ "variant_id": "…", "quantity": 1, "buyer_email": "shopper@example.com" }Without a payment, the answer is 402 with the requirements in the PAYMENT-REQUIRED header. Send the same request again with a signed payload in PAYMENT-SIGNATURE, and the answer is the order, with the settlement in PAYMENT-RESPONSE. A shop that does not take x402 answers 409 payments_not_configured.
What is checked
The requirements are rebuilt from the checkout when the payment arrives, never taken from the payload. A payment is refused if its recipient, amount, token or network differs from what the shop published, if its signature does not recover to the account it claims, or if its validity window has closed. The amount must be what the order is charged after store credit, and a payment signed for anything else is refused before anything settles, with x402_amount_mismatch when the basket changed underneath it.
No refunds through Storeware
A settled transfer is final. There is no chargeback and no dispute. An order paid this way cannot be refunded through the platform: a merchant refunding one sends the stablecoin back themselves.