How it works
1
Your server creates the session
POST /api/merchant/checkout with the amount in USDC returns a checkout_url and session_id.2
Send your customer to the payment page
Redirect to
checkout_url. The page shows your business name, the amount, and the deposit address.3
Your customer pays
In USDC or USDT on any supported network, or with M-Pesa.
4
The payment is settled
The payment is converted and paid out. USDT payments add 30 to 50 seconds.
5
Your server is notified
A webhook is sent when the session is
completed, failed, or expired. You can also get the session.Pay with M-Pesa too
Every checkout session can offer M-Pesa, whatever your payout currency. The payment page shows a Crypto / M-Pesa switch when the amount is within M-Pesa limits. The customer enters their phone number and approves the payment prompt. The payment settles the same way as a crypto payment.Create a session
Request fields
The amount in USDC, greater than 0. Payable in USDC, USDT, or the KES equivalent with M-Pesa.
fiat or usdc. Overrides your account setting for this session. See settlement mode.Where to send the customer after payment. An
https URL, up to 2048 characters. See sending the customer back.Response (201)
Sending the customer back to your site
Setredirect_url to return the customer to your site after payment. Without it, the customer stays on the hosted page. Payment links don’t support redirects.
Where your customer lands
Two query parameters are appended to your URL:
So
https://yourstore.com/thanks?order=4821 becomes:
session_id or status, your values are kept and ours aren’t added.
When it happens
Oncompleted, the customer is redirected automatically a few seconds after the success screen. On failed or expired, a return link is shown instead.
Settlement mode
Sessions use your account’s settlement mode unlesssettlement_mode overrides it:
fiat: paid out in local currency.usdc: settled as USDC, without conversion.
usdc, settlement_chain sets the network. For networks other than Base, checkout.completed arrives before the USDC reaches that network. Wait for checkout.forwarded, or check forward on the session. If the move fails, settlement.forward_failed is sent and the USDC remains on Base.
Related endpoints, using your checkout API key:
GET /api/merchant/settlement: current mode, network, fee rate, and available networks.GET /api/merchant/balances: USDC balance per network.nullmeans the balance couldn’t be read.
Using external_id
Pass your order ID asexternal_id. It’s included in every webhook, so you can match payments to orders.

