Documentation Index
Fetch the complete documentation index at: https://docs.x402r.org/llms.txt
Use this file to discover all available pages before exploring further.
Overview
Theauth-capture scheme for x402 v2 uses the audited Commerce Payments Protocol (AuthCaptureEscrow + token collectors) directly, no fork. The client signs a single signature (ERC-3009 or Permit2). The facilitator submits it, either locking funds in escrow for later capture (two-phase) or sending them directly to the receiver with refund capability (single-shot).
Unlike exact, which has no mechanism for returning funds, auth-capture supports returning funds to the client through void, refund, and reclaim.
Settlement Paths
The scheme supports two settlement paths, selected viaextra.autoCapture:
autoCapture | Behavior |
|---|---|
false (default) | Two-phase. Funds held in escrow. CaptureAuthorizer can capture, void, or refund. Client can reclaim if the capture deadline passes. |
true | Single-shot. Funds sent directly to the receiver. CaptureAuthorizer can refund post-settlement. |
Two-phase (autoCapture: false, default)
Authorize
The facilitator submits the client’s authorization, locking funds in escrow via
AuthCaptureEscrow.authorize(). The token collector executes the client’s signature (ERC-3009 receiveWithAuthorization or Permit2 permitTransferFrom) to pull tokens into escrow.Capture or Void
The captureAuthorizer can capture (capture funds to the receiver) or void (return escrowed funds to the client). Capture conditions are policy-defined per captureAuthorizer (time-locked, arbiter-approved, etc.).
Reclaim
If
captureDeadline passes without capture, the client can reclaim funds directly from the escrow without captureAuthorizer involvement.Single-shot (autoCapture: true)
Charge
The facilitator submits the client’s authorization, sending funds directly to the receiver via
AuthCaptureEscrow.charge(). No escrow hold.Visual Flow
Exact Payment (Immediate Settlement)
auth-capture (Two-phase)
Key Differences
| Aspect | Exact | auth-capture |
|---|---|---|
| Settlement | Immediate on request | Via escrow (two-phase) or direct with refund (single-shot) |
| Payer Protection | None (payment final) | Refundable in both paths |
| Resource Delivery | After payment clears | Immediately after authorization |
| Recourse | No recourse | Reclaim after capture deadline, refund via captureAuthorizer |
| Fee System | None | Configurable (min/max bounds, client-signed) |
| Use Case | Trusted, low-value, instant | High-value, variable cost, disputes |
CaptureAuthorizer
The captureAuthorizer is the address that may callauthorize, capture, void, refund, or charge on a payment. The escrow contract gates those operations on msg.sender. In x402’s facilitator-submits flow that means either the facilitator’s EOA, or any smart contract that ends up calling the escrow (for example, an arbiter contract with dispute logic or a multisig).
| Use Case | CaptureAuthorizer |
|---|---|
| Session billing | EOA that tracks usage off-chain, captures periodically |
| Time-locked escrow | Contract that releases after a period expires |
| Dispute resolution | Arbiter contract that decides capture vs refund |
| Immediate (exact-like) | Facilitator with autoCapture: true for instant settlement |
| Streaming payments | Contract that performs time-proportional captures |
vs Exact Scheme
Theauth-capture scheme adds an authorization step before settlement (or refundability for single-shot). For simple immediate payments where trust and refundability aren’t concerns, the exact scheme remains more efficient.
Next Steps
Wire Format
PaymentRequirements and PaymentPayload shapes for EIP-3009 and Permit2.
Verification and Settlement
The 13-step verification flow, settlement logic, and error codes.
PaymentInfo Struct
On-chain struct, expiry ordering, and safety guarantees.
SDK Overview
Build your first auth-capture payment flow.