Core Contracts - x402r Documentation

PaymentOperator

The main payment operator contract with pluggable conditions for flexible authorization logic.

Overview

Type: Operator instance (one per fee recipient + configuration)
Deployment: Via PaymentOperatorFactory
Immutability: Cannot be paused or upgraded
Configuration: 10 slots for conditions and recorders
Use Cases: Marketplace, subscriptions, streaming, grants, custom flows

Immutable Fields

address public immutable ESCROW;              // AuthCaptureEscrow address
address public immutable FEE_RECIPIENT;       // Operator fee recipient
ProtocolFeeConfig public immutable PROTOCOL_FEE_CONFIG; // Shared protocol fee config
IFeeCalculator public immutable FEE_CALCULATOR; // Operator fee calculator

State

// Fee tracking for accurate distribution
mapping(address token => uint256) public accumulatedProtocolFees;

// Fees locked at authorization time
mapping(bytes32 paymentInfoHash => AuthorizedFees) public authorizedFees;

10-Slot Configuration

Condition Slots (Before Actions)

AUTHORIZE_CONDITION - Who can authorize payments
CHARGE_CONDITION - Who can charge partial amounts
RELEASE_CONDITION - Who can release from escrow
REFUND_IN_ESCROW_CONDITION - Who can refund during escrow
REFUND_POST_ESCROW_CONDITION - Who can refund after release

Default: address(0) = always allow

Recorder Slots (After Actions)

AUTHORIZE_RECORDER - Record authorization (e.g., timestamp)
CHARGE_RECORDER - Record charge event
RELEASE_RECORDER - Record release
REFUND_IN_ESCROW_RECORDER - Record in-escrow refund
REFUND_POST_ESCROW_RECORDER - Record post-escrow refund

Default: address(0) = no recording (no-op)

Key Methods

authorize()

Authorizes a payment and locks funds in escrow.

function authorize(
    AuthCaptureEscrow.PaymentInfo calldata paymentInfo,
    uint256 amount,
    address tokenCollector,
    bytes calldata collectorData
) external nonReentrant

Parameters:

paymentInfo - Payment info struct (must have operator == address(this), feeReceiver == address(this))
amount - Amount to authorize
tokenCollector - Address of the token collector contract
collectorData - Data to pass to the token collector

Flow:

Check AUTHORIZE_CONDITION (if set)
Validate fee bounds compatibility
Store fees at authorization time (prevents protocol fee changes from breaking capture)
Call escrow.authorize()
Call AUTHORIZE_RECORDER (if set)
Emit AuthorizationCreated

Access: Controlled by AUTHORIZE_CONDITION (default: anyone)

Authorization Expiry: The PaymentInfo struct includes an authorizationExpiry field (from base commerce-payments). Set this to type(uint48).max for no expiry, or specify a timestamp to allow the payer to reclaim funds after expiry. This is useful for subscription-based payments where you want to limit the authorization window.

charge()

Direct charge - collects payment and immediately transfers to receiver (no escrow hold).

function charge(
    AuthCaptureEscrow.PaymentInfo calldata paymentInfo,
    uint256 amount,
    address tokenCollector,
    bytes calldata collectorData
) external nonReentrant

Parameters:

paymentInfo - Payment info struct (must have operator == address(this), feeReceiver == address(this))
amount - Amount to charge
tokenCollector - Address of the token collector contract
collectorData - Data to pass to the token collector

Flow:

Check CHARGE_CONDITION (if set)
Validate fee bounds compatibility
Call escrow.charge() - funds go directly to receiver
Accumulate protocol fees for later distribution
Call CHARGE_RECORDER (if set)
Emit ChargeExecuted

Access: Controlled by CHARGE_CONDITION (default: anyone)

Unlike authorize(), funds go directly to receiver without escrow hold. Refunds are only possible via refundPostEscrow().

release()

Releases funds from escrow to receiver (capture).

function release(
    AuthCaptureEscrow.PaymentInfo calldata paymentInfo,
    uint256 amount
) external nonReentrant

Parameters:

paymentInfo - Payment info struct
amount - Amount to release

Flow:

Check RELEASE_CONDITION (if set)
Use fees stored at authorization time
Call escrow.capture()
Accumulate protocol fees for later distribution
Call RELEASE_RECORDER (if set)
Emit ReleaseExecuted

Access: Controlled by RELEASE_CONDITION

Marketplace example: Receiver OR StaticAddressCondition(arbiter) + escrow passed Subscription example: StaticAddressCondition(serviceProvider) DAO example: StaticAddressCondition(daoMultisig)

refundInEscrow()

Refunds payment while still in escrow (partial void).

function refundInEscrow(
    AuthCaptureEscrow.PaymentInfo calldata paymentInfo,
    uint120 amount
) external nonReentrant

Parameters:

paymentInfo - Payment info struct
amount - Amount to return to payer

Flow:

Check REFUND_IN_ESCROW_CONDITION (if set)
Call escrow.partialVoid() to return funds to payer
Call REFUND_IN_ESCROW_RECORDER (if set)
Emit RefundInEscrowExecuted

Access: Controlled by REFUND_IN_ESCROW_CONDITION

Marketplace example: StaticAddressCondition(arbiter) - disputes Return policy example: Receiver OR StaticAddressCondition(arbiter) DAO example: StaticAddressCondition(daoMultisig) Subscription example: address(0) - no refunds

refundPostEscrow()

Refunds payment after it has been released (captured).

function refundPostEscrow(
    AuthCaptureEscrow.PaymentInfo calldata paymentInfo,
    uint256 amount,
    address tokenCollector,
    bytes calldata collectorData
) external nonReentrant

Parameters:

paymentInfo - Payment info struct
amount - Amount to refund to payer
tokenCollector - Address of the token collector that will source the refund
collectorData - Data to pass to the token collector (e.g., signatures)

Flow:

Check REFUND_POST_ESCROW_CONDITION (if set)
Call escrow.refund() - token collector enforces permission
Call REFUND_POST_ESCROW_RECORDER (if set)
Emit RefundPostEscrowExecuted

Access: Controlled by REFUND_POST_ESCROW_CONDITION. Permission is also enforced by the token collector (e.g., receiver must have approved it, or collectorData contains receiver’s signature).

Marketplace example: StaticAddressCondition(arbiter) - post-delivery disputes Return policy example: Receiver - voluntary returns Most configurations: address(0) - no post-escrow refunds

Fee System (Modular, Additive)

Fees are additive and modular: totalFee = protocolFee + operatorFee

Fee Architecture

// Shared protocol fee config (timelocked, swappable calculator)
ProtocolFeeConfig public immutable PROTOCOL_FEE_CONFIG;

// Per-operator fee calculator (immutable, set at deploy)
IFeeCalculator public immutable FEE_CALCULATOR;

// Fee recipients
address public immutable FEE_RECIPIENT;  // Operator fee recipient
// Protocol fee recipient is on ProtocolFeeConfig

// Fee tracking for accurate distribution
mapping(address token => uint256) public accumulatedProtocolFees;

Example Fee Calculation (Additive): For a 1000 USDC payment:

Protocol Fee: 3 bps (0.03%) = 0.30 USDC → goes to protocolFeeRecipient
Operator Fee: 2 bps (0.02%) = 0.20 USDC → goes to FEE_RECIPIENT
Total Fee: 5 bps (0.05%) = 0.50 USDC
Receiver Gets: 999.50 USDC

Fee Locking: Fees are calculated and stored at authorize() time in authorizedFees[hash]. This prevents protocol fee changes from breaking capture of already-authorized payments.

struct AuthorizedFees {
    uint16 totalFeeBps;
    uint16 protocolFeeBps;
}
mapping(bytes32 paymentInfoHash => AuthorizedFees) public authorizedFees;

FEE_RECIPIENT can be:

Arbiter (marketplace with disputes)
Service Provider (subscriptions)
Platform Treasury (platform-controlled)
DAO Multisig (governance-controlled)

Fee Distribution

Fees accumulate in the operator contract and are distributed via distributeFees(token):

// Anyone can call to distribute fees for a token
operator.distributeFees(usdcAddress);
// Protocol share → protocolFeeRecipient
// Operator share → FEE_RECIPIENT

Protocol Fee Changes (7-day Timelock)

Protocol fee calculator changes require a 7-day timelock on ProtocolFeeConfig:

// Step 1: Queue new calculator
protocolFeeConfig.queueCalculator(newCalculatorAddress);

// Step 2: Wait 7 days

// Step 3: Execute
protocolFeeConfig.executeCalculator();

Protocol fee changes require 7-day timelock. Operator fees are immutable (set at deploy time).

Security Features

ReentrancyGuardTransient - EIP-1153 transient storage for gas-efficient reentrancy protection
Ownership - Solady’s Ownable with 2-step transfer
Timelock - 7-day delay on protocol fee changes (operator fees are immutable)
Immutable Core - Escrow, conditions, and fee configuration cannot be changed

RefundRequest

Manages refund requests independent of operator implementation.

Overview

Type: Singleton (one per network)
Deployment: Direct deployment (no factory)
Purpose: Track refund request lifecycle

Request Types

In-Escrow Refunds
Post-Escrow Refunds

Who can request: Payer, Receiver, OR ArbiterTypical flow:

Payer suspects fraud, requests refund
Arbiter investigates
Arbiter approves or denies request
If approved, arbiter calls operator.refundInEscrow()

Use cases:

Buyer remorse
Seller fraud
Payment error

Who can request: Receiver onlyTypical flow:

Receiver realizes product defect after release
Receiver requests refund
Arbiter investigates
If approved, arbiter calls operator.refundPostEscrow()

Use cases:

Product defects discovered later
Service not as described
Voluntary refund by merchant

Request Status States

Key Methods

requestRefund()

Creates a new refund request.

function requestRefund(
    AuthCaptureEscrow.PaymentInfo calldata paymentInfo,
    uint120 amount,
    uint256 nonce
) external

Parameters:

paymentInfo - Payment info struct
amount - Amount being requested for refund
nonce - Record index (from PaymentIndexRecorder) identifying which charge/action

Access Control: Only the payer who made the authorization can request

Each refund request is keyed by (paymentInfoHash, nonce) where nonce is the record index. This allows multiple refund requests per payment (one per charge/action).

updateStatus()

Approve or deny a refund request.

function updateStatus(
    AuthCaptureEscrow.PaymentInfo calldata paymentInfo,
    uint256 nonce,
    RequestStatus newStatus
) external

Parameters:

paymentInfo - Payment info struct
nonce - Record index identifying which refund request
newStatus - The new status (Approved or Denied)

Access: Receiver can always approve/deny. While in escrow, anyone passing the operator’s REFUND_IN_ESCROW_CONDITION can also approve/deny. Valid transitions:

Pending → Approved
Pending → Denied

cancelRefundRequest()

Payer cancels their own request.

function cancelRefundRequest(
    AuthCaptureEscrow.PaymentInfo calldata paymentInfo,
    uint256 nonce
) external

Parameters:

paymentInfo - Payment info struct
nonce - Record index identifying which refund request

Access: Only the payer who created the request Valid transition:

Pending → Cancelled

Usage Example

// 1. Payer requests refund (nonce 0 = first action on this payment)
await refundRequest.requestRefund(paymentInfo, requestedAmount, 0);
// Status: Pending

// 2. Receiver (or arbiter) reviews and approves
await refundRequest.updateStatus(
  paymentInfo,
  0,  // nonce
  RequestStatus.Approved
);
// Status: Approved

// 3. Execute refund via operator (separate transaction)
await operator.refundInEscrow(paymentInfo, refundAmount);
// Funds returned to payer

RefundRequest is advisory only. Approval does not automatically execute refunds - the authorized party must call the operator’s refund function.

AuthCaptureEscrow

Base escrow contract from commerce-payments library.

Overview

Type: Singleton (one per network)
Source: commerce-payments (x402r fork)
Purpose: Hold ERC-20 tokens during payment lifecycle
Access: Operator-based (only registered operators can manage payments)

x402r uses a forked version of commerce-payments with added partial void support for handling partially completed orders.

Payment State Machine

Key Methods

authorize()

Locks tokens in escrow. Called by operator.

function authorize(
    bytes32 paymentId,
    address payer,
    address receiver,
    uint256 amount,
    address token,
    address operator
) external onlyOperator

Requires: Payer has approved escrow contract for amount of token

The base escrow contract uses individual parameters (paymentId, payer, receiver, etc.) while the PaymentOperator wraps them in a PaymentInfo struct. The operator translates between the two formats internally.

release()

Releases tokens to receiver. Called by operator.

function release(
    bytes32 paymentId
) external onlyOperator returns (uint256 amount)

State change: InEscrow → Released

void()

Returns tokens to payer (full refund). Called by operator.

function void(
    bytes32 paymentId
) external onlyOperator

State change: InEscrow → Settled Use case: Refund during escrow period

reclaim()

Takes tokens back from receiver to give to payer. Called by operator.

function reclaim(
    bytes32 paymentId,
    address from,
    uint256 amount
) external onlyOperator

State change: Released → Settled Use case: Refund after release Requires: Receiver has approved escrow for amount

partialVoid()

Returns partial amount to payer.

function partialVoid(
    bytes32 paymentId,
    uint256 amount
) external onlyOperator

Use case: Partial refunds for partially fulfilled orders

Security Features

Operator whitelist - Only registered operators can manage payments
Reentrancy protection - All state changes protected
Event logging - Complete audit trail

Supporting Contracts

ERC3009PaymentCollector

Payment collection with gasless meta-transactions. Features:

ERC-3009 transferWithAuthorization() support
Nonce-based replay protection
Deadline-based expiry
Multicall3 integration

Use case: Allow payers to authorize payments via signed messages instead of direct transactions (gasless UX).

TokenStore

Safe token transfer utilities from commerce-payments. Features:

Reentrancy-safe transfers
SafeERC20 integration
Balance tracking

Contract Addresses

Base Sepolia Testnet

Contract	Address
AuthCaptureEscrow	`0xb9488351E48b23D798f24e8174514F28B741Eb4f`
ERC3009PaymentCollector	`0xed02d3E5167BCc9582D851885A89b050AB816a56`
RefundRequest	`0x6926c05193c714ED4bA3867Ee93d6816Fdc14128`
PaymentOperatorFactory	`0xFa8C4Cb156053b867Ae7489220A29b5939E3Df70`

Next Steps

Factories

Learn about factory deployment patterns.

Conditions

Explore the pluggable condition system.

Deploy an Operator

Deploy operators using the SDK’s deployment utilities.

Examples

See real-world configuration examples.

Getting Started

Smart Contracts

Roadmap

​PaymentOperator

​Overview

​Immutable Fields

​State

​10-Slot Configuration

​Key Methods

​authorize()

​charge()

​release()

​refundInEscrow()

​refundPostEscrow()

​Fee System (Modular, Additive)

​Fee Architecture

​Fee Distribution

​Protocol Fee Changes (7-day Timelock)

​Security Features

​RefundRequest

​Overview

​Request Types

​Request Status States

​Key Methods

​requestRefund()

​updateStatus()

​cancelRefundRequest()

​Usage Example

​AuthCaptureEscrow

​Overview

​Payment State Machine

​Key Methods

​authorize()

​release()

​void()

​reclaim()

​partialVoid()

​Security Features

​Supporting Contracts

​ERC3009PaymentCollector

​TokenStore

​Contract Addresses

​Base Sepolia Testnet

​Next Steps

Factories

Conditions

Deploy an Operator

Examples

PaymentOperator

Overview

Immutable Fields

State

10-Slot Configuration

Key Methods

authorize()

charge()

release()

refundInEscrow()

refundPostEscrow()

Fee System (Modular, Additive)

Fee Architecture

Fee Distribution

Protocol Fee Changes (7-day Timelock)

Security Features

RefundRequest

Overview

Request Types

Request Status States

Key Methods

requestRefund()

updateStatus()

cancelRefundRequest()

Usage Example

AuthCaptureEscrow

Overview

Payment State Machine

Key Methods

authorize()

release()

void()

reclaim()

partialVoid()

Security Features

Supporting Contracts

ERC3009PaymentCollector

TokenStore

Contract Addresses

Base Sepolia Testnet

Next Steps