exact versus upto. Every guide in these docs assumes these terms.
The payment loop
1
Request
A client requests a protected resource. It has no payment yet.
2
402 with terms
The server answers
402 Payment Required with the price, the asset, the network, and the
address to pay.3
Sign
The client signs a Soroban authorization entry that permits exactly that one payment. On Stellar
the client signs an auth entry, not a pre-signed transaction.
4
Retry
The client retries the request with the signed payment attached.
5
Verify and settle
The facilitator verifies the authorization, submits it on-chain, and sponsors the network fee.
6
Resource
The server returns the resource. If the service carried discovery metadata, the facilitator
catalogs it in the Bazaar.
The four addresses
A payment involves four parties. Keeping them straight is the single most common point of confusion.The facilitator is the transaction source and pays the network fee, so the buyer needs only the
payment asset and no XLM. The facilitator never holds the buyer’s funds. It only submits the
buyer-signed authorization, so tampering with a payment fails signature verification.
exact and upto
Rail402 supports two settlement schemes.exact
A fixed price. The buyer authorizes and settles one known amount. Use it for a per-call price.
upto
Authorize a ceiling, settle the actual usage. Use it for metered services such as token billing.
A Soroban contract enforces the ceiling on-ledger.
The three surfaces
You interact with Rail402 through one of three surfaces, depending on what you are building.Next steps
Install and first payment
Make a real testnet payment in five minutes.
Stellar essentials
Trustlines, SEP-41 assets, 7-decimal amounts, and smart accounts.