# Railbed developer docs

> Railbed is a card checkout for online merchants that settles every sale as USDC on Polygon to a wallet the merchant controls. These docs cover the REST API (checkout sessions and payments), signed webhooks, test mode, hosted and merchant-built checkouts, embeds and the WooCommerce plugin. Every page below is also available as Markdown.

Essentials for building against Railbed:

- API base URL: `https://pay.railbed.io/v1`. JSON over HTTPS. Authenticate every call from your server with `Authorization: Bearer <secret key>`.
- Keys decide the mode: `rb_test_…` keys work only with simulated Test payments (no money moves), `rb_live_…` keys take real card payments. Create and revoke keys in the dashboard under Developers (https://app.railbed.io/developers). Never put a secret key in browser or mobile code; there is no publishable key.
- The flow: create a checkout session (`POST /v1/checkout_sessions`), send the buyer to its `url` (or start it with `POST /v1/checkout_sessions/:id/start` and render the returned providers in your own checkout), then fulfil only when the payment is `paid`, confirmed by a signed `payment.paid` webhook or by `GET /v1/payments/:id`. Never fulfil from the buyer's return to `success_url`.
- Send an `Idempotency-Key` header (1–120 printable ASCII characters, remembered for 24 hours) on every create so a retried request never makes a second payment.
- Money is a decimal string (`"49.00"`, from 1.00 to 100000.00); currencies are USD, EUR, GBP, CAD and AUD. `/v1` timestamps are Unix seconds; in webhooks the event's `created` is Unix seconds and the payment object uses camelCase with millisecond timestamps. Payment ids look like `pay_…` and are both the session id and the payment id.
- Payment statuses: `open` and `pending` (wait), `paid` (fulfil, once), `held` (money arrived but failed a check; never fulfil automatically, the merchant reviews it), `failed` (Test mode decline), `expired` (can still become `paid` or `held` if money arrives late).
- Webhooks are signed: `Railbed-Signature: t=<unix seconds>,v1=<hex HMAC-SHA256 of "<t>.<raw body>">` keyed with the endpoint's whole `whsec_…` secret. Verify against the raw body, reject timestamps more than 5 minutes off, dedupe on the event `id`, answer 2xx within 10 seconds. Failed deliveries are retried 1m, 5m, 30m, 2h, 6h and 12h after each failure.
- Webhook events: `payment.started`, `payment.paid`, `payment.held`, `payment.updated`, `payment.failed`, `payment.expired`, `payment.canceled`, and `ping` for tests. Ignore types you don't handle; events can arrive more than once and out of order.
- Errors are `{"error": {"code", "message", "field"?}}`; branch on `code` and the HTTP status, never the message. 429 responses carry `Retry-After: 60`; limits are about 120 requests and 12 session starts a minute per account.
- Test mode: `POST /v1/payments/:id/simulate` with `outcome` `paid`, `underpaid` or `failed` settles a started Test payment through the same checks and webhooks as a live one.
- Card details are always entered on a licensed card provider's page, never on Railbed's pages or yours. There are no refund, subscription or event-list endpoints; refunds are sent from the merchant's wallet.

## Get started

- [Railbed developer docs](https://railbed.io/docs/index.md): 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.
- [Quickstart](https://railbed.io/docs/quickstart.md): Take your first payment in Test mode in about ten minutes. Create a secret key, create a checkout session, pay it as a buyer, and confirm it from your server.
- [How payments work](https://railbed.io/docs/how-it-works.md): The life of a Railbed payment, from the checkout to the USDC in your wallet, and what each status means for the order behind it.
- [Testing](https://railbed.io/docs/testing.md): Test mode simulates payments end to end, with no card charged and no money moved. Make payments succeed, fall short or be declined on demand, send sample webhook events, and go live with confidence.

## Guides

- [Hosted checkout](https://railbed.io/docs/guides/hosted-checkout.md): Create a checkout session for each order on your server, send the buyer to Railbed's hosted page, and bring them back to your store once they've paid.
- [Your own checkout](https://railbed.io/docs/guides/custom-checkout.md): Keep buyers in your app or game. Your server starts the checkout session and gets the card providers that can take the payment; your screen shows them, and the buyer pays on the chosen provider's page.
- [Fulfil orders safely](https://railbed.io/docs/guides/fulfilment.md): Deliver each order exactly once, only for money that really arrived. The checks that keep fulfilment correct through retries, duplicate events, late payments and reviews.
- [Payment links and buy buttons](https://railbed.io/docs/guides/no-code.md): Take payments without writing server code. Create payment links, checkout pages and pricing tables in the dashboard, and add a buy button or an embedded checkout to any website with two lines of HTML.
- [WooCommerce](https://railbed.io/docs/guides/woocommerce.md): Add Railbed card checkout to a WordPress store with the Railbed for WooCommerce plugin. Orders complete from verified payments, with no code.

## API reference

- [API reference](https://railbed.io/docs/api.md): The Railbed REST API. JSON over HTTPS, one secret key per server, idempotent creates, cursor pagination and plain error codes.
- [Checkout sessions](https://railbed.io/docs/api/checkout-sessions.md): A checkout session is one payment for one order. Create it on your server, send the buyer to its page or start it for your own checkout, and read its payment to fulfil.
- [Payments](https://railbed.io/docs/api/payments.md): A payment is what a checkout session became. Read it to fulfil orders, list payments to reconcile, and simulate outcomes in Test mode.
- [Errors](https://railbed.io/docs/api/errors.md): Every error the Railbed API returns, with its HTTP status, what caused it and what to do next.

## Webhooks

- [Webhooks](https://railbed.io/docs/webhooks.md): Railbed sends a signed HTTPS request to your server when a payment starts, settles, is held, expires or is canceled. How endpoints, deliveries, retries and the delivery log work.
- [Event types](https://railbed.io/docs/webhooks/events.md): Every webhook event Railbed sends, when it's sent, what the payment looks like at that moment, and the full payload reference.
- [Verify signatures](https://railbed.io/docs/webhooks/signatures.md): Prove each webhook came from Railbed and wasn't changed. The signing scheme, verification code in six languages, how to get the raw body in common frameworks, and a test vector.

## Resources

- [Build with AI agents](https://railbed.io/docs/agents.md): Everything in these docs is available to AI assistants and coding agents: llms.txt, a Markdown copy of every page, a structured index, and WebMCP tools on railbed.io and in the dashboard.

## API endpoints

- [`POST /v1/checkout_sessions`](https://railbed.io/docs/api/checkout-sessions.md#create-a-checkout-session): Create a checkout session
- [`GET /v1/checkout_sessions/:id`](https://railbed.io/docs/api/checkout-sessions.md#retrieve-a-checkout-session): Retrieve a checkout session
- [`POST /v1/checkout_sessions/:id/start`](https://railbed.io/docs/api/checkout-sessions.md#start-a-checkout-session): Start a checkout session
- [`GET /v1/payments/:id`](https://railbed.io/docs/api/payments.md#retrieve-a-payment): Retrieve a payment
- [`GET /v1/payments`](https://railbed.io/docs/api/payments.md#list-payments): List payments
- [`POST /v1/payments/:id/simulate`](https://railbed.io/docs/api/payments.md#simulate-a-payment): Simulate a payment

## Webhook events

- [`payment.started`](https://railbed.io/docs/webhooks/events.md#payment-started): The buyer entered their email and was given a way to pay: Railbed assigned the payment's deposit address and locked the fee and the order's USD value. The payment is still open (it becomes pending when the buyer reaches a provider), and provider is usually still null.
- [`payment.paid`](https://railbed.io/docs/webhooks/events.md#payment-paid): The money arrived and passed Railbed's checks: at least 90% of the order's value in a dollar coin and, from the processor's signed notice, the right deposit address, your wallet in the payout and a transaction never used before. Or you accepted a held payment as paid. This is the event to fulfil from.
- [`payment.held`](https://railbed.io/docs/webhooks/events.md#payment-held): Money arrived but failed a check, most often because less arrived than 90% of the order's value. Don't fulfil. The payment waits for you in the dashboard.
- [`payment.updated`](https://railbed.io/docs/webhooks/events.md#payment-updated): A paid payment's settlement details arrived after it was confirmed: txidIn, valueCoin, coin and merchantReceived are now filled in. The status stays paid. Update your records; there's nothing to fulfil again.
- [`payment.failed`](https://railbed.io/docs/webhooks/events.md#payment-failed): The payment was declined. Today this is sent in Test mode only, when you simulate a decline: live card providers don't report declines, so a live payment the buyer never completes ends as payment.expired. Let the buyer try again with a new session.
- [`payment.expired`](https://railbed.io/docs/webhooks/events.md#payment-expired): Nobody paid before the payment's expiresAt: 24 hours for API sessions, or the lifetime chosen for a payment link. It's sent within five minutes of expiry.
- [`payment.canceled`](https://railbed.io/docs/webhooks/events.md#payment-canceled): You canceled a payment link in the dashboard before anyone had gone to a provider. The payment's status is expired and canceledAt is set.
- [`ping`](https://railbed.io/docs/webhooks/events.md#ping): Sent only when you choose Send test event and pick ping (Test endpoints) or Send ping (Live endpoints). data.payment is null. Use it to check the address, the secret and your signature code.

## Optional

- [All of these docs in one file](https://railbed.io/docs/llms-full.txt)
- [Railbed company overview (llms.txt)](https://railbed.io/llms.txt)
- [Dashboard: create API keys and webhook endpoints](https://app.railbed.io/developers)
- [Sign up](https://app.railbed.io/signup)