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.
On this page
Start here
- QuickstartCreate a Test key, make a checkout session, pay it as a buyer and confirm it from your server. About ten minutes.
- Add to an existing appThe short path for an app that already sells: keys, the webhook receiver, statuses, retries and what the API can't do yet.
- How payments workThe life of a payment from checkout to settlement, and what each status means for your order.
- Connect an AI assistantLet ChatGPT, Claude, Codex or your coding agent work on your business through the official MCP server. You sign in and confirm each change.
Using the dashboard without writing code? The Railbed user guide covers account setup, invoices, checkouts and everyday payment management.
How it fits together
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, usually 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.
- 01Create a checkout session
Your server sends the amount, currency and your order's reference.
POST /v1/checkout_sessions - 02The buyer pays by card
On Railbed's hosted page or your own screen, they choose a provider and pay on its page.
Provider checks may apply - 03Railbed confirms it
The money reaches your wallet, passes the settlement checks, and a signed event goes to your server.
payment.paid
Fulfil from a verified payment.paid or GET /v1/payments/:id. The buyer's return to your site is not proof of payment.
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 |
|---|---|---|
| Invoices and buy buttons | Nothing. Create invoices, 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 or a pop-up | Custom stores and apps that want Railbed's checkout page |
| Embedded checkout | A script tag and one element on your page | Sites that want the checkout inside their own 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,
"order_id": "ord_M4tQx8ZkP1vRn6WcLs2B",
"collect": null,
"canceled_at": null,
"checkout_id": null,
"plan_label": 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". Every session belongs to an order: send its items, totals and addresses as order, and your orders and customers appear in the dashboard and in every webhook.
A Full access key also creates invoices with line items, tax and a due date, saved checkout pages (pricing tables and widgets are made in the dashboard) and webhook endpoints. The API reference lists every endpoint, and the OpenAPI document and Postman collection describe the same API for your tools.
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 and the short checklist for going live.
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.
Building with an AI agent
Every page here has a Markdown copy (View as Markdown beside each page), and /docs/llms.txt summarises the whole API with the rules an integration must keep. A coding agent can get a Test key into your project without anyone pasting it, and start from a tested recipe for your stack: see For AI agents. To let an assistant work on your account rather than your code, connect it through the MCP server (https://mcp.railbed.io/mcp).