Why it exists
The Payment Router serves two purposes:- Instant detection — The contract emits a
CheckoutPaymentevent with the session ID, so Locus detects payments immediately without scanning all USDC transfers. - Session binding — Each payment is tied to a specific checkout session on-chain, creating a verifiable link between the payment and the order.
Contract addresses
Payment Router
USDC
How external wallet payments work
External wallet payments require two transactions from the buyer:1
Approve USDC spending
The buyer approves the Payment Router to transfer the exact payment amount of USDC on their behalf.
2
Call pay() on the Payment Router
The buyer calls
pay() with the session ID, seller address, and amount. The contract transfers USDC from the buyer to the seller and emits a CheckoutPayment event.3
Locus detects the event
Locus listens for
CheckoutPayment events and automatically marks the corresponding checkout session as PAID. The merchant receives a webhook.The checkout page handles both transactions automatically — the buyer just connects their wallet and clicks “Pay”. The approve + pay steps are presented as a guided flow.
Contract interface
IPaymentRouter.sol
IPaymentRouter.sol
Session ID encoding
ThesessionId parameter is a bytes32 encoding of the checkout session UUID. The encoding is: remove dashes from the UUID hex string, left-align, and zero-pad to 32 bytes.
USDC amounts
USDC has 6 decimals. Amounts are in base units:$25.00 = 25000000.
Verify on BaseScan
You can verify any checkout payment on BaseScan:1
Open the contract
Go to the Payment Router on BaseScan.
2
View events
Click the Events tab. Look for
CheckoutPayment events — each one shows the sessionId, from (buyer), to (seller), and amount.3
Check a specific session
Under the Read Contract tab, call
sessionPaid(bytes32) with the encoded session ID. Returns true if the session has been paid on-chain.