Quickstart

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.

On this page

Before you start

You need a Railbed account (sign up) and a terminal. Everything below runs in Test mode: no card is charged and no money moves. The same code works in Live mode with a live key.

1. Create a secret key

In the dashboard, turn on Test mode (open the business block at the top of the sidebar), open Developers and choose Create key. The dialog's title, Create a Test secret key, confirms the mode. Name it after the server that will use it, for example "Store backend", and keep Checkout API as the purpose and Full access (a Read only key can't create checkouts). The key starts with rb_test_ and is shown once: copy it into your server's environment.

Using an AI coding agent? Have it run npx checkouts.md login in your project: you approve once on a Railbed page and the key goes straight into the project's environment, never into the chat (Keys without pasting them), and it can start from the tested recipe for your stack. An agent that calls the API for you, rather than for your app, uses agent sign-in instead.

Your server's environment
export RAILBED_SECRET_KEY="rb_test_…"

2. Create a checkout session

A checkout session is one payment for one order: a fixed amount, a currency, and your order's reference. Send an Idempotency-Key so a retried request can never create a second payment.

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",
    "customer_email": "buyer@example.com",
    "success_url": "https://yourstore.com/thanks?order={REFERENCE}"
  }'

The response is the new session. Save its id (pay_…) with your order.

Response
{
  "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": "buyer@example.com",
  "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
}
201 Created

3. Pay as a buyer

Only your team's browsers can pay a Test page, so first, in Developers under API keys, choose Turn on Test payments in this browser (once, in either mode; it lasts seven days). Then open the session's url in that browser. Continue with the email, pick a card provider and choose Pay. In Test mode the provider's page is replaced by Railbed's test provider, where Simulate successful payment stands in for entering a card. (You can also simulate from your server.) The checkout tab then shows the payment as paid and takes the buyer to your success_url, with {REFERENCE} filled in.

4. Confirm the payment from your server

The redirect is for the buyer's comfort, not proof of payment. Confirm it from your server, with the same key:

curl https://pay.railbed.io/v1/payments/pay_7AAiYH0Ykt11ED4hmfiN \
  -H "Authorization: Bearer $RAILBED_SECRET_KEY"
Response
{
  "id": "pay_7AAiYH0Ykt11ED4hmfiN",
  "object": "payment",
  "url": "https://pay.railbed.io/p/pay_7AAiYH0Ykt11ED4hmfiN",
  "status": "paid",
  "livemode": false,
  "amount": "49.00",
  "currency": "USD",
  "description": "Pro Membership",
  "reference": "order_1042",
  "customer_email": "buyer@example.com",
  "created": 1790380525,
  "expires_at": 1790466925,
  "started_at": 1790380611,
  "metadata": null,
  "order_id": "ord_M4tQx8ZkP1vRn6WcLs2B",
  "collect": null,
  "canceled_at": null,
  "checkout_id": null,
  "plan_label": null,
  "paid_at": 1790381342,
  "provider": "stripe",
  "hold_reason": null,
  "hold_acceptable": false,
  "method": "card",
  "settlement": {
    "network": null,
    "coin": "polygon_usdc",
    "value_coin": "47.53",
    "merchant_received": "44.915850",
    "merchant_received_usd": "44.915850",
    "txid_in": "0x1111111111111111111111111111111111111111111111111111111111111111",
    "txid_out": "0x2222222222222222222222222222222222222222222222222222222222222222",
    "payout_wallet": "0x3333333333333333333333333333333333333333"
  },
  "invoice_id": null,
  "tip": "0.00"
}
200 OK

Check that status is paid and that the id, amount, currency and reference match the order you saved, then fulfil it once.

5. Get told instead of asking

Polling works, but webhooks tell you the moment something happens. In Developers, choose Add endpoint and enter your server's https:// address (while you build on your own computer, use a tunnel). Copy the signing secret now (revealing it later asks you to sign in again), then choose Send test event to see exactly what your server receives. Webhooks covers the events and verifying signatures.

Next

Updated · This page as Markdown