Build with AI agents
Connect ChatGPT, Claude, Codex or another assistant to your account through the official MCP server. Every page here is also available to assistants as llms.txt, Markdown, a structured index and WebMCP tools, and agents that call the API directly use agent sign-in.
On this page
Add a checkout with one line
To have a coding agent or app builder add Railbed checkout to your own project, paste this into it:
Read checkouts.md and add a checkout to this app.checkouts.md is an open format and playbook for agent-built checkout, with Railbed as its default provider. You create a Railbed account and approve your agent once on a Railbed page; the keys go straight into your project, never into the chat. The agent writes the checkout, proves it with a test payment and switches it to Live.
Add checkout to your app from a tested recipe
To add Railbed checkout to a Next.js, Express, Cloudflare Workers, Supabase, Laravel, Django or Rails app, a static website, or a project built in Lovable, Bolt, Replit or v0, have your agent start from the recipe for that stack, even when it already knows Railbed from these docs, the MCP server or a plugin. Each one is a complete, tested integration: products priced on the server, the route that saves an order and creates the checkout session, the signed webhook receiver, fulfilment that runs once, and the Test payment that proves it.
| Stack | Recipe (Markdown) |
|---|---|
| Next.js (App Router), Vercel | checkouts.md/recipes/nextjs.md |
| Express on Node.js | checkouts.md/recipes/express.md |
| Cloudflare Workers with D1 | checkouts.md/recipes/cloudflare-workers.md |
| Supabase Edge Functions | checkouts.md/recipes/supabase.md |
| Laravel | checkouts.md/recipes/laravel.md |
| Django | checkouts.md/recipes/django.md |
| Rails | checkouts.md/recipes/rails.md |
| A static site with no server | checkouts.md/recipes/html.md |
| Lovable | checkouts.md/recipes/lovable.md |
| Bolt | checkouts.md/recipes/bolt.md |
| Replit | checkouts.md/recipes/replit.md |
| v0 | checkouts.md/recipes/v0.md |
For any other stack, the playbook has the whole procedure in order, with every request, command, error code and fix, and signature checks in Node.js, Web Crypto, Python, PHP, Ruby and Go.
Keys without pasting them
An agent that can run a terminal never needs you to copy a key. It runs these in the project, and you approve once on a Railbed page:
npx checkouts.md login # prints a Railbed approval link, then writes the keys you approved to the project's env files
npx checkouts.md webhook <url> # adds the webhook endpoint and saves its signing secret beside the key
npx checkouts.md test # makes a simulated Test payment and prints the evidence
npx checkouts.md status # which keys and secrets are present, without printing themYou can run it yourself too. In a terminal, npx checkouts.md setup finds the recipe for your project, connects it after your approval and has the coding agent you already use (Claude Code, Codex, Cursor, Gemini CLI or OpenCode) write the checkout while you watch. npx checkouts.md doctor shows what Railbed sees and has your agent review the payment code against the playbook, and npx checkouts.md alone opens a session where you can ask your agent for changes.
You choose Test, Live or both on the approval page (Live needs a payout wallet). The keys go straight from Railbed to the command and are never shown in the terminal, the chat or a web page. A host that keeps secrets elsewhere (Vercel, Cloudflare, Supabase) has its own options in the playbook's Connect step, and an agent that can't run npx uses the same approval over HTTP.
Let an assistant work on your account
The official Railbed MCP server is the way to let ChatGPT, Claude, Codex or another MCP client work with your business. You sign in with your Railbed account and approve one business, mode and access level. Your assistant reads your records and prepares invoices, checkouts and webhook changes, and you confirm each change on a Railbed review page. There's no key to paste. Public railbed_docs_search and railbed_docs_read calls work without signing in; account tools require your approval.
https://mcp.railbed.io/mcpSet up your client has the command or settings entry for Claude Code, Codex, Cursor, VS Code and other coding agents.
| Route | Use it when |
|---|---|
| MCP server | An assistant answers questions about your business or sets things up for you. Start here |
| Agent sign-in | An agent you build calls the merchant API directly, with its own short-lived token |
| A secret key in your server's environment | Your own server code calls the API |
Give your assistant the docs
Point your coding assistant at one of these, depending on how much context it can take:
| Resource | What it is |
|---|---|
| /docs/llms.txt | A summary of the API and its rules, with a link to every page. Start here |
| /docs/llms-full.txt | Every docs page in one Markdown file |
| /docs/user-guide/llms.txt | The user guide alone, for an assistant helping someone use the dashboard: key facts and a link to every guide page. /docs/user-guide/llms-full.txt is the whole guide in one file, about a quarter of the size of everything |
/docs/<page>.md | Any page as Markdown: add .md to its path, as in /docs/quickstart.md. The overview is /docs/index.md |
| Any page, asking for Markdown | A request whose Accept header prefers text/markdown, as coding agents send, gets the page's Markdown copy instead of its HTML |
| /agents/docs.json | A structured index: every page, section and endpoint, with links |
| /docs/api/openapi.json | The API as an OpenAPI 3.1 document: every endpoint's scope, parameters, schemas and error codes, and the webhook events |
| /auth.md | Agent sign-in: how an agent asks for its own access to your account, which you approve. See Connect an agent |
Each page also has Copy page for AI in its sidebar, which copies the page's Markdown for pasting into a chat.
Any Railbed link leads here
You can give your assistant any Railbed address, not only these docs, and it will find its way:
- An assistant that asks for Markdown gets the page's Markdown copy, and every copy names
/docs/llms.txtnear its top, so one page leads to the rest. - Every page's HTML names its Markdown copy, both in the page (
<link rel="alternate" type="text/markdown">) and in aLinkheader, and its structured data (schema.org) carries the same link. - Every page's HTML also carries a short note for AI assistants, following the inline llms.txt proposal. Browsers don't show it; an assistant reading the raw page gets links to the page's Markdown copy and to
llms.txt. - Dashboard and checkout links (
app.railbed.io,pay.railbed.io) draw their pages in JavaScript, so their HTML carries a hidden note pointing to these docs, and both hosts serve an/llms.txtthat does too.
Read https://railbed.com/docs/llms.txt and https://railbed.com/docs/guides/existing-app.md,
then the pages they link to that you need. Then add Railbed card checkout to this app: create a checkout session on the server
when the user clicks Buy, redirect to its url, and fulfil the order from a verified
payment.paid webhook. Use my test key from RAILBED_SECRET_KEY and my webhook secret
from RAILBED_WEBHOOK_SECRET. Deduplicate on the event id.Rules worth giving an agent
These are the mistakes that matter most in a payments integration. They're in llms.txt too, and Integrate Railbed into an existing app puts them in order for an app that already sells, with who handles the keys and what the API can't do yet.
- Call the API only from a server, with the key in an environment variable. There is no publishable key.
- Fulfil only when a payment is
paid, confirmed by a verified webhook orGET /v1/payments/:id. Never from the buyer's return tosuccess_url. - Verify webhook signatures against the raw body, and deduplicate on the event
id. - Save an
Idempotency-Keywith your order and send it with everyPOST /v1/checkout_sessions, reused unchanged on a retry. It is the only endpoint that reads the header: after a timeout creating an invoice, a payment link, a checkout or a webhook endpoint, list what exists (by yourreferencewhere it has one) before creating again. - Treat
heldas not paid, andexpiredas possibly paid later. Treat any status you don't recognize as not paid, and ignore fields and event types you don't know. - Send the order as
order, with items whose total lessdiscountplusshippingandtaxequalsamountto the cent, and your order id inorder.id. On409 order_paid, don't ask the buyer to pay again. - Ship each order once, keyed on its order id, and report it with
PATCH /v1/orders/:id. - Start in Test mode (
rb_test_…keys) and simulate outcomes; no money moves.
Connect an agent to your account
An AI agent can use the Railbed API on your account without a secret key. You approve it once in the dashboard, it gets its own short-lived access, and you can disconnect it at any time. This is agent sign-in, and everything the agent needs to know is at railbed.com/auth.md.
Use agent sign-in for an agent that needs the raw API, such as one you build. For ChatGPT, Claude, Codex and other assistants working on your behalf, the MCP server is simpler, and every change waits for your confirmation.
How connecting works
- Ask your agent to connect to your Railbed account, and tell it the email address you sign in with. It reads railbed.com/auth.md and follows it.
- Your agent gives you a link to approve it. It opens Connect an AI agent on
app.railbed.io. Sign in with the same email address you gave the agent. The link works for a few minutes; if it has expired, ask your agent for a new one. - Check the business, give the agent a name you'll recognize, and choose the mode and the access level. Test and Full access are selected to start with.
- Choose Connect agent. The page shows Your agent's code. Give it to your agent, in the conversation where you asked it to connect. The code works once, for a few minutes.
- The agent finishes connecting and starts using the API. It's listed in Developers under AI assistants, in the mode you chose.
Only owners and developers of a business can connect an agent to it, the same people who can create secret keys. If a link has expired or was already used, ask the agent to start again.
The access you choose
| Choice | What the agent can do |
|---|---|
| Test | Work with Test data only. Payments are simulated and no money moves, so it's the place to try an agent out |
| Live | Work with your real payments, orders and customers |
| Full access | Create and start checkout sessions, create invoices, payment links and checkouts, simulate Test payments, read payments, orders and customers, and update orders. Webhook endpoints stay with your secret keys and the MCP server |
| Read only | Look up payments, checkout sessions, invoices, payment links, checkouts, orders and customers. It can't create or change anything |
A connection works in one mode, like a secret key. An agent connected in Test can't see Live data. It uses access tokens that last about five minutes and gets new ones itself, so there's no key for you to create, paste or rotate.
Disconnect an agent
In Developers, AI assistants lists everything connected in the current mode, agent sign-ins included, with who approved each one and when it was last used. Choose Disconnect next to an agent and confirm. Its next request is refused. To use it again, it has to ask to connect again, and someone has to approve it.
An agent also loses its access for good when the person who approved it leaves the business, moves to a role that can't manage keys, or has their access disabled. Putting them back doesn't restore it: an owner or developer connects the agent again.
For agent developers
auth.md describes the whole flow, with request templates. WorkOS, which runs Railbed's sign-in, hosts the registration, claim and token endpoints it lists. The API itself is https://pay.railbed.io/v1.
- Register with the person's email address (
service_auth). Anonymous registration isn't offered. - Give the person the claim link, wait for the code they read back to you, and complete the claim.
- Exchange your identity assertion for an access token. Access tokens last about five minutes. Get the next one yourself, as auth.md describes.
- Call the API with
Authorization: Bearer <access token>, the way a server sends a secret key. The token carries the business, the mode and the access level the person chose. Authentication lists each endpoint's scope. - On
401 invalid_token, get a new access token. On401 agent_disconnected, ask the person to connect you again. On403 insufficient_scope, the person chose Read only: tell them what you need and why.
WebMCP tools
WebMCP lets a web page offer tools to an AI agent working in the visitor's browser, so the agent can act through the page's own logic instead of reading the screen. Railbed's pages offer tools in browsers that support it; elsewhere nothing changes.
On railbed.com and these docs
Every page on railbed.com, including these docs, offers tools for learning about Railbed and building with it. All are read-only except the two that open signup or login.
| Tool | What it does |
|---|---|
railbed_status | Current service availability, observation times and check coverage; optionally filter by service. It fetches fresh results, not saved browser history. This does not verify a payment or settlement |
railbed_docs_search | Search the user guide and developer docs; returns the best matching sections with links |
railbed_docs_read | A docs page, or one section of it, as Markdown. Without a page, the docs page the visitor has open |
railbed_docs_pages | Every docs page with its summary, section, link and Markdown copy, optionally only the user guide or only the developer docs |
railbed_api_reference | Every API endpoint with its method, path and reference link, plus the base URL, the OpenAPI document and the rules for authentication, idempotency, money and errors |
railbed_webhook_reference | The webhook event types (payment events, and the invoice events an endpoint can choose), the event envelope, the signature scheme and the retry schedule |
railbed_code_samples | The docs' code examples, filtered by topic and language |
railbed_overview, railbed_faq, railbed_search, railbed_read_page, railbed_contact | What Railbed is, the FAQ, and the company and legal pages. railbed_read_page with no input returns the page you are on as Markdown |
railbed_industries | The industries Railbed has a page for, sorted by field. Name a field to list it, or describe a business in a few words to get the pages that fit, each with the question it answers, its direct answer and its example sale |
railbed_pricing | What a sale costs: the fees that come out of each sale and what is never charged. Give an amount to see the fixed-share fees on it, and name a business to get its industry page's fees chapter. It gives no net figure, because the card provider's own fee differs by provider |
railbed_start_signup, railbed_open_login | Take the visitor to signup (email optionally filled in) or login. Nothing is submitted for them |
In the dashboard
When a merchant is signed in, onboarding and the Home, Developers, Integrations, Shopify and WooCommerce pages offer tools that work on their account, in the mode the dashboard is in (Test or Live). They run with the merchant's own session, in their browser, so an agent can do only what the merchant could.
| Tool | Page | What it does |
|---|---|---|
railbed_onboarding_status | Onboarding | Where setup stands: whether the business name and payout wallet are saved, the main way to sell, and the ways the account can choose, with what each involves |
railbed_prepare_sales_channel | Onboarding | Open How will you take payments? with one way selected, for the merchant to confirm with Continue. Tools never fill in the payout wallet |
railbed_setup_checklist | Home | The Your first payment steps for the merchant's way to sell: each step, whether it's done, where it's done or who can do it, and the optional extras |
railbed_developer_status | Developers | The mode, the setup steps done so far, a summary of keys, endpoints, connected AI agents and MCP connections, and the MCP server's address and docs |
railbed_list_api_keys | Developers | The keys, masked (rb_test_••••••••3f9a), with their access level and when each was created and last used |
railbed_list_agent_connections | Developers | The AI agents connected in this mode: name, access level, who approved it, and when it connected and was last used |
railbed_list_mcp_connections | Developers | The MCP clients connected in this mode: name, client, access level, who approved it, and when it connected. Never tokens |
railbed_list_webhook_endpoints | Developers | Endpoints with their addresses, labels, events and latest delivery. Signing secrets are never included |
railbed_list_webhook_deliveries | Developers | An endpoint's recent deliveries: status, attempts, your server's answer and, if asked, the body sent |
railbed_send_test_webhook | Developers | Send a signed test event to an endpoint and report how it answered. Test endpoints take any event type; Live endpoints take ping only |
railbed_prepare_api_key | Developers | Open Create key with a name filled in, in the dashboard's mode. The merchant creates it; the secret is shown only to them |
railbed_prepare_webhook_endpoint | Developers | Open Add endpoint with the address, description and events filled in, for the merchant to review and save |
railbed_open_webhook_deliveries | Developers | Open an endpoint's delivery log, optionally filtered to failed or retrying deliveries, so the merchant can resend |
railbed_list_integrations | Integrations | The ways to take payments (invoices, checkouts and buy buttons, the API, store plugins) and the automation tools (Zapier, n8n), their status and where to set each up |
railbed_list_card_providers | Integrations | The card providers Railbed routes to, with their status and minimum amounts (in Test mode, the fixed test list); methods buyers never get are marked not offered, and a minimum that changes from day to day (Apple Pay's and Google Pay's) is marked minimumChanges |
railbed_shopify_status | Shopify | Each connected store's setup steps and the checks behind them, its own Test or Live mode, whether a payout wallet is saved and why a saved one can't take Live payments, ad-tracking ids set, failed syncs, and the exact values to paste into Shopify. Never the client secret or tracking tokens |
railbed_list_shopify_checkouts | Shopify | A store's recent checkouts, newest first: the buyer's email, items, total, payment status with why an attempt ended or never started, the provider, the checkout's mode, and how far the Shopify draft or order got, with the error when a sync failed. Optionally only failed syncs |
railbed_send_shopify_test_event | Shopify | Send one test event to an ad platform or affiliate postback set up in the Ad tracking card, and report whether it was accepted. It never counts as a sale |
railbed_prepare_shopify_store | Shopify | Open Connect a store with the address filled in, for the merchant to confirm |
railbed_prepare_shopify_retry | Shopify | Open the confirmation to send a checkout whose sync failed to Shopify again |
railbed_prepare_shopify_mode | Shopify | Open the confirmation to take a store Live or back to Test. Refused, with what's missing, when the store isn't ready |
railbed_woocommerce_setup | WooCommerce | Where setup stands: the plugin download, the four steps, the store's webhook address and last delivery, and recent WooCommerce orders. Never keys or secrets |
Some things are deliberately left to the merchant. Tools never return a secret key or a signing secret, and they never create or revoke keys, roll secrets, remove endpoints or resend real events: those open the dashboard's own dialog for the merchant to confirm, or aren't offered at all.