Implementing the x402 v2 HTTP exchange: headers, facilitators and settlement

What it is

Status as of 25 October 2026. This describes x402 protocol version 2 and its HTTP binding. Re-check both specifications and the selected scheme before deploying; a protocol version alone does not pin every implementation detail. RFC 9110 reserves HTTP 402 for future use: the status code itself supplies no interoperable payment procedure.

x402 adds that procedure. A client requests a resource, the resource server supplies payment requirements, and a facilitator can perform verification and settlement through /verify and /settle. The server may operate that functionality itself. Facilitator support must match the chosen scheme and network.

Why it matters

The HTTP binding carries base64-encoded JSON in three headers: PAYMENT-REQUIRED for the server's challenge, PAYMENT-SIGNATURE for the client's payment payload, and PAYMENT-RESPONSE for settlement results. The challenge header is the canonical location; a client should not depend on a convenient JSON response body.

The core specification separates authorization verification from moving funds. In the default authorization flow, verification precedes resource execution and settlement follows it. Other defined flows, including upfront and escrow, commit funds before execution. A successful verification is therefore insufficient evidence that settlement happened.

How to apply

• Implement the client deliberately. Parse PaymentRequired, select a supported entry from accepts, and check its amount, asset, network and recipient against spending policy before signing. Send the resulting payload through PAYMENT-SIGNATURE. Reject unfamiliar payment flows instead of guessing their effect.
• Implement server checks. Supply the requirements and validate the returned authorization against them. Follow the selected flow's verification and settlement order. Return the settlement result in PAYMENT-RESPONSE; retain its transaction identifier and network for reconciliation.
• Check browser infrastructure. For cross-origin clients, expose PAYMENT-REQUIRED and PAYMENT-RESPONSE through CORS and permit PAYMENT-SIGNATURE in the preflight. A command-line probe does not exercise those browser restrictions.
• Handle uncertainty. The documented settlement_pending result means a broadcast transaction may still confirm. Reconcile its transaction identifier before deciding whether another payment is appropriate.
• Use a review checklist. As an integration practice, record which component owns pricing, signing, verification, settlement and delivery. Exercise denied payments, unavailable facilitators and lost responses in a non-production environment before granting an agent spending authority.

Pitfalls

Treating any 402 response as permission to spend confuses a seller's request with the user's authorization. Maintain that authorization separately. The core specification explicitly excludes client budget management.

For operational review, keep payment outcome and resource delivery as separate records. Investigate a paid request with missing delivery before issuing another authorization. These recordkeeping recommendations are implementation practice, not a claim that HTTP provides automatic refunds or exactly-once application execution.