# x402

> Paying a Storeware shop in USDC on Base with an x402 payment, at a shop that has turned it on.

Source: https://storeware.ai/docs/agents/x402

[x402](https://github.com/coinbase/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

1. **Read the checkout session.** Over ACP, look in `capabilities.payment.handlers` for the handler named `ai.storeware.x402`, with id `storeware_x402`. Its `config` is a complete x402 `PaymentRequired`: 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 a `store_credit` message.
2. **Sign** an EIP-3009 `transferWithAuthorization` for exactly that amount, to exactly that address, on the network named in `accepts[0].network`. Base is `eip155:8453`.
3. **Complete the checkout** with the base64 payload as the credential's token, and `x402` as 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](https://storeware.ai/handlers/x402/config.schema.json) for its `config`, and [instrument.schema.json](https://storeware.ai/handlers/x402/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.

```http
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.