Struct Paygate 

pub struct Paygate<TFacilitator> { /* private fields */ }

Available on crate feature server only.

V2-only payment gate for enforcing x402 payments.

Handles the full payment lifecycle: header extraction, verification, settlement, and 402 response generation using the V2 wire format.

Construct via PaygateBuilder (obtained from Paygate::builder).

To add lifecycle hooks (before/after verify and settle), wrap your facilitator with HookedFacilitator before passing it to the payment gate.

Implementations

impl<TFacilitator> Paygate<TFacilitator>

pub const fn builder(facilitator: TFacilitator) -> PaygateBuilder<TFacilitator>

Returns a new builder seeded with the given facilitator.

pub const fn facilitator(&self) -> &TFacilitator

Returns a reference to the underlying facilitator.

pub fn accepts(&self) -> &[PriceTag]

Returns a reference to the accepted price tags.

pub const fn resource(&self) -> &ResourceInfo

Returns a reference to the resource information.

pub fn error_response(&self, err: PaygateError) -> Response

Converts a PaygateError into a proper HTTP response.

Verification errors produce a 402 with the Payment-Required header and a JSON body. Settlement errors produce a 402 with error details.

Panics

Panics if the payment-required response cannot be serialized to JSON or if the HTTP response builder fails. These indicate a bug.

impl<TFacilitator> Paygate<TFacilitator>

where TFacilitator: Facilitator + Sync,

pub async fn enrich_accepts(&mut self)

Enriches price tags with facilitator capabilities (e.g., fee payer address).

pub async fn verify_only( &self, headers: &HeaderMap, ) -> Result<VerifiedPayment, PaygateError>

Verifies the payment from request headers without executing the inner service or settling on-chain.

Returns a VerifiedPayment token on success, which the caller can later settle at their discretion.

Errors

Returns PaygateError::Verification if the payment header is missing, malformed, or rejected by the facilitator.

pub async fn handle_request<ReqBody, ResBody, S: Service<Request<ReqBody>, Response = Response<ResBody>>>( &self, inner: S, req: Request<ReqBody>, ) -> Result<Response, PaygateError>

where S::Response: IntoResponse, S::Error: IntoResponse, S::Future: Send,

Handles an incoming request with sequential settlement.

verify → execute → settle → attach header → return

Settlement only runs if the handler returns a success status (not 4xx/5xx).

Errors

Returns PaygateError if payment verification or settlement fails.

impl<TFacilitator> Paygate<TFacilitator>

where TFacilitator: Facilitator + Clone + Send + Sync + 'static,

pub async fn handle_request_concurrent<ReqBody, ResBody, S: Service<Request<ReqBody>, Response = Response<ResBody>>>( &self, inner: S, req: Request<ReqBody>, ) -> Result<Response, PaygateError>

where S::Response: IntoResponse, S::Error: IntoResponse, S::Future: Send + 'static, ReqBody: Send + 'static,

Handles an incoming request with concurrent settlement.

verify → (settle ∥ execute) → await settle → attach header → return

Settlement is spawned immediately after verification and runs in parallel with the handler, reducing total latency by one facilitator RTT. On handler error (4xx/5xx), the settlement task is detached.

Errors

Returns PaygateError if payment verification or settlement fails.