Payment flow

The buyer first requests the protected resource and receives a 402 Payment Required response with the payment terms. After the buyer signs and retries, the resource server asks the Facilitator to verify the authorization without moving funds. If verification succeeds, the server runs the protected resource and then asks the Facilitator to settle the payment. The Facilitator sponsors the XLM network fee, submits the transaction to the selected Stellar network, waits for confirmation, and returns the settlement result to the resource server.

INFO

Verification does not move funds. Settlement happens only after the protected resource succeeds.

Retries and idempotency

Settlement is idempotent in the Buyer's signed payment. A resource server can safely resend POST /settle with the same payment — a dropped connection, a timeout, or an uncertain first answer is resolved by retrying the request.

The Facilitator identifies the original settlement from the Buyer's signature, so a retry returns the same recorded result, or continues reconciling the original transaction, rather than submitting a second payment. Retrying is also how a settlement still in flight reaches its final state: while the response is settlement_pending, resend /settle with the same payment to reconcile it against the chain.

INFO

Retry with the same signed payment. The Facilitator reuses the transaction it stored on the first request; it does not rebuild or re-sign it. A different payment is a different authorization, not a retry — and if the caller or terms differ from the stored record, the retry is answered settlement_conflict.

For a complete end-to-end example, see the weather-x402 reference — an x402-gated weather service settled through the Facilitator, including a browser wallet flow.