Skip to main content
A checkout session is a single payment request created from your server. It returns a hosted payment page URL, and a webhook is sent when the payment completes. For a shareable link with no code, use a payment link.

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

number
required
The amount in USDC, greater than 0. Payable in USDC, USDT, or the KES equivalent with M-Pesa.
string
Shown on the payment page.
string
Your own reference, such as an order ID. Included in every webhook.
string
Used for the customer’s receipt.
string
fiat or usdc. Overrides your account setting for this session. See settlement mode.
string
BASE, ARB, AVAX, OP, ETH, or MATIC. Only used when settlement_mode is usdc.
string
Where to send the customer after payment. An https URL, up to 2048 characters. See sending the customer back.

Response (201)

Sessions expire after 30 minutes. Create one when the customer is ready to pay.

Sending the customer back to your site

Set redirect_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:
If your URL already contains session_id or status, your values are kept and ours aren’t added.

When it happens

On completed, the customer is redirected automatically a few seconds after the success screen. On failed or expired, a return link is shown instead.
Don’t treat status=completed in the URL as proof of payment: anyone can edit it. Fulfil orders only after the webhook or a server-side status check.

Settlement mode

Sessions use your account’s settlement mode unless settlement_mode overrides it:
  • fiat: paid out in local currency.
  • usdc: settled as USDC, without conversion.
A session’s mode is fixed at creation. With 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. null means the balance couldn’t be read.

Using external_id

Pass your order ID as external_id. It’s included in every webhook, so you can match payments to orders.

Check session status

No API key is required.

Status values

Full example

See Webhook verification for the signature check.