# 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.

Source: https://railbed.io/docs/ · Updated: 2026-09-26 · Railbed by DeepWork developer docs

## 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.

- [Quickstart](https://railbed.io/docs/quickstart.md): Create a key, make a checkout session and take a simulated payment in about ten minutes.
- [How payments work](https://railbed.io/docs/how-it-works.md): The life of a payment, from checkout to settlement, and what each status means for your order.
- [API reference](https://railbed.io/docs/api.md): Authentication, idempotency, pagination, errors and every endpoint, with examples.
- [Webhooks](https://railbed.io/docs/webhooks.md): Signed 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](https://railbed.io/docs/guides/no-code.md) | 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](https://railbed.io/docs/guides/woocommerce.md) | Nothing. Install the plugin and connect it with a key and a webhook secret | WordPress stores |
| [Hosted checkout](https://railbed.io/docs/guides/hosted-checkout.md) | One API call per order, then a redirect | Custom stores and apps that want Railbed's checkout page |
| [Your own checkout](https://railbed.io/docs/guides/custom-checkout.md) | 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](https://railbed.io/docs/guides/fulfilment.md) 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.

Create a checkout session:

```bash
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"
  }'
```

Response · response 201 Created:

```json
{
  "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](https://railbed.io/docs/testing.md) 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.

> [!TIP]
> Building with an AI assistant? Every page here has a Markdown copy, and [/docs/llms.txt](https://railbed.io/docs/llms.txt) summarises the whole API. See [For AI agents](https://railbed.io/docs/agents.md).