Skip to content

index.mdx

Latest commit

 

History

History
96 lines (76 loc) · 3.27 KB

index.mdx

File metadata and controls

96 lines (76 loc) · 3.27 KB
Raw
title What is x402r?
description x402r adds escrow deposits, refund windows, and dispute resolution to HTTP-native payments
icon house

x402r is a refundable payments protocol extension for x402. It enables secure, reversible transactions with built-in buyer protection through smart contract escrow on Base.

Why x402r

Standard x402 payments are immediate and irreversible. x402r adds:

  • Escrow deposits: smart contracts hold funds until conditions clear
  • Refund windows: configurable time periods for buyers to request refunds
  • Dispute resolution: arbiter system for handling contested transactions

How it works

sequenceDiagram
    participant Client
    participant Merchant
    participant Escrow
    participant Arbiter

    Client->>Escrow: Pay (funds held)
    Escrow-->>Merchant: Payment notification

    alt Happy path
        Merchant->>Escrow: Capture funds
        Escrow->>Merchant: Transfer
    else Refund requested
        Client->>Escrow: Request refund
        Merchant->>Escrow: Approve/Deny
        alt Disputed
            Arbiter->>Escrow: Resolve dispute
        end
    end
Loading

Who this is for

Capture funds, process refunds, and manage escrow periods.

Get started

Understand how x402r extends the x402 protocol. Explore the escrow and payment operator contracts. Start building with the TypeScript SDK. Deploy your own PaymentOperator on Base.

Architecture

x402r consists of these core components:

Component Purpose
PaymentOperator Manages payment authorization, capture, charge, void, and refunds with pluggable conditions
AuthCaptureEscrow Holds ERC-20 tokens during the payment lifecycle (from commerce-payments)
Conditions & Hooks Pluggable authorization checks (before action) and state updates (after action)
EscrowPeriod & Freeze Time-based capture and freeze policies for buyer protection
RefundRequest Handles refund request lifecycle and approvals

All protocol contracts use universal CREATE2 addresses, same address on every supported chain.

Supported networks

Today, the supported chains in @x402r/core are Base and Base Sepolia. More EVMs land as canonical base/commerce-payments@v1.0.0 coverage extends. See Network support for chain IDs and USDC token addresses.

Resources

Source code and examples. SDK documentation and API reference. Get help with integration.