API reference

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.

On this page

Base URL

Base URL
https://pay.railbed.io/v1

Every request uses HTTPS. You create checkout sessions, one for each attempt at paying, and read their payments to fulfil orders. A session and its payment share one id (pay_…). Each session belongs to an order, which holds what was bought and where it ships, and each order to a customer. Payment links ask one payer for one amount, invoices bill a customer with lines, tax, a due date and part payments, and checkouts are reusable pages a buy button opens. Webhook endpoints let your code, or a tool such as n8n or Zapier, subscribe to events. Payment methods list the card providers your buyers can pay with.

EndpointWhat it does
POST /v1/checkout_sessionsCreate a checkout session
GET /v1/checkout_sessions/:idRetrieve a checkout session
POST /v1/checkout_sessions/:id/startStart a checkout session and get its card providers
POST /v1/checkout_sessions/:id/cancelCancel a checkout session nobody has started paying
GET /v1/payments/:idRetrieve a payment
GET /v1/paymentsList payments
POST /v1/payments/:id/simulateSimulate a payment (Test mode)
GET /v1/payment_methodsList payment methods: the card providers, which you turned off, and what Smart Routing would offer for an amount
GET /v1/payout_walletsList payout wallets: the other wallets a payment link or invoice can pay
POST /v1/payment_linksCreate a payment link
GET /v1/payment_links/:idRetrieve a payment link
GET /v1/payment_linksList payment links
POST /v1/payment_links/:id/cancelCancel a payment link
POST /v1/invoicesCreate an invoice: a draft, issued, or emailed to the customer
GET /v1/invoices/:idRetrieve an invoice
PATCH /v1/invoices/:idUpdate an invoice
GET /v1/invoicesList invoices, payment links among them
POST /v1/invoices/:id/issueIssue an invoice without emailing it
POST /v1/invoices/:id/sendSend an invoice by email, with its PDF
POST /v1/invoices/:id/voidVoid an invoice
DELETE /v1/invoices/:idDelete a draft invoice
GET /v1/invoices/:id/pdfDownload an invoice PDF
POST /v1/checkoutsCreate a checkout page
GET /v1/checkouts/:idRetrieve a checkout
GET /v1/checkoutsList checkouts
GET /v1/orders/:idRetrieve an order
GET /v1/ordersList orders by status, fulfilment or date, or find one by your store's order id
PATCH /v1/orders/:idUpdate an order's fulfilment
POST /v1/orders/:id/eventsReport a cancellation or refund on the order's timeline
GET /v1/customers/:idRetrieve a customer
GET /v1/customersList customers, or find one by email
POST /v1/webhook_endpointsCreate a webhook endpoint and get its signing secret
GET /v1/webhook_endpoints/:idRetrieve a webhook endpoint
GET /v1/webhook_endpointsList webhook endpoints
PATCH /v1/webhook_endpoints/:idUpdate a webhook endpoint's events or description
DELETE /v1/webhook_endpoints/:idDelete a webhook endpoint

OpenAPI and Postman

The same API is published as an OpenAPI 3.1 document: every endpoint with the scope it needs, its parameters, its request and response schemas and its error codes, and every webhook event with its Railbed-Signature header. Load it into an API tool or a client generator. Its examples are the ones these pages show.

To try the API in Postman, import the Railbed collection. Set its secret_key variable to a Test key (rb_test_…) in a Postman environment rather than in the collection, so the key isn't shared with it. Its base_url variable already points at the API.

Authentication

Send a bearer token on every request: a secret key from your server, or the access token of an AI agent you've connected to your account. The API treats both the same way.

An authenticated request
curl "https://pay.railbed.io/v1/payments?limit=1" \
  -H "Authorization: Bearer rb_test_…"

The credential decides everything about the request: which account it belongs to, whether it works on Test or Live data, and which endpoints it may use. Nothing else can switch the mode. An account that has paused taking payments still answers every request except creating and starting sessions, creating payment links and checkouts, and creating, changing, issuing and sending invoices, which get 409 commerce_paused. A suspended or archived account still answers every read and list, and refuses anything that creates or changes with 403 merchant_read_only. Its secret keys, connected agents and webhook endpoints can still be revoked in the dashboard, so a leaked key can always be cut off.

Secret keys

Keys are created and revoked in Developers, and each is shown once, when it's created. A key is made in the mode the dashboard is in: the dialog says Create a Test secret key or Create a Live secret key. Until the business has a full-access Test key, the Live dialog also offers Create a Test key instead; that key is listed under Test mode. rb_test_… keys see only Test data and rb_live_… keys only Live data. A missing, malformed or revoked key gets 401 invalid_api_key. Revoking a key also removes the webhook endpoints it added.

A secret key is rb_live_ or rb_test_ followed by 43 URL-safe characters (A–Z, a–z, 0–9, - and _): 51 characters in all, with no spaces, padding or line breaks. If your configuration checks a key before using it, check the prefix (it also tells you the mode) and that character set, and store the key exactly as copied, without surrounding spaces or a trailing newline.

Each key has an access level, chosen when you create it:

Access levelScopesWhat the key can do
Full access (the default)All seven scopesUse every endpoint
Read onlypayments:read, orders:read, customers:readRetrieve and list payments, checkout sessions, payment links, invoices (and their PDFs), checkouts, payment methods, orders and customers. Nothing that creates or changes, and no webhook endpoints

Keys created before access levels existed have full access. WooCommerce keys always do, because the plugin creates checkout sessions, but they can't manage webhook endpoints: the plugin never does, so its key doesn't need to.

Agent access tokens

An AI agent gets access through agent sign-in. It reads railbed.com/auth.md, a person who can manage keys approves it in the dashboard, and the agent receives its own access tokens. Each lasts about five minutes, and the agent gets the next one itself from the token endpoint that auth.md describes. A token carries the business, the mode and the access level (Full access or Read only) the person chose.

An agent's request
curl "https://pay.railbed.io/v1/payments?limit=1" \
  -H "Authorization: Bearer $ACCESS_TOKEN"
ResponseCauseWhat the agent should do
401 invalid_tokenThe token expired, is malformed or wasn't issued for RailbedGet a new access token
401 agent_disconnectedThe agent was disconnected in the dashboard, or the person who connected it no longer manages keys for the businessAsk the person to connect it again

Scopes

Every endpoint needs one scope. A key or agent whose access level doesn't include it gets 403 insufficient_scope, and the message names the scope.

ScopeEndpoints
payments:readGET /v1/payments, GET /v1/payments/:id, GET /v1/checkout_sessions/:id, GET /v1/payment_links, GET /v1/payment_links/:id, GET /v1/invoices, GET /v1/invoices/:id, GET /v1/invoices/:id/pdf, GET /v1/checkouts, GET /v1/checkouts/:id, GET /v1/payment_methods, GET /v1/payout_wallets
checkouts:writePOST /v1/checkout_sessions, POST /v1/checkout_sessions/:id/start, POST /v1/checkout_sessions/:id/cancel, POST /v1/payments/:id/simulate, POST /v1/payment_links, POST /v1/payment_links/:id/cancel, POST /v1/invoices, PATCH /v1/invoices/:id, DELETE /v1/invoices/:id, POST /v1/invoices/:id/issue, POST /v1/invoices/:id/send, POST /v1/invoices/:id/void, POST /v1/checkouts
orders:readGET /v1/orders, GET /v1/orders/:id
orders:writePATCH /v1/orders/:id, POST /v1/orders/:id/events
customers:readGET /v1/customers, GET /v1/customers/:id
webhooks:readGET /v1/webhook_endpoints, GET /v1/webhook_endpoints/:id
webhooks:writePOST /v1/webhook_endpoints, PATCH /v1/webhook_endpoints/:id, DELETE /v1/webhook_endpoints/:id

Connected AI agents never have the two webhook scopes, and nor do WooCommerce keys: manage webhook endpoints with a secret key made for the API.

Discovery

Every 401 from the API tells an agent where to find out how to get access, in a WWW-Authenticate header (RFC 9728):

A request without a credential
WWW-Authenticate: Bearer resource_metadata="https://pay.railbed.io/.well-known/oauth-protected-resource/v1"
401 Unauthorized

When a credential was sent and refused, the header adds error="invalid_token". A 403 insufficient_scope carries error="insufficient_scope", scope="…", naming the scope the endpoint needs.

The protected resource metadata names the API, its authorization server, the scopes and these docs. The same document is also at https://pay.railbed.io/.well-known/oauth-protected-resource. An agent starting out should read auth.md, which takes it through the rest.

The protected resource metadata
{
  "resource": "https://pay.railbed.io/v1",
  "resource_name": "Railbed API",
  "authorization_servers": ["https://astounding-resonance-81.authkit.app"],
  "scopes_supported": ["payments:read", "checkouts:write", "orders:read", "orders:write", "customers:read", "webhooks:read", "webhooks:write"],
  "bearer_methods_supported": ["header"],
  "resource_documentation": "https://railbed.com/docs/api/"
}
200 OK

Requests and responses

  • Send JSON bodies with Content-Type: application/json, up to 64 KiB. Other types get 415, larger bodies 413, and bodies that aren't a JSON object 400 invalid_json.
  • Responses are JSON and are never cached (Cache-Control: no-store).
  • Unknown fields in a request are ignored, with two exceptions that answer 400 and name the field, so a misspelt one never passes quietly: invoices (unknown_field) and the collect object (invalid_collect). Build against the fields documented here.
  • null for an optional field reads as leaving it out. On Update an invoice, null clears the field.
  • For an authenticated request to a known path with the wrong HTTP method, the API returns 405 method_not_allowed with an Allow header listing supported methods. Authentication and access checks still run first.
  • Money is a decimal string, never a number, so no amount is ever rounded in transit. Prices have two places ("49.00"); settlement amounts in the coin can have more (merchant_received has six, or eight for Bitcoin, Litecoin, Bitcoin Cash, Zcash and Monero).
  • Currencies are USD, EUR, GBP, CAD, AUD, INR and SEK.
  • Timestamps in the API are Unix seconds. (A webhook event's created is Unix seconds too, but the payment, order, customer and invoice inside it use milliseconds; see event payloads.)
  • Ids are prefixed: pay_ for sessions, payment links and payments, in_ for invoices, chk_ for checkouts, ord_ for orders, cus_ for customers, we_ for webhook endpoints, evt_ for webhook events.

Text and metadata

Free text in description, reference, and the documented order/customer text fields has its control characters, direction markers and overrides removed, is normalized to Unicode NFC, then trimmed. Each field’s limit counts Unicode code points after that normalization; the maximum itself is allowed. For example, description and reference allow exactly 120. A required description must still contain text. An optional field that becomes blank is null.

Metadata follows the same control removal and NFC normalization. Keys are also trimmed; values keep ordinary leading and trailing spaces. Up to 20 keys are allowed, with 1–40 code points per key and 0–500 per string value. Blank keys, two keys that become identical, or keys beginning with __ after normalization return 400 invalid_metadata. ZWJ and ZWNJ script joiners are preserved. Store the normalized values returned by the API when comparing later responses.

Idempotency

POST /v1/checkout_sessions and POST /v1/invoices honor Idempotency-Key. To retry that create safely, send the header: a value unique to the order attempt, 1–120 printable ASCII characters. Save it with your order before the first call.

SituationResponse
First request with a key201 and the new session
Same key, same validated body (a retry)200 and the same session, with its current status
Same key, different validated body409 idempotency_conflict. Retrying won't help: use a new key for a different order
Same key and body while the first request is still runningThe same session: one request gets 201, the others 200. Rarely, 409 idempotency_in_progress with a Retry-After header: send the same request again with the same key after that many seconds
Key longer than 120 characters, blank, or with other characters400 invalid_idempotency_key (never truncated)

Keys are scoped to your account and the key's mode, not to one secret key, so a retry sent with a replacement key returns the same session. They're remembered for 24 hours; after that the same key creates a new session. Save the exact body with the key and send it unchanged on a retry: the fields that count include the buyer's email, the return URLs and, when sent, order and customer, and for a session from a saved checkout the checkout, plan and option you sent rather than the price they gave. Bodies are compared after validation and normalization; metadata key order does not matter. For example, "49" and "49.00" represent the same amount, and equivalent normalized text or return URLs do not cause a conflict. Metadata value spacing remains meaningful. For invoices, the same rules hold, except that the body is compared as you sent it (in any field order), so send a retry byte for byte. Other endpoints ignore this header; their own retry and event-id rules still apply. Without the header, every create makes a new session, and your reference alone doesn't prevent duplicates.

Pagination

The list endpoints (GET /v1/payments, GET /v1/payment_links, GET /v1/invoices, GET /v1/checkouts, GET /v1/orders, GET /v1/customers and GET /v1/webhook_endpoints) return the newest first, up to limit (1–100, default 20) at a time:

A page
{
  "data": [
    {
      "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": {
        "user_id": "player_1042"
      },
      "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"
    },
    {
      "id": "pay_Kx81mQv2PzR0dT7eWcYa",
      "object": "payment",
      "url": "https://pay.railbed.io/p/pay_Kx81mQv2PzR0dT7eWcYa",
      "status": "held",
      "livemode": false,
      "amount": "49.00",
      "currency": "USD",
      "description": "Pro Membership",
      "reference": "order_1042",
      "customer_email": "buyer@example.com",
      "created": 1790380465,
      "expires_at": 1790466865,
      "started_at": 1790380611,
      "metadata": {
        "user_id": "player_1042"
      },
      "order_id": "ord_Rx2Np5VqT9sW4mLb7ZaC",
      "collect": null,
      "canceled_at": null,
      "checkout_id": null,
      "plan_label": null,
      "paid_at": null,
      "provider": "stripe",
      "hold_reason": "The provider sent 24.50 USDC, below 85% of the order’s 49.00 USD value.",
      "hold_acceptable": true,
      "method": "card",
      "settlement": {
        "network": null,
        "coin": "polygon_usdc",
        "value_coin": "24.50",
        "merchant_received": "23.152500",
        "merchant_received_usd": "23.152500",
        "txid_in": "0x1111111111111111111111111111111111111111111111111111111111111111",
        "txid_out": "0x2222222222222222222222222222222222222222222222222222222222222222",
        "payout_wallet": "0x3333333333333333333333333333333333333333"
      },
      "invoice_id": null,
      "tip": "0.00"
    }
  ],
  "has_more": true,
  "next_cursor": "pay_Kx81mQv2PzR0dT7eWcYa"
}
200 OK

Pass next_cursor as starting_after to get the next page, until next_cursor is null. The order is stable, even for objects created in the same second. A limit outside 1–100, or a cursor that isn't an object from the same list in this mode, gets 400 rather than a silent first page.

Rate limits

Each account can make about 120 requests a minute per mode across all its keys, and 12 session starts a minute per mode. Each connected AI agent has its own 120 a minute, so an agent can't use up your servers' budget; its live session starts still count toward the account's Live budget of 12. Test activity never consumes the Live budget. Requests with a missing or invalid secret key are limited to about 60 a minute from one address. Over the limit, requests get 429 rate_limited with a Retry-After: 60 header. Every 429 includes Retry-After; use its value before retrying. Queue requests on your server and back off with a little randomness; never make a request per animation frame or per page view.

The limits protect the service rather than set a quota: they're enforced per region and are approximate, so plan well below them. Responses don't carry rate-limit headers today; Retry-After on a 429 is the signal. Check unfinished orders in the background suggests a budget for polling and reconciliation.

Errors

Errors use HTTP status codes and a JSON body with a stable code, a sentence for people, and sometimes the field at fault:

An error
{
  "error": {
    "code": "invalid_amount",
    "message": "amount must be a decimal string between \"1.00\" and \"100000.00\".",
    "field": "amount"
  }
}
400 Bad Request

Branch on code and the status, never on message, which may be reworded. Errors lists every code.

Versioning

The API is v1. Changes within v1 only add things: new fields in responses, new optional request fields, new error codes, new webhook event types. A change that could break an integration would come as a new version. Write your integration so additions can't break it:

  • Fields. Ignore fields you don't know, in API responses and in webhook events.
  • Event types. Acknowledge an event type you don't handle with 2xx and ignore it.
  • Error codes. Branch on the codes you know, and handle any other by its HTTP status (Errors): retry an unknown 5xx, wait for Retry-After on any 429, and treat any other unknown 4xx as a request to fix.
  • Statuses. Fulfil only on paid. Treat any status you don't recognize as not paid, and keep reconciling the payment as you would an open one.

Updated · This page as Markdown