402 Payment Required and terms, the client signs a payment and retries, and a facilitator verifies and settles it on chain before the resource is returned.
This page defines the loop and the words the rest of the docs use. Read it once, and the buyer, seller, and operator paths assume it.
The loop, step by step
1
The client requests a resource
A buyer (usually software) calls a paid endpoint with no payment attached.
2
The server answers 402 with terms
The response is
402 Payment Required carrying the payment terms: scheme, network, asset, amount, and the address to pay (payTo).3
The client signs an authorization
The buyer reads the terms and signs a Soroban authorization entry that permits exactly one payment. On Stellar this is an authorization entry, not a whole transaction. See The exact scheme.
4
The client retries with the payment attached
The buyer repeats the request, this time carrying the signed authorization.
5
The facilitator verifies
The seller’s payment middleware calls the facilitator’s
/verify. The facilitator checks that the authorization signs exactly the declared call, asset, amount, and recipient, is not replayed, and is not expired.6
The facilitator settles
The middleware calls
/settle. The facilitator builds the transaction, sets its own account as the source, pays the network fee, and submits the transfer on chain.7
The server returns the resource
Settlement succeeds and the server returns the paid response, with the settlement hash in the
PAYMENT-RESPONSE header.The four roles on stage
Every payment involves the same four participants. The rest of the docs name them without re-introducing them.Buyer
The paying party. Holds the payment asset, signs the authorization, and needs no XLM. Can be a G keypair or a C contract account (see Stellar essentials).
Seller
The resource server. States the terms in the
402, and is paid at its payTo address. Runs payment middleware that talks to the facilitator.Facilitator (sponsor)
Verifies and settles. It is the transaction source and pays the network fee, so the buyer sponsors nothing. It never holds funds (see below).
Token contract
The SEP-41 asset’s Stellar Asset Contract (SAC). The authorization permits one
transfer(from, to, amount) against it. Testnet USDC is the default asset.The facilitator’s three endpoints
A facilitator is the service a seller trusts to check and settle a payment. Rail402 exposes the standard surface.
The live testnet facilitator is
https://facilitator.rail402.dev. Point a stock, unmodified @x402/* client at it and a payment completes with no Rail402-specific code. See the reference.
The facilitator is non-custodial. The only money movement any code path causes is submitting the buyer-signed authorization exactly as signed. The transfer’s
from is the buyer, and the transaction source is the facilitator. You can confirm this on chain for any settlement in the Explorer.exact and upto
Rail402 settles two schemes. Both use the same loop above. They differ only in what the buyer signs.exact
Fixed price. The buyer authorizes exactly the stated amount, and exactly that amount settles. The fit for a fixed-price call.
upto
Metered. The buyer authorizes a ceiling, and only the actual usage settles, never more than the ceiling. The fit for a metered service such as token billing.
Next steps
How it works
The same loop, from the reader’s point of view, with a runnable path.
The exact scheme
Auth entries, ledger-based expiration, and sponsored settlement.
Bazaar
How a paid endpoint becomes discoverable.
Quickstart
Complete a settled payment end to end.