Developers
Keys, the IP allowlist, webhook verification and a quickstart in curl and Node.
Checkout for your site and app
Get paid inside your own product.
Create a checkout session from your server and send your customer to the hosted page it returns. The page handles the coin, the network and a one-time address, sends your customer back to you, and tells your server what happened through signed webhooks.
One request to startSigned webhooks0.8% to collect
Step 3 of 4, Pay: the customer is asked to send 81.13 USDC on Base to an address made for this payment, valid for 60 minutes.
Illustrative. Harbourview Markets Ltd is a sample business. Press a step to see that screen.
How it works
From order to settled in three steps.
Your server starts the session, the hosted page takes the payment, and your systems hear the outcome. No SDK and no plugin: two HTTPS requests and a webhook handler.
-
1
Create a checkout session
Call the payments endpoint with your publishable key: the amount, your customer’s email, your own reference and where to send them afterwards. You get back a payment URL.
-
2
Your customer pays on the hosted page
They pick the coin and network, then pay by transfer from any wallet or exchange, or straight from a browser wallet. The address is made for this payment and stays open for 60 minutes.
-
3
Hear back, and settle
Signed webhooks tell your server when the payment is seen and when it completes, your customer returns to your callback URL, and the money settles to the destination you chose.
Features
A complete checkout, nothing to host.
The page, the addresses and the watching of the chain are ours to run. Your side is one request to start, one to verify, and a webhook handler.
An address for every payment
Each session gets its own deposit address, so a payment arrives already matched to one order and nothing pools.
60 minutes to pay
The address stays open for 60 minutes, with a countdown on the page. If nothing arrives in time, the session expires.
Transfer or browser wallet
Customers pay from any wallet or exchange by QR or address, or approve it in a browser wallet that fills in the amount and network.
Five plain statuses
Pending, processing, completed, expired and failed. Check any session with your secret key, by payment id or by your own reference.
Back to your site
After paying, your customer returns to your callback URL with the payment id and your reference added. If it fails, to your failure URL.
Signed webhooks
payment.received, payment.completed and payment.failed, signed with HMAC-SHA256 and retried up to 7 times over about 31 hours.
Settles where you choose
Checkout and API has its own routing rule: your bank in local currency, your treasury, or a wallet you hold.
Test sessions on testnets
Test keys make test checkouts on Base Sepolia and Celo Sepolia, kept apart from live and settled to wallets only.
The lifecycle
Every session, start to finish.
Follow one checkout session through its statuses and see exactly what your server receives at each step. Change the ending to see an address run out, or a payment fail.
Checkout sessionORDER10482 · ₦125,000.00
14:02
Session created
Your server calls POST /api/v1/payments and gets the payment URL.
Pending14:02
Address made
The customer chose USDC on Base. The address is valid until 15:02.
Pending14:09
Payment seen
81.13 USDC arrived on Base. Your server receives payment.received.
Processing14:10
Completed
Settled to your destination. Your server receives payment.completed and the customer returns to your site.
Completed
Statuses
- PendingCreated, waiting for the customer to pay.
- ProcessingSeen on the network, being settled.
- CompletedSettled to your destination.
- ExpiredThe 60 minutes ran out before anything arrived.
- FailedThe payment could not be completed.
Read the status any time from your server, with your secret key: GET /api/v1/payments/:paymentId/verify, or by your own reference.
Webhook to your serverpayment.completed
POST /hooks/chainpal
X-ChainPal-Signature: v1=6330e786…
X-ChainPal-Timestamp: 1791724200
{
"type": "payment.completed",
"environment": "live",
"data": {
"paymentId": "6708f3c2a1e4b7d9c0f12a34",
"clientReference": "ORDER10482",
"fiatAmount": "125000.00",
"currency": "NGN",
"cryptoAmount": "81.13",
"token": "USDC",
"network": "base",
"status": "completed"
}
}Customer returns to https://harbourview.example/paid?paymentId=…&reference=ORDER10482
Illustrative. Field names, statuses and events are the API’s own; the values are a sample for Harbourview Markets Ltd.
Works with
Part of one platform.
Checkout shares its settlement rules, records and intelligence with everything else you run on ChainPal.
Payouts
Route checkout payments to your bank in local currency, or keep them in stablecoins.
Payment links
Sell without writing code, on the same hosted pay pages your customers know.
Aria
Ask about abandoned checkouts and stuck payments, and see the records behind each answer.
Questions
Checkout, answered.
Planning an integration? Write to help@chainpal.org and we will help you plan it.
Do we need an SDK or a plugin?
No. The API is plain REST over HTTPS, so anything that can send a request works. Our developer page has examples in curl and in Node using only its built-in crypto module, and the full reference is in the API docs.
How long does a customer have to pay?
The address is valid for 60 minutes, and the page counts it down. If nothing arrives in that time the session ends as expired and your server receives payment.failed, so you can release the order or offer a new checkout.
Which coins and networks can customers pay with?
USDC and USDT, on Base, BNB Chain, Celo and Polygon, depending on your market. The checkout only offers what your business can be paid on. Each payment is at least $1, and at most between $1,600 and $5,000 depending on the country.
How do we confirm a payment before fulfilling an order?
Verify it from your server with your secret key, by payment id or by your own reference, or act on a webhook whose HMAC-SHA256 signature you have checked. Treat the return to your site as a courtesy to your customer, not as proof of payment.
What stops one order being charged twice?
Your reference. It has to be unique, so the same order cannot open a second checkout. Use your own order number and every payment maps back to exactly one order in your system.
Does ChainPal hold the money in between?
No. Each payment lands on its own address and moves straight on to the destination you set for Checkout and API: your bank account in local currency, your treasury, or a wallet you hold. There is no ChainPal balance in between.
Open for business
Build on rails you control.
Open an account, choose where each product settles and take your first payment in digital dollars. No setup fee, and no balance held on your behalf.