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
https://pay.railbed.io/v1Every 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.
| Endpoint | What it does |
|---|---|
POST /v1/checkout_sessions | Create a checkout session |
GET /v1/checkout_sessions/:id | Retrieve a checkout session |
POST /v1/checkout_sessions/:id/start | Start a checkout session and get its card providers |
POST /v1/checkout_sessions/:id/cancel | Cancel a checkout session nobody has started paying |
GET /v1/payments/:id | Retrieve a payment |
GET /v1/payments | List payments |
POST /v1/payments/:id/simulate | Simulate a payment (Test mode) |
GET /v1/payment_methods | List payment methods: the card providers, which you turned off, and what Smart Routing would offer for an amount |
GET /v1/payout_wallets | List payout wallets: the other wallets a payment link or invoice can pay |
POST /v1/payment_links | Create a payment link |
GET /v1/payment_links/:id | Retrieve a payment link |
GET /v1/payment_links | List payment links |
POST /v1/payment_links/:id/cancel | Cancel a payment link |
POST /v1/invoices | Create an invoice: a draft, issued, or emailed to the customer |
GET /v1/invoices/:id | Retrieve an invoice |
PATCH /v1/invoices/:id | Update an invoice |
GET /v1/invoices | List invoices, payment links among them |
POST /v1/invoices/:id/issue | Issue an invoice without emailing it |
POST /v1/invoices/:id/send | Send an invoice by email, with its PDF |
POST /v1/invoices/:id/void | Void an invoice |
DELETE /v1/invoices/:id | Delete a draft invoice |
GET /v1/invoices/:id/pdf | Download an invoice PDF |
POST /v1/checkouts | Create a checkout page |
GET /v1/checkouts/:id | Retrieve a checkout |
GET /v1/checkouts | List checkouts |
GET /v1/orders/:id | Retrieve an order |
GET /v1/orders | List orders by status, fulfilment or date, or find one by your store's order id |
PATCH /v1/orders/:id | Update an order's fulfilment |
POST /v1/orders/:id/events | Report a cancellation or refund on the order's timeline |
GET /v1/customers/:id | Retrieve a customer |
GET /v1/customers | List customers, or find one by email |
POST /v1/webhook_endpoints | Create a webhook endpoint and get its signing secret |
GET /v1/webhook_endpoints/:id | Retrieve a webhook endpoint |
GET /v1/webhook_endpoints | List webhook endpoints |
PATCH /v1/webhook_endpoints/:id | Update a webhook endpoint's events or description |
DELETE /v1/webhook_endpoints/:id | Delete 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.
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 level | Scopes | What the key can do |
|---|---|---|
| Full access (the default) | All seven scopes | Use every endpoint |
| Read only | payments:read, orders:read, customers:read | Retrieve 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.
curl "https://pay.railbed.io/v1/payments?limit=1" \
-H "Authorization: Bearer $ACCESS_TOKEN"| Response | Cause | What the agent should do |
|---|---|---|
401 invalid_token | The token expired, is malformed or wasn't issued for Railbed | Get a new access token |
401 agent_disconnected | The agent was disconnected in the dashboard, or the person who connected it no longer manages keys for the business | Ask 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.
| Scope | Endpoints |
|---|---|
payments:read | GET /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:write | POST /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:read | GET /v1/orders, GET /v1/orders/:id |
orders:write | PATCH /v1/orders/:id, POST /v1/orders/:id/events |
customers:read | GET /v1/customers, GET /v1/customers/:id |
webhooks:read | GET /v1/webhook_endpoints, GET /v1/webhook_endpoints/:id |
webhooks:write | POST /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):
WWW-Authenticate: Bearer resource_metadata="https://pay.railbed.io/.well-known/oauth-protected-resource/v1"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.
{
"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/"
}Requests and responses
- Send JSON bodies with
Content-Type: application/json, up to 64 KiB. Other types get415, larger bodies413, and bodies that aren't a JSON object400 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
400and name the field, so a misspelt one never passes quietly: invoices (unknown_field) and thecollectobject (invalid_collect). Build against the fields documented here. nullfor an optional field reads as leaving it out. On Update an invoice,nullclears the field.- For an authenticated request to a known path with the wrong HTTP method, the API returns
405 method_not_allowedwith anAllowheader 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_receivedhas six, or eight for Bitcoin, Litecoin, Bitcoin Cash, Zcash and Monero). - Currencies are
USD,EUR,GBP,CAD,AUD,INRandSEK. - Timestamps in the API are Unix seconds. (A webhook event's
createdis 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.
| Situation | Response |
|---|---|
| First request with a key | 201 and the new session |
| Same key, same validated body (a retry) | 200 and the same session, with its current status |
| Same key, different validated body | 409 idempotency_conflict. Retrying won't help: use a new key for a different order |
| Same key and body while the first request is still running | The 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 characters | 400 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:
{
"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"
}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:
{
"error": {
"code": "invalid_amount",
"message": "amount must be a decimal string between \"1.00\" and \"100000.00\".",
"field": "amount"
}
}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
2xxand ignore it. - Error codes. Branch on the codes you know, and handle any other by its HTTP status (Errors): retry an unknown
5xx, wait forRetry-Afteron any429, and treat any other unknown4xxas 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 anopenone.