# Railbed documentation

> Railbed is a card checkout for online merchants that settles every sale as USDC on Polygon to a wallet the merchant controls. Start with the user guide for account setup, payment links, checkouts, pricing tables, your wallet and everyday payment management. The developer docs cover the REST API, signed webhooks and custom integrations. Every page below is also available as Markdown; visual examples include text descriptions.

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.
- Each key has an access level: Full access (every endpoint; the default) or Read only (scopes `payments:read`, `orders:read`, `customers:read`). Every endpoint needs one scope; a call outside the key's access level gets `403 insufficient_scope`, naming the scope.
- AI agents acting for a merchant get their own access through agent sign-in: read https://railbed.com/auth.md and follow it. Register with the merchant's email address, give them the claim link, complete the claim with the code they read back, then exchange your identity assertion for an access token (about five minutes) and renew it yourself. Send it as `Authorization: Bearer <access token>`. It carries the business, mode and access level the merchant chose. `401 invalid_token`: get a new token; `401 agent_disconnected`: ask the merchant to connect you again. Never ask a merchant to paste a secret key into a chat.
- Every 401 from the API carries `WWW-Authenticate: Bearer resource_metadata="https://pay.railbed.io/.well-known/oauth-protected-resource/v1"`, the API's protected resource metadata (RFC 9728).
- 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.
- Orders and customers: send `order` (items, discount, shipping, tax, addresses; items − discount + shipping + tax must equal `amount`) and `customer` (name, phone, your customer id) with a session. Every session belongs to an order (`ord_…`); each email is one customer (`cus_…`). Send your order id as `order.id` so a retry joins the same order; a session for an order that's already paid answers `409 order_paid`. Read them with `GET /v1/orders`, `GET /v1/orders/:id` and `GET /v1/customers/:id`; set fulfilment with `PATCH /v1/orders/:id`. An order is `paid` only when its paid payments cover its `total`.
- Webhook events: `payment.started`, `payment.paid`, `payment.held`, `payment.updated`, `payment.failed`, `payment.expired`, `payment.canceled`, and `ping` for tests. Each payment event carries `data.payment`, `data.order` (with up to 50 items) and `data.customer`. 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.

## Start here

- [Your guide to getting paid](https://railbed.com/docs/user-guide.md): Set up your business, take your first card payment, and follow every sale to your wallet. Start here, with or without a website.
- [Set up your account](https://railbed.com/docs/user-guide/getting-started.md): Go from a new account to a checkout you can share, with the right business details and payout wallet in place.
- [Test and Live mode](https://railbed.com/docs/user-guide/test-and-live.md): Practice the buyer experience without moving money, then prepare a separate checkout for real customers.

## Take payments

- [Create and share a payment link](https://railbed.com/docs/user-guide/payment-links.md): Request one payment for one customer. Add an invoice reference, share a link or QR code, and track it until it is paid.
- [Create a reusable checkout](https://railbed.com/docs/user-guide/checkout-pages.md): Sell one product at one price with a page you can share again and again. Every buyer gets a separate payment.
- [Offer plans with a pricing table](https://railbed.com/docs/user-guide/pricing-tables.md): Present up to four packages side by side, highlight one recommendation, and let buyers choose the right one.
- [Add Railbed to your website](https://railbed.com/docs/user-guide/widgets-and-buttons.md): Keep customers on your site while they choose what to buy. Copy a small HTML snippet; Railbed handles the checkout.
- [What your customer sees](https://railbed.com/docs/user-guide/buyer-experience.md): Understand the card checkout, provider choice and return journey so you can confidently guide a customer through payment.
- [Accept crypto payments](https://railbed.com/docs/user-guide/crypto-payments.md): Let buyers pay in USDC or USDT from their own wallet, beside card. It's off until you turn it on, and the money goes to your payout wallet.

## Orders and customers

- [Manage orders and fulfilment](https://railbed.com/docs/user-guide/orders.md): See what a customer bought, review their payment attempts, and keep track of what still needs to be delivered.
- [Understand your customers](https://railbed.com/docs/user-guide/customers.md): See a customer's order history, contact details and spending. Keep a private note and manage the personal data saved in Railbed.
- [Find records across Railbed](https://railbed.com/docs/user-guide/search.md): Jump to an order, customer, payment or setting from anywhere in your dashboard. Search by a name, amount, email or record ID.

## Manage your money

- [Find and understand a payment](https://railbed.com/docs/user-guide/payments.md): Search across your payment links, checkouts and API orders. See what happened, what arrived and what to do next.
- [Review a held payment](https://railbed.com/docs/user-guide/held-payments.md): Understand why a payment is being reviewed or underpaid, and when you can choose to accept the amount that arrived.
- [Understand your wallet and settlement](https://railbed.com/docs/user-guide/wallet-and-settlement.md): Know where the money goes, how received totals are calculated, and why your checkout price and wallet balance can differ.

## Your business

- [Make Railbed your own](https://railbed.com/docs/user-guide/branding-and-settings.md): Put your business name, logo and support details on checkout, and keep your account settings accurate.
- [Connect Railbed to your store](https://railbed.com/docs/user-guide/integrations.md): Choose the connection that fits your business, from Shopify or a WordPress plugin to a checkout built by your developer.
- [Use Railbed on your phone](https://railbed.com/docs/user-guide/mobile.md): Manage payments in your browser, or add the dashboard to your Home Screen for quicker access.

## Help and reference

- [Find your next step](https://railbed.com/docs/user-guide/troubleshooting.md): Start with the symptom, check the current payment state, and take the next action without losing track of the order.
- [Railbed, in plain language](https://railbed.com/docs/user-guide/glossary.md): A short reference for the words you will see in checkout, the dashboard and your payment records.

## Get started

- [Railbed developer docs](https://railbed.com/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.com/docs/quickstart.md): Take your first payment in Test mode. Create a secret key, create a checkout session, pay it as a buyer, and confirm it from your server.
- [How payments work](https://railbed.com/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.com/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.com/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.com/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.com/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.com/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.com/docs/guides/woocommerce.md): Add Railbed card checkout to a WordPress store with the Railbed for WooCommerce plugin. Orders complete from verified payments, and their items, customers and fulfilment appear in Railbed, with no code.

## API reference

- [API reference](https://railbed.com/docs/api.md): The Railbed REST API. JSON over HTTPS, secret keys for your servers and access tokens for connected agents, scopes, idempotent creates, cursor pagination and plain error codes.
- [Checkout sessions](https://railbed.com/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.com/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.
- [Orders](https://railbed.com/docs/api/orders.md): An order is what a buyer tried to buy, with its items, totals, addresses and customer. Every checkout session belongs to one. Read orders to fulfil them, and report fulfilment, cancellations and refunds back from your store.
- [Customers](https://railbed.com/docs/api/customers.md): A customer is one buyer's email address in one mode, with the contact details and addresses their orders brought. Read customers to see who bought what, and find one by email.
- [Errors](https://railbed.com/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.com/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.com/docs/webhooks/events.md): Every webhook event Railbed sends, when it's sent, what the payment, order and customer look like at that moment, and the full payload reference.
- [Verify signatures](https://railbed.com/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.com/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. An agent can also connect to your account through agent sign-in, with the access you choose.

## API endpoints

- [`POST /v1/checkout_sessions`](https://railbed.com/docs/api/checkout-sessions.md#create-a-checkout-session): Create a checkout session
- [`GET /v1/checkout_sessions/:id`](https://railbed.com/docs/api/checkout-sessions.md#retrieve-a-checkout-session): Retrieve a checkout session
- [`POST /v1/checkout_sessions/:id/start`](https://railbed.com/docs/api/checkout-sessions.md#start-a-checkout-session): Start a checkout session
- [`GET /v1/payments/:id`](https://railbed.com/docs/api/payments.md#retrieve-a-payment): Retrieve a payment
- [`GET /v1/payments`](https://railbed.com/docs/api/payments.md#list-payments): List payments
- [`POST /v1/payments/:id/simulate`](https://railbed.com/docs/api/payments.md#simulate-a-payment): Simulate a payment
- [`GET /v1/orders/:id`](https://railbed.com/docs/api/orders.md#retrieve-an-order): Retrieve an order
- [`GET /v1/orders`](https://railbed.com/docs/api/orders.md#list-orders): List orders
- [`PATCH /v1/orders/:id`](https://railbed.com/docs/api/orders.md#update-an-order): Update an order
- [`POST /v1/orders/:id/events`](https://railbed.com/docs/api/orders.md#report-a-cancellation-or-refund): Report a cancellation or refund
- [`GET /v1/customers/:id`](https://railbed.com/docs/api/customers.md#retrieve-a-customer): Retrieve a customer
- [`GET /v1/customers`](https://railbed.com/docs/api/customers.md#list-customers): List customers

## Webhook events

- [`payment.started`](https://railbed.com/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.com/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.com/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.com/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.com/docs/webhooks/events.md#payment-failed): The payment reached a terminal failure. Today this is sent in Test mode only, for an explicit API simulation with outcome: "failed". The Test provider's declined-card action keeps the payment open and sends no failed event. Live card providers don't report declines, so a live payment the buyer never completes ends as payment.expired. After a terminal failure, let the buyer try again with a new session.
- [`payment.expired`](https://railbed.com/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.com/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.com/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, data.order and data.customer are null. Use it to check the address, the secret and your signature code.

## Agent sign-in

- [auth.md](https://railbed.com/auth.md): how an AI agent gets its own access to a merchant's account, approved by the merchant. Start here when you need to call the API for someone
- [Connect an agent to your account](https://railbed.com/docs/agents.md#connect-an-agent): the same flow from the merchant's side, the access they can choose and disconnecting
- [Authentication and scopes](https://railbed.com/docs/api.md#authentication): secret keys, agent access tokens, each endpoint's scope and discovery

## Optional

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