Settlement
Settlement is the process of verifying a payment signature and executing the on-chain transfer. The facilitator handles this automatically.Overview
When a client submits a payment, the facilitator:- Verifies the signature is valid and the user has sufficient balance
- Settles by executing the on-chain transfer
Exact vs Escrow Settlement
Exact Scheme
Direct USDC Transfer
- ERC-3009
transferWithAuthorization - Direct transfer from payer to receiver
- Single on-chain transaction
Escrow Scheme
Swap + Transfer
- Permit2 signature (for non-USDC tokens)
- DEX swap to USDC
- Transfer USDC to receiver
Exact Scheme Settlement
For USDC payments using theexact scheme:
The facilitator calls transferWithAuthorization on the USDC contract using the payer’s signature. This is gasless for the payer.
Escrow Scheme Settlement (Swap)
For non-USDC payments using theescrow scheme:
The flow:
- Permit2 transfers the input token (e.g., WETH) to the SwapCollector contract
- SwapCollector executes the swap via a DEX aggregator (Uniswap, Paraswap, or OpenOcean)
- SwapCollector transfers the resulting USDC to the receiver
Signature Types
ERC-3009 (USDC)
Used for direct USDC transfers. The payer signs atransferWithAuthorization message:
Permit2 (Other Tokens)
Used for WETH, DAI, USDT transfers. The payer signs a Permit2 transfer:Nonce Management
Each payment has a unique nonce to prevent replay attacks.ERC-3009 Nonces
Derived deterministically from payment parameters:Permit2 Nonces
Also derived deterministically, ensuring each payment can only be settled once.Idempotency
The facilitator enforces idempotency:- Each signature can only be settled once
- Retrying with the same signature returns the cached result
- No risk of double-charging
Gas Costs
| Operation | Gas (approx) | Who Pays |
|---|---|---|
| ERC-3009 transfer | ~65k | Facilitator |
| Permit2 + swap | ~150k-250k | Facilitator |
Gas costs are covered by the facilitator. Users pay $0 in gas.
Settlement Response
After successful settlement, the facilitator returns:transaction field contains the on-chain transaction hash, which can be verified on a block explorer.
Error Handling
Common settlement errors:| Error | Cause | Solution |
|---|---|---|
insufficient_balance | Payer doesn’t have enough tokens | Check balance before signing |
signature_invalid | Signature verification failed | Ensure correct signing parameters |
nonce_already_used | Payment already settled | Idempotent - same result returned |
quote_expired | Swap quote expired | Retry with fresh quote |
swap_failed | DEX swap reverted | Check slippage settings |
Supported DEX Aggregators
For swap payments, the facilitator routes through:| Aggregator | Type | Notes |
|---|---|---|
| Uniswap UniversalRouter | Push | Best for simple swaps |
| Paraswap | Pull | Often best rates |
| OpenOcean | Pull | Good for exotic pairs |