Commerce Payments Protocol

A permissionless protocol for onchain payments that mimics traditional "authorize and capture" payment flows.

Quick Start

The Commerce Payments Protocol facilitates secure escrow-based payments with flexible authorization and capture patterns. Operators drive payment flows using modular token collectors while the protocol ensures payer and merchant protections.

📖 Read the Full Documentation

🔧 Fork Modifications

This is a fork of Coinbase's Commerce Payments Protocol with the following additions:

partialVoid() Function

Location: src/AuthCaptureEscrow.sol:336-354

A custom function enabling partial refunds during the escrow period.

Purpose: The original protocol only supports full void() operations. This addition allows operators to return a specified amount (rather than the entire capturable balance) to the payer.

Use Case: Enables partial refunds for disputes, cancellations, or adjustments without voiding the entire authorization.

Function Signature:

function partialVoid(PaymentInfo calldata paymentInfo, uint120 amount)
    external
    nonReentrant
    onlySender(paymentInfo.operator)
    validAmount(amount)

Key Features:

• ✅ Operator-only access (via onlySender modifier)
• ✅ Amount validation (cannot exceed capturable amount)
• ✅ Reentrancy protection
• ✅ CEI pattern (state update before external call)
• ✅ Emits PaymentPartiallyVoided event

Security: Uses the same security patterns as the audited void() function, with additional validation to ensure the partial amount doesn't exceed the capturable balance.

---

Key Features

• Two-Phase Payments: Separate authorization and capture for guaranteed merchant payments and management of real-world complexity
• Flexible Fee Structure: Configurable fee rates and recipients within predefined ranges
• Modular Token Collection: Support for multiple authorization methods (ERC-3009, Permit2, allowances, spend permissions)
• Built-in Protections: Time-based expiries, amount limits, and reclaim mechanisms
• Operator Model: Permissionless operators manage payment flows while remaining trust-minimized

Deployment Addresses

Base Mainnet & Base Sepolia

Contract	Address
AuthCaptureEscrow	0xBdEA0D1bcC5966192B070Fdf62aB4EF5b4420cff
ERC3009PaymentCollector	0x0E3dF9510de65469C4518D7843919c0b8C7A7757
Permit2PaymentCollector	0x992476B9Ee81d52a5BdA0622C333938D0Af0aB26
PreApprovalPaymentCollector	0x1b77ABd71FCD21fbe2398AE821Aa27D1E6B94bC6
SpendPermissionPaymentCollector	0x8d9F34934dc9619e5DC3Df27D0A40b4A744E7eAa
OperatorRefundCollector	0x934907bffd0901b6A21e398B9C53A4A38F02fa5d

Documentation

• Protocol Overview - Architecture, components, and payment lifecycle
• Security Analysis - Security features, risk assessment, and mitigation strategies
• Token Collectors Guide - Modular payment authorization methods
• Fee System - Comprehensive fee mechanics and examples
• Core Operations:
  • Authorize - Reserve funds for future capture
  • Capture - Transfer authorized funds to merchants
  • Charge - Immediate authorization and capture
  • Void - Cancel authorizations (operator)
  • Partial Void 🆕 - Cancel partial amount from authorization (operator, fork addition)
  • Reclaim - Recover expired authorizations (payer)
  • Refund - Return captured funds to payers

Development

# Install dependencies
forge install

# Run tests
forge test

# Deploy (example)
forge script script/Deploy.s.sol --rpc-url $RPC_URL --broadcast

License

MIT License - see LICENSE file for details.

Security Audits

Audited by Spearbit and Coinbase Protocol Security.

Audit	Date	Report
Coinbase Protocol Security audit 1	03/19/2025	Report
Coinbase Protocol Security audit 2	03/26/2025	Report
Spearbit audit 1	04/01/2025	Report
Coinbase Protocol Security audit 3	04/15/2025	Report
Spearbit audit 2	04/22/2025	Report