Railbed developer docs
Take card payments that settle as USDC to a wallet you control. Create checkouts from your server, send buyers to a hosted page or build your own, and fulfil orders from signed webhooks.
What you can build
Railbed gives your store a card checkout that never holds your money. A buyer pays by card through a licensed on-ramp provider, and the sale settles as USDC on Polygon straight to your own wallet. Your integration decides where the buyer pays and when an order counts as paid; Railbed handles the checkout, the provider hand-off and the settlement checks.
- QuickstartCreate a key, make a checkout session and take a simulated payment in about ten minutes.
- How payments workThe life of a payment, from checkout to settlement, and what each status means for your order.
- API referenceAuthentication, idempotency, pagination, errors and every endpoint, with examples.
- WebhooksSigned events for every step of a payment, retries, and the delivery log.
Choose an integration
Every integration ends the same way: the buyer pays on a provider's page and the money settles to your wallet. They differ in how much you build.
| Integration | You build | Best for |
|---|---|---|
| Payment links and buy buttons | Nothing. Create links, checkout pages and pricing tables in the dashboard; paste a buy button into any site | Invoices, one product, getting started this afternoon |
| WooCommerce | Nothing. Install the plugin and connect it with a key and a webhook secret | WordPress stores |
| Hosted checkout | One API call per order, then a redirect | Custom stores and apps that want Railbed's checkout page |
| Your own checkout | The whole buyer screen: your server starts the session and shows the card providers | Apps and games with their own purchase flow |
Whichever you choose, fulfil orders the same way: from a verified payment.paid webhook or an authenticated status check. Fulfil orders safely shows how.
The API at a glance
The API is JSON over HTTPS at https://pay.railbed.io/v1. Your server authenticates with a secret key; buyers never see it.
curl https://pay.railbed.io/v1/checkout_sessions \
-H "Authorization: Bearer $RAILBED_SECRET_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: order_1042" \
-d '{
"amount": "49.00",
"currency": "USD",
"description": "Pro Membership",
"reference": "order_1042"
}'{
"id": "pay_7AAiYH0Ykt11ED4hmfiN",
"object": "checkout_session",
"url": "https://pay.railbed.io/p/pay_7AAiYH0Ykt11ED4hmfiN",
"status": "open",
"livemode": false,
"amount": "49.00",
"currency": "USD",
"description": "Pro Membership",
"reference": "order_1042",
"customer_email": null,
"created": 1790380525,
"expires_at": 1790466925,
"started_at": null,
"metadata": null
}Send the buyer to url. When they pay, Railbed sends a signed payment.paid event to your server, and GET /v1/payments/pay_… reports "status": "paid".
Test mode and live mode
Every account has two separate modes. Test mode simulates payments: no card is charged, no money moves, and you can make a payment succeed, fall short or be declined on demand. Live mode takes real card payments. Keys, webhook endpoints, checkouts and payments belong to one mode, and a test key can never touch a live payment. Build and test everything in Test mode first; Testing covers the tools.
What Railbed doesn't do
Card details are always entered on the provider's own page, never on Railbed's pages or yours, so your integration stays out of card-data scope. Railbed can't reverse a settled payment: refunds are sent from your wallet, and card disputes are handled by the provider that charged the card. There are no subscription, refund or event-list endpoints today.