Skip to main content
The Payment Router is a smart contract on Base that processes external wallet payments for Locus Checkout. When a buyer pays with MetaMask, Coinbase Wallet, or any other external wallet, the payment goes through this contract.

Why it exists

The Payment Router serves two purposes:
  • Instant detection — The contract emits a CheckoutPayment event 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

Session ID encoding

The sessionId 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

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.