How x402 Works

This page explains the complete payment flow in x402, from initial request to payment settlement.

Overview

x402 enables programmatic payments over HTTP using a simple request-response flow. When a client requests a paid resource, the server responds with payment requirements, the client submits payment, and the server delivers the resource.

Interaction Flow

Payment-flow

1. Client makes an HTTP request to a resource server

2. Resource server responds with a 402 Payment Required status and a Payment Required Response JSON object in the response body.

3. Client selects one of the paymentDetails returned by the accepts field of the server response and creates a Payment Payload based on the scheme of the paymentDetails they have selected.

4. Client sends the HTTP request with the X-PAYMENT header containing the Payment Payload to the resource server

5. Resource server verifies the Payment Payload is valid either via local verification or by POSTing the Payment Payload and Payment Details to the /verify endpoint of the facilitator server.

6. Facilitator server performs verification of the object based on the scheme and networkId of the Payment Payload and returns a Verification Response

7. If the Verification Response is valid, the resource server performs the work to fulfill the request. If the Verification Response is invalid, the resource server returns a 402 Payment Required status and a Payment Required Response JSON object in the response body.

8. Resource server either settles the payment by interacting with a blockchain directly, or by POSTing the Payment Payload and Payment Details to the /settle endpoint of the facilitator server.

9. Facilitator server submits the payment to the blockchain based on the scheme and networkId of the Payment Payload.

10. Facilitator server waits for the payment to be confirmed on the blockchain.

11. Facilitator server returns a Payment Execution Response to the resource server.

12. Resource server returns a 200 OK response to the Client with the resource they requested as the body of the HTTP response, and a X-PAYMENT-RESPONSE header containing the Settlement Response as Base64 encoded JSON if the payment was executed successfully.