

The 402 handshake
Ask, get a price, sign a payment, ask again. A facilitator checks and settles it.
Key points
- The server answers 402 with a price in the PAYMENT-REQUIRED header.
- The client retries with a signed payment in PAYMENT-SIGNATURE.
- A facilitator checks the payment, then submits it to the chain.
The lesson
Picture a snack machine that talks.
You ask for chips. The machine says, "That's 50 cents. Here is how to pay." You put in a signed slip for 50 cents. Then you ask again. A helper checks the slip and cashes it. Out come the chips.
works the same way, with three parties:
- The client: the agent that wants the data.
- The : the service that sells it.
- The : a helper service that checks the payment and sends it to the chain.
The client signs the payment itself. The facilitator only passes it along. It cannot change who gets paid or how much. Any change would break the client's signature.
The whole trip is two web requests. On the XRP Ledger, the payment settles in seconds.
The version 2 handshake over HTTP:
- The client sends a normal request.
- The server answers
402with aPAYMENT-REQUIREDheader. It holds base64-encoded JSON: anacceptslist of ways to pay. - The client picks one, builds and signs a payment, and retries with a
PAYMENT-SIGNATUREheader. - The server sends that payload to the 's
/verifyendpoint. - If it passes, the server calls
/settle. The facilitator checks again and submits the transaction. - After settlement, the server sends the data with a
PAYMENT-RESPONSEheader:success, thetransactionhash, thenetworkand thepayer.
Each
acceptsentry names ascheme, the way to pay, such asexact. It also names anetwork, anasset, anamount, apayToaddress andmaxTimeoutSeconds. Extra fields go inextra.Version 1 used
X-PAYMENTandX-PAYMENT-RESPONSE. The spec calls those names deprecated.The XRP Ledger spec lists its trust limits. The facilitator cannot redirect funds. The server cannot collect more than the payer signed for. Some guides, like one page on xrpl.org, still show the older flow and header names.

