{ "product": "Railbed", "apiBase": "https://pay.railbed.io/v1", "llms": "https://railbed.com/docs/llms.txt", "authMd": "https://railbed.com/auth.md", "sections": [ { "title": "Start here", "pages": [ "user-guide", "user-guide/getting-started", "user-guide/test-and-live" ], "audience": "merchants" }, { "title": "Take payments", "pages": [ "user-guide/payment-links", "user-guide/checkout-pages", "user-guide/pricing-tables", "user-guide/widgets-and-buttons", "user-guide/buyer-experience", "user-guide/crypto-payments" ], "audience": "merchants" }, { "title": "Orders and customers", "pages": [ "user-guide/orders", "user-guide/customers", "user-guide/search" ], "audience": "merchants" }, { "title": "Manage your money", "pages": [ "user-guide/payments", "user-guide/held-payments", "user-guide/wallet-and-settlement" ], "audience": "merchants" }, { "title": "Your business", "pages": [ "user-guide/branding-and-settings", "user-guide/integrations", "user-guide/mobile" ], "audience": "merchants" }, { "title": "Help and reference", "pages": [ "user-guide/troubleshooting", "user-guide/glossary" ], "audience": "merchants" }, { "title": "Get started", "pages": [ "", "quickstart", "how-it-works", "testing" ], "audience": "developers" }, { "title": "Guides", "pages": [ "guides/hosted-checkout", "guides/custom-checkout", "guides/fulfilment", "guides/no-code", "guides/woocommerce" ], "audience": "developers" }, { "title": "API reference", "pages": [ "api", "api/checkout-sessions", "api/payments", "api/orders", "api/customers", "api/errors" ], "audience": "developers" }, { "title": "Webhooks", "pages": [ "webhooks", "webhooks/events", "webhooks/signatures" ], "audience": "developers" }, { "title": "Resources", "pages": [ "agents" ], "audience": "developers" } ], "pages": [ { "id": "user-guide", "title": "Your guide to getting paid", "nav": "Welcome to Railbed", "section": "Start here", "description": "Set up your business, take your first card payment, and follow every sale to your wallet. Start here, with or without a website.", "audience": "merchants", "url": "https://railbed.com/docs/user-guide/", "path": "/docs/user-guide/", "markdown": "https://railbed.com/docs/user-guide.md", "updated": "2026-09-26", "bodyLineOffset": 8, "markdownHash": "b3cf67a4e244c78adae37ddcf2e3e3b24df6632e2bf73ac5d6ed5e6e8783cd98", "sections": [ { "heading": "Your guide to getting paid", "anchor": "", "level": 1, "startLine": 0, "text": "New to Railbed? Set up your account and try a Test payment. Visual example: How a payment works. 1. Share your checkout: Send a payment link or publish a reusable checkout. You set the price. 2. Your buyer pays by card: They choose an eligible provider and pay on its page. Provider checks may apply. 3. Confirm the payment: Read the payment status and reported USDC settlement in Railbed. Your wallet · Polygon. Deliver only when the payment is Paid. A browser return does not confirm payment. The Live payment journey. In Test mode, the provider and settlement are simulated.", "endLine": 49 }, { "heading": "Start with your first payment", "anchor": "start-with-your-first-payment", "level": 2, "startLine": 6, "text": "Start with your first payment A customer pays by card. You receive USDC on Polygon in a wallet you control. Railbed gives you the checkout, a record of each payment, and a place to manage it all. Start in Test mode to try the full experience without charging a card. When you are ready to take real payments, create your customer-facing links in Live mode . - Set up your account: Add your business, choose a payout wallet, and find your way around the dashboard. - Try a test payment: See a successful payment, an underpayment, and a decline before going live.", "endLine": 15 }, { "heading": "Choose how to get paid", "anchor": "choose-how-to-get-paid", "level": 2, "startLine": 15, "text": "Choose how to get paid The right starting point depends on whether you are requesting one payment or selling the same thing repeatedly. You want to… Use What you share --- --- --- Ask one customer for a specific amount Payment link A one-time link or QR code, with an optional invoice reference Sell one product to many buyers Checkout page A reusable page; each buyer gets a separate payment Let buyers choose between packages Pricing table A reusable page with up to four plans Take payments inside your website Widget or buy button A short HTML snippet copied from the dashboard Connect a WordPress store WooCommerce The Railbed plugin, connected to your account", "endLine": 27 }, { "heading": "Make Railbed part of your day", "anchor": "make-railbed-part-of-your-day", "level": 2, "startLine": 27, "text": "Make Railbed part of your day - Manage your orders: See items, payment attempts and what still needs to be fulfilled. - Know your customers: Read purchase histories, save private notes and manage customer data. - Understand your payments: Find an order, read its status, and open its timeline. - Read your wallet: Understand the difference between a balance, a sale, and the amount received. - Make it yours: Set your business name, logo, support email, and checkout appearance. - Solve a problem: Find the next step for a missing payment, an unavailable checkout, or a buyer who needs help. Use account search to jump between records. Prefer reading in the dark? Choose Dark or Match system from the docs theme selector. Appearance settings explains the separate dashboard and checkout preferences.", "endLine": 38 }, { "heading": "A few things to know", "anchor": "a-few-things-to-know", "level": 2, "startLine": 38, "text": "A few things to know You control the wallet. Railbed does not hold a balance for you to withdraw. Settlement goes to your own wallet. Your buyer pays with a card provider. They enter card details on that provider's page. Available providers and identity checks vary by buyer, country, currency and amount. Payment status is what matters. Check that a payment is Paid before delivering the order. A buyer returning to a thank-you page is not proof of payment. Read the statuses. Pricing tables are one-time purchases. A monthly or yearly label does not create automatic recurring billing. Building your own store, app or game? Switch to the developer docs for API examples and signed webhooks. These user guides focus on the dashboard and everyday merchant tasks.", "endLine": 49 } ] }, { "id": "user-guide/getting-started", "title": "Set up your account", "nav": "Set up your account", "section": "Start here", "description": "Go from a new account to a checkout you can share, with the right business details and payout wallet in place.", "audience": "merchants", "url": "https://railbed.com/docs/user-guide/getting-started/", "path": "/docs/user-guide/getting-started/", "markdown": "https://railbed.com/docs/user-guide/getting-started.md", "updated": "2026-10-04", "bodyLineOffset": 8, "markdownHash": "d32b8a3d5bea7c0196c784e36331364c1a41d91007daf3816afe987a2d9d91d8", "sections": [ { "heading": "Before you begin", "anchor": "before-you-begin", "level": 2, "startLine": 0, "text": "Before you begin Have a business name, a product or service to sell, and the public address of a self-custody wallet on Polygon . Use a wallet you control, rather than an exchange deposit address. The address tells Railbed where to send settlement; you never need to give Railbed a seed phrase or private key. Your customers see prices in USD, EUR, GBP, CAD or AUD. Settlement reaches your wallet as USDC on Polygon, regardless of the checkout currency.", "endLine": 6 }, { "heading": "Create your account", "anchor": "create-your-account", "level": 2, "startLine": 6, "text": "Create your account 1. Open Railbed signup. Continue with email or a sign-in option shown on the page, then complete any verification prompts. 2. In Set up your business , enter the name buyers should see, add your logo if you have one, and choose Connect a wallet to pick your payout wallet from MetaMask, Trust Wallet, Rabby, Rainbow or any wallet that scans a WalletConnect QR code. Railbed reads the wallet's public address and disconnects; it never asks you to sign anything or approve a transaction. No wallet yet? Create one with Base Account , Coinbase's free wallet that you set up with a passkey. You can also choose Paste an address instead : Railbed checks a pasted address for typos and shows it in groups of four so you can compare it with your wallet app. 3. In How will you take payments? , choose your main way to sell. You can add the others later from Integrations . Choose When What happens next --- --- --- Send payment links or invoices You bill customers one at a time, or sell without a website Make your first payment link and share it by link or QR code. You can try a test payment first. Add it to your own app or website You have a site or app of your own Without a developer: make a checkout and paste two lines of HTML. With one: connect your server with a Test key, then a Live key, through the API. Sell on Shopify Your store runs on Shopify Enter your store address, then follow the Shopify setup page's four steps. Sell on WooCommerce Your store runs on WordPress Download the plugin, then follow the WooCommerce setup. 4. Back on Wallet , the Your first payment card lists what's left for your way to sell and ticks each step as it happens. Hide it when you don't need it; Settings brings it back. 5. Check the dashboard's Live switch before sharing anything. Turn Live off to use Test mode. A link or checkout belongs to the mode in which you created it. [!IMPORTANT] Test mode and Live mode have separate checkouts and payment records. Switching the dashboard to Live does not convert a Test checkout into a real one. Create a checkout in the intended mode and share its new link.", "endLine": 25 }, { "heading": "Find your way around", "anchor": "find-your-way-around", "level": 2, "startLine": 25, "text": "Find your way around Dashboard area What you do there --- --- Wallet Follow the steps to your first payment, and see your latest checkout, payout wallet, recent receipts and payments needing review Orders Review items, customers, payment attempts and fulfilment for each purchase Customers See purchase histories, contact details and your private customer notes Payments Search all payment sources, filter by status and inspect a payment's details Payment links Request a one-time payment, share its QR code and follow its progress Checkouts Manage reusable checkout pages, pricing tables and payment widgets Create Choose which payment experience to make next Integrations Download the WooCommerce plugin and review ways to connect Railbed Developers Create API keys (full access or read only), connect webhooks, inspect event deliveries and manage connected AI agents Settings Change your business details, branding, profile photo or payout wallet Use Search in the sidebar or phone navigation to find a record or jump to another page. Account search supports keyboard shortcuts and queries such as an order number, email or payment ID. Choose the dashboard's Light , Dark or Match system appearance in Settings. You may see additional controls if your account is a platform operator. They are not needed for ordinary merchant setup.", "endLine": 44 }, { "heading": "Make your first practice checkout", "anchor": "make-your-first-practice-checkout", "level": 2, "startLine": 44, "text": "Make your first practice checkout 1. Turn Live off. Confirm the Test mode label is visible. 2. Choose Create → Checkout page . Enter an example product such as Design consultation, a price such as 49.00 , and USD. 3. Create the page, then open its Share tab and choose Open checkout . 4. Follow Try a test payment to experience the buyer's steps and confirm the result in Payments. Visual example: A reusable checkout page. A checkout shows Northstar Studio, Design consultation, $49.00 USD and an email field. Continue to pay leads to provider selection; card details are entered on the provider's page. Illustrative example · your product on the left, buyer details on the right.", "endLine": 55 }, { "heading": "Finish your business settings", "anchor": "finish-your-business-settings", "level": 2, "startLine": 55, "text": "Finish your business settings In Settings, add your logo and support email. Buyers use those details to recognize your business and get help with their order. Choose a checkout brand color and Save settings . Logo and profile photo uploads save as soon as you finish cropping them. Branding and settings explains where each detail appears and which changes are shared across modes.", "endLine": 61 }, { "heading": "When you are ready for customers", "anchor": "when-you-are-ready-for-customers", "level": 2, "startLine": 61, "text": "When you are ready for customers Open Test and Live mode and work through the launch checklist. Confirm the payout address, the product price and currency, the buyer experience, and how you will deliver orders after payment. For a one-off invoice or deposit, start with a payment link. For a product you sell repeatedly, keep using a checkout page.", "endLine": 66 } ] }, { "id": "user-guide/test-and-live", "title": "Test and Live mode", "nav": "Test and Live mode", "section": "Start here", "description": "Practice the buyer experience without moving money, then prepare a separate checkout for real customers.", "audience": "merchants", "url": "https://railbed.com/docs/user-guide/test-and-live/", "path": "/docs/user-guide/test-and-live/", "markdown": "https://railbed.com/docs/user-guide/test-and-live.md", "updated": "2026-10-05", "bodyLineOffset": 8, "markdownHash": "d60863c328582516d960d75c8f0eef255f7b6e0bdc62cc4dd1f863879521ef97", "sections": [ { "heading": "Check the mode before you create", "anchor": "check-the-mode-before-you-create", "level": 2, "startLine": 0, "text": "Check the mode before you create Use the Live switch in the dashboard. Live off means Test mode. The app shows a Test mode banner and labels so you can tell which records you are viewing. What changes Test mode Live mode --- --- --- Card payments Simulated; no card is charged Real payments through available card providers Wallet display Simulated USDC received in the last 7 days USDC balance read from your wallet on Polygon Links, checkouts, orders, customers and payments Separate Test records Separate Live records Provider list Fixed for practice Depends on current availability and buyer eligibility Webhooks Real signed HTTP deliveries for simulated events Real signed HTTP deliveries for actual events Business details, branding and the payout wallet in Settings are shared across both modes. Changing those settings while viewing Test mode still changes your account settings.", "endLine": 14 }, { "heading": "Run a practice payment", "anchor": "run-a-practice-payment", "level": 2, "startLine": 14, "text": "Run a practice payment 1. Turn Live off and create a payment link or checkout with a sample price, such as $49. 2. Open the buyer link and continue with an email address you use for testing. Choose one of the available Test providers. 3. Railbed opens a simulated provider page. Choose Simulate successful payment . You do not enter card details. 4. Return to the original checkout tab. It updates to the paid result, or follows your success URL if you set one. 5. Open Payments in Test mode. Find the payment, confirm Paid , and inspect the timeline and simulated receipt. You can also open Orders to inspect the purchase and its attempts, then open its customer. These are Test records. A simulated Paid status does not represent a real charge or settlement.", "endLine": 24 }, { "heading": "Practice the exceptions too", "anchor": "practice-the-exceptions-too", "level": 2, "startLine": 24, "text": "Practice the exceptions too Create a new Test payment for each completed-payment scenario. A declined card can be retried on the same payment. - Simulate an underpayment: the payment becomes Underpaid . Open its details to understand the hold and any available review action. - Simulate declined card: the payment stays open. Return to the checkout tab, choose Choose another way to pay , and try another provider. You can then simulate a successful payment on the same checkout. - Leave a payment unfinished: see how an open or in-progress payment differs from a paid one. A Live card decline happens on the provider's page and is not directly reported to Railbed. The payment may stay open or in progress until it is paid or expires. Test mode teaches the UI and integration behavior; it does not prove which providers will approve a real buyer. [!NOTE] A configured Test webhook still sends real requests to its endpoint. Use an endpoint intended for testing, especially if your connected system sends emails or fulfils orders automatically.", "endLine": 37 }, { "heading": "Before sharing a Live link", "anchor": "before-sharing-a-live-link", "level": 2, "startLine": 37, "text": "Before sharing a Live link - [ ] Confirm the full Polygon payout address in Settings against the wallet you control. - [ ] Review your business name, logo, support email and displayed Railbed fee. - [ ] Switch to Live and create the payment link or checkout there. - [ ] Open that exact buyer link and confirm its price, currency, description and appearance. - [ ] Copy the Live embed code again if you are using a button or widget. - [ ] Confirm how you will deliver the order after Paid , and what you will do with a payment that needs review. - [ ] If you use a store or API integration, connect the matching Live key and Live webhook endpoint. Opening a Live checkout is different from completing a card payment. A successful Test payment does not move funds or demonstrate real settlement.", "endLine": 49 }, { "heading": "Where did my checkout go?", "anchor": "where-did-my-checkout-go", "level": 2, "startLine": 49, "text": "Where did my checkout go? Check the mode first. A Test link, payment or key is not listed in Live mode, and vice versa. Switching modes changes the records you see; it does not delete them. The buyer URL already identifies its checkout or payment. Your current dashboard mode does not change what a customer sees when they open a previously shared URL.", "endLine": 54 } ] }, { "id": "user-guide/payment-links", "title": "Create and share a payment link", "nav": "Payment links", "section": "Take payments", "description": "Request one payment for one customer. Add an invoice reference, share a link or QR code, and track it until it is paid.", "audience": "merchants", "url": "https://railbed.com/docs/user-guide/payment-links/", "path": "/docs/user-guide/payment-links/", "markdown": "https://railbed.com/docs/user-guide/payment-links.md", "updated": "2026-09-26", "bodyLineOffset": 8, "markdownHash": "c6caf31bb5b38b86aedd10880caa7147f34e256aa8de4e07e05587b6a0d7f4bb", "sections": [ { "heading": "When to use a payment link", "anchor": "when-to-use-a-payment-link", "level": 2, "startLine": 0, "text": "When to use a payment link Use a payment link for an invoice, a project deposit, a consultation or a custom order. It has a fixed amount and can be paid once. To sell the same product repeatedly, use a checkout page instead. Visual example: Create a payment link. New payment link: Amount 49.00, Currency USD, What it is for Design consultation, Reference INV-0042, Can be paid for 7 days. The buyer sees a payment request with the amount, description and reference. Illustrative example · a $49 consultation with a 7-day payment link.", "endLine": 8 }, { "heading": "Create the request", "anchor": "create-the-request", "level": 2, "startLine": 8, "text": "Create the request 1. Check Test or Live mode, then open Create → Payment link , or choose New payment link in Payment links. 2. Enter the Amount , Currency , and What it’s for . The description is shown to the customer, so use a recognizable product or service name. 3. Add the optional customer and invoice details below. 4. Choose how long the link Can be paid for : 1 day , 7 days , or 30 days . The default is 7 days. 5. Choose Create payment link . Review the saved details before sharing the link. Field What to enter Example --- --- --- Amount A price from 1.00 to 100,000.00; provider minimums may be higher 49.00 Currency USD, EUR, GBP, CAD or AUD USD What it’s for A customer-facing description, up to 120 characters Design consultation Reference An optional order or invoice number, up to 64 characters INV-0042 Name An optional customer name, up to 80 characters Alex Morgan Email Prefills the buyer's email at checkout alex@example.com Note to the customer An optional note shown on the payment page, up to 500 characters Consultation on Friday at 2 pm Railbed does not email the payment link. Adding a customer email prefills checkout; you still send the link yourself. A customer's name or email is not an access restriction. Share the payment link only with people who should see the request.", "endLine": 28 }, { "heading": "Share the payment link or QR code", "anchor": "share-the-payment-link-or-qr-code", "level": 2, "startLine": 28, "text": "Share the payment link or QR code The saved request has a Payment link section. Copy the link into your invoice, message or email. Use its QR code for a printed invoice or for a customer to scan from another screen. The QR code opens the same payment page; it is not a crypto transfer address. Here is a message you can adapt: Example: Example message to a customer text Hi Alex, Your design consultation is ready to book. The total is $49.00 USD (reference INV-0042). Pay using the Railbed link included in this message. The link is available for 7 days. Thank you, Northstar Studio Paste your actual saved link into the message before sending it. Recheck the mode: a Test link cannot collect real money.", "endLine": 51 }, { "heading": "Share progress with someone else", "anchor": "share-progress-with-someone-else", "level": 2, "startLine": 51, "text": "Share progress with someone else Use the separate Tracking link for an accountant or collaborator who needs to see whether the request has been paid. Visual example: A status-only tracking page. The tracking page shows a $49 Design consultation for Alex Morgan, reference INV-0042, In progress. It omits the email, note, wallet, transactions and a way to pay. Illustrative example · share progress without sharing payment details. The tracking page shows the amount, status, progress, reference and billed-to name. It omits the buyer's email, your note, deposit and wallet details, transaction links and a way to pay. Anyone with the tracking link can see that limited information; treat it as a shareable link, not a login-protected report.", "endLine": 61 }, { "heading": "Read the result", "anchor": "read-the-result", "level": 2, "startLine": 61, "text": "Read the result Open the request in Payment links to see its status, details and timeline. Once paid, the buyer's payment link shows their receipt. A held payment shows that it is being reviewed. The list's Paid filter also includes payments being reviewed, and Expired includes declined payments. Always read the individual row status before delivering an order. Payment statuses explains the next action for each one.", "endLine": 67 }, { "heading": "Cancel, duplicate or replace a request", "anchor": "cancel-duplicate-or-replace-a-request", "level": 2, "startLine": 67, "text": "Cancel, duplicate or replace a request Cancel link is available only while the link is still payable and the buyer has not gone to a card provider. After that hand-off, the link stays open for the payment to arrive or expire. Canceling a request does not reverse a card payment or refund money. Saved payment links are not edited in place. To correct an amount or request payment again, choose Duplicate , review the copied fields, and create a new link. Duplicate clears the reference. Once the original payment has started, it also clears the saved email, so review and re-enter the details needed for the new request. Cancel the old link if that action is still available.", "endLine": 73 }, { "heading": "Send the buyer to your thank-you page", "anchor": "send-the-buyer-to-your-thank-you-page", "level": 2, "startLine": 73, "text": "Send the buyer to your thank-you page Under More options , fill After payment, send them to . You can include {PAYMENT_ID} and {REFERENCE} : Example: Example success URL text https://example.com/thanks?payment={PAYMENT_ID}&order={REFERENCE} The original Railbed tab follows this URL after payment is confirmed. If the buyer closes the tab, the redirect cannot happen. Leaving the field empty shows Railbed's on-screen receipt; it does not send a receipt email. The buyer experience explains the two-tab flow.", "endLine": 84 } ] }, { "id": "user-guide/checkout-pages", "title": "Create a reusable checkout", "nav": "Checkout pages", "section": "Take payments", "description": "Sell one product at one price with a page you can share again and again. Every buyer gets a separate payment.", "audience": "merchants", "url": "https://railbed.com/docs/user-guide/checkout-pages/", "path": "/docs/user-guide/checkout-pages/", "markdown": "https://railbed.com/docs/user-guide/checkout-pages.md", "updated": "2026-10-05", "bodyLineOffset": 8, "markdownHash": "5ea77778c67f43befee5d56b44e544336fb6cecab42a96fce6dea5ac761c1733", "sections": [ { "heading": "One page, many customers", "anchor": "one-page-many-customers", "level": 2, "startLine": 0, "text": "One page, many customers A checkout page is a reusable product page hosted by Railbed. Unlike a one-time payment link, it keeps accepting new buyers until you delete it. Share it in your website, social profile or messages, or use it behind a buy button. Visual example: A reusable checkout page. A checkout shows Northstar Studio, Design consultation, $49.00 USD and an email field. Continue to pay leads to provider selection; card details are entered on the provider's page. Illustrative example · your product on the left, buyer details on the right.", "endLine": 8 }, { "heading": "Build your checkout", "anchor": "build-your-checkout", "level": 2, "startLine": 8, "text": "Build your checkout 1. Check the dashboard mode, then choose Create → Checkout page . 2. Enter the product Name , optional Description , Price and Currency . The preview shows how those details appear to buyers. 3. Choose the Checkout theme , Light or Dark. The editor also lets you choose a brand color; that brand setting applies across your business's checkouts. 4. Optionally change the Button text . Keep the next action clear, such as Continue to pay. This changes the button inside the checkout; a buy button on your website has its own label. 5. Choose the Provider choice : Smart Routing (the default), Buyers choose, or One provider. How buyers reach a provider explains each. 6. Under More options , add a success URL if you have a thank-you page. 7. Choose Create checkout page , then open the saved page's Share tab. Names can be up to 80 characters; descriptions up to 280. Prices range from 1.00 to 100,000.00 in USD, EUR, GBP, CAD or AUD. A price that Railbed accepts may still be below a provider's minimum. Smart Routing checks the providers available to that buyer.", "endLine": 20 }, { "heading": "Choose how buyers reach a provider", "anchor": "choose-how-buyers-reach-a-provider", "level": 2, "startLine": 20, "text": "Choose how buyers reach a provider Provider choice in the Checkout card decides what happens after the buyer enters their email. It applies to this checkout, including any widget or buy button that uses it. - Smart Routing sends each buyer straight to the best card provider for their country, amount and currency. Their one click on Continue to pay opens the provider. New checkouts start here. - Buyers choose shows Smart Routing's ranked list, with the best match selected, and the buyer picks. Checkouts made before this setting existed use it until you change them. - One provider sends every buyer to the provider you pick. The editor shows the provider's minimum and warns when your price is below it (or asks you to check, when the minimum is in another currency), when the provider isn't taking payments, or when it serves only some countries. With One provider, If it can't take a buyer, use Smart Routing instead is on by default: a buyer the provider can't serve (another country, below its minimum, or while it's down) goes to the best provider for them, and the payment's timeline says so. Turn it off only if every buyer must use that provider. Buyers it can't serve then see a message and can't pay at this checkout, and no payment is created. In every mode, a buyer can choose Choose another way to pay to see the full list, including after a declined card. The payment's timeline shows who chose each provider: Smart Routing, your checkout's setting, or the buyer. Shopify stores and WooCommerce have the same setting on their setup pages (Integrations). Payment links and custom API checkouts always show the list.", "endLine": 32 }, { "heading": "Share the saved page", "anchor": "share-the-saved-page", "level": 2, "startLine": 32, "text": "Share the saved page The Share tab contains the hosted URL and QR code. Open the actual checkout to check the buyer view, then copy the URL wherever customers will find it. A checkout address looks like this: Example: Example checkout address — use your saved URL text https://pay.railbed.io/c/your-checkout-slug The slug is the final part of the saved address. It is also what the embed code uses. Use the URL Railbed gives you instead of typing a slug from the product name. To take payments on your own website, use Add it to your site in the Share tab. Widgets and buy buttons covers the available formats and copyable HTML.", "endLine": 48 }, { "heading": "Edit an existing checkout", "anchor": "edit-an-existing-checkout", "level": 2, "startLine": 48, "text": "Edit an existing checkout Open Checkouts , choose the checkout, then select Edit . Change the product details and choose Save changes in the page header. The Share and Edit tabs keep sharing controls separate from your product settings. The hosted URL stays the same when you edit the product. Future payment creation uses the updated checkout details. Payments already created retain their saved amount and description, so do not expect an edit to rewrite an existing customer's order. Currency becomes fixed once a payment reaches a card provider, or a payment is paid or being reviewed. If the field is locked, create a new checkout to sell in a different currency. For a different checkout kind, create that kind separately.", "endLine": 56 }, { "heading": "Use a success URL", "anchor": "use-a-success-url", "level": 2, "startLine": 56, "text": "Use a success URL Set After payment, send buyers to under More options: Example: Send a confirmed buyer to your thank\\-you page text https://example.com/thanks?payment={PAYMENT_ID} Railbed fills in the payment ID after confirmation. Reusable checkout payments do not have your own order reference, so {REFERENCE} would be empty. Use an API integration if every order needs a reference or customer-account metadata supplied by your server. A redirect is a convenience for the buyer. For manual delivery, check the payment in the dashboard. For automatic delivery, use verified webhooks or authenticated payment retrieval.", "endLine": 70 }, { "heading": "Stop accepting new buyers", "anchor": "stop-accepting-new-buyers", "level": 2, "startLine": 70, "text": "Stop accepting new buyers Open Edit → Delete checkout page and confirm. The hosted checkout and any embedded button or widget using it stop accepting new payments. Past payments remain in Payments. Deleting the checkout is not a refund or a cancellation of payments that already exist. If you want to keep the page available, remove links to it from your own website instead; anyone who still has its URL can continue to open it until it is deleted.", "endLine": 75 } ] }, { "id": "user-guide/pricing-tables", "title": "Offer plans with a pricing table", "nav": "Pricing tables", "section": "Take payments", "description": "Present up to four packages side by side, highlight one recommendation, and let buyers choose the right one.", "audience": "merchants", "url": "https://railbed.com/docs/user-guide/pricing-tables/", "path": "/docs/user-guide/pricing-tables/", "markdown": "https://railbed.com/docs/user-guide/pricing-tables.md", "updated": "2026-10-05", "bodyLineOffset": 8, "markdownHash": "c0a60c9d5bf5fb5d11b01504b868be029fc609e084aec79c1247a36d670ce496", "sections": [ { "heading": "What a pricing table does", "anchor": "what-a-pricing-table-does", "level": 2, "startLine": 0, "text": "What a pricing table does A pricing table is a reusable checkout with multiple plans. It works for service packages, access passes, resource bundles or other choices with a fixed price. A buyer chooses a plan, enters their details, and continues to a card provider. Visual example: Compare three one-time plans. Starter costs $19, Studio $49 and Team $99. Studio is highlighted as recommended. Each purchase is a one-time payment; nothing renews automatically. Illustrative example · Studio is the recommended plan. [!IMPORTANT] Every purchase is one payment. Pricing tables do not create subscriptions or automatic renewals. Labels such as / mo and / yr describe what you sell; they do not schedule another card charge.", "endLine": 11 }, { "heading": "Create the table", "anchor": "create-the-table", "level": 2, "startLine": 11, "text": "Create the table 1. Choose the correct mode, then Create → Pricing table . 2. Set the table Title , optional Description and Currency . All plans use that currency. 3. Add between one and four plans . The editor starts with Starter, Pro and Team as names; enter your own prices and details. 4. For each plan, fill Name , optional Description , Price , optional Label , and Features . Enter one feature per line, up to eight. 5. Optionally turn on Recommended plan for one plan. It appears as the dark highlighted card. Only one plan can be recommended. 6. Arrange plans with their move controls. Review the preview, choose the theme, and create the pricing table. 7. Optionally change the Provider choice in the Checkout card. It works as it does on checkout pages; with One provider, the editor compares every plan price with the provider's minimum when both are in the same currency, and asks you to check them when they aren't. A plan name can contain up to 40 characters, its description up to 140, and the price label up to 16. Keep feature descriptions short enough for buyers to compare at a glance.", "endLine": 23 }, { "heading": "Offer two price options", "anchor": "offer-two-price-options", "level": 2, "startLine": 23, "text": "Offer two price options Turn on Price switch to provide two prices for every plan. Name First option and Second option , then fill in both prices for each plan. For example, a studio could sell a Single session or a Three-session pack . Switching the option changes the displayed prices across the table. Monthly and Yearly are also possible labels when the purchase buys that period of access, but Railbed will not charge again when it ends. Make both the price and what it includes explicit: Plan Single session Three-session pack --- --- --- Consultation $49 $129 Extended session $99 $269 These are illustrative prices. You decide what you deliver and any access duration outside Railbed.", "endLine": 38 }, { "heading": "Share or embed it", "anchor": "share-or-embed-it", "level": 2, "startLine": 38, "text": "Share or embed it Open the saved table's Share tab. Share its hosted URL or QR code, add a Buy button that opens the plans, or place the Pricing table directly in your website from Add it to your site . Example: Place your pricing table on a website html \n\n\n" }, { "page": "user-guide/widgets-and-buttons", "section": "Add a buy button", "url": "https://railbed.com/docs/user-guide/widgets-and-buttons/#add-a-buy-button", "language": "HTML", "label": "A button that opens your checkout", "kind": "code", "code": "\n\n\n" }, { "page": "user-guide/widgets-and-buttons", "section": "Add an inline checkout", "url": "https://railbed.com/docs/user-guide/widgets-and-buttons/#add-an-inline-checkout", "language": "HTML", "label": "A checkout embedded in your page", "kind": "code", "code": "\n\n\n" }, { "page": "overview", "section": "The API at a glance", "url": "https://railbed.com/docs/#the-api-at-a-glance", "language": "cURL", "label": "Create a checkout session", "kind": "code", "code": "curl https://pay.railbed.io/v1/checkout_sessions \\\n -H \"Authorization: Bearer $RAILBED_SECRET_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -H \"Idempotency-Key: order_1042\" \\\n -d '{\n \"amount\": \"49.00\",\n \"currency\": \"USD\",\n \"description\": \"Pro Membership\",\n \"reference\": \"order_1042\"\n }'" }, { "page": "overview", "section": "The API at a glance", "url": "https://railbed.com/docs/#the-api-at-a-glance", "language": "JSON", "label": "Response", "kind": "response", "code": "{\n \"id\": \"pay_7AAiYH0Ykt11ED4hmfiN\",\n \"object\": \"checkout_session\",\n \"url\": \"https://pay.railbed.io/p/pay_7AAiYH0Ykt11ED4hmfiN\",\n \"status\": \"open\",\n \"livemode\": false,\n \"amount\": \"49.00\",\n \"currency\": \"USD\",\n \"description\": \"Pro Membership\",\n \"reference\": \"order_1042\",\n \"customer_email\": null,\n \"created\": 1790380525,\n \"expires_at\": 1790466925,\n \"started_at\": null,\n \"metadata\": null,\n \"order_id\": \"ord_M4tQx8ZkP1vRn6WcLs2B\"\n}" }, { "page": "quickstart", "section": "1. Create a secret key", "url": "https://railbed.com/docs/quickstart/#1-create-a-secret-key", "language": "cURL", "label": "Your server's environment", "kind": "code", "code": "export RAILBED_SECRET_KEY=\"rb_test_…\"" }, { "page": "quickstart", "section": "2. Create a checkout session", "url": "https://railbed.com/docs/quickstart/#2-create-a-checkout-session", "language": "cURL", "label": "cURL", "kind": "code", "code": "curl https://pay.railbed.io/v1/checkout_sessions \\\n -H \"Authorization: Bearer $RAILBED_SECRET_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -H \"Idempotency-Key: order_1042\" \\\n -d '{\n \"amount\": \"49.00\",\n \"currency\": \"USD\",\n \"description\": \"Pro Membership\",\n \"reference\": \"order_1042\",\n \"customer_email\": \"buyer@example.com\",\n \"success_url\": \"https://yourstore.com/thanks?order={REFERENCE}\"\n }'" }, { "page": "quickstart", "section": "2. Create a checkout session", "url": "https://railbed.com/docs/quickstart/#2-create-a-checkout-session", "language": "Node.js", "label": "Node.js", "kind": "code", "code": "const res = await fetch('https://pay.railbed.io/v1/checkout_sessions', {\n method: 'POST',\n headers: {\n Authorization: `Bearer ${process.env.RAILBED_SECRET_KEY}`,\n 'Content-Type': 'application/json',\n 'Idempotency-Key': 'order_1042',\n },\n body: JSON.stringify({\n amount: '49.00',\n currency: 'USD',\n description: 'Pro Membership',\n reference: 'order_1042',\n customer_email: 'buyer@example.com',\n success_url: 'https://yourstore.com/thanks?order={REFERENCE}',\n }),\n});\nconst session = await res.json();\nconsole.log(session.url);" }, { "page": "quickstart", "section": "2. Create a checkout session", "url": "https://railbed.com/docs/quickstart/#2-create-a-checkout-session", "language": "Python", "label": "Python", "kind": "code", "code": "import os, requests\n\nsession = requests.post(\n \"https://pay.railbed.io/v1/checkout_sessions\",\n headers={\n \"Authorization\": f\"Bearer {os.environ['RAILBED_SECRET_KEY']}\",\n \"Idempotency-Key\": \"order_1042\",\n },\n json={\n \"amount\": \"49.00\",\n \"currency\": \"USD\",\n \"description\": \"Pro Membership\",\n \"reference\": \"order_1042\",\n \"customer_email\": \"buyer@example.com\",\n \"success_url\": \"https://yourstore.com/thanks?order={REFERENCE}\",\n },\n timeout=15,\n).json()\nprint(session[\"url\"])" }, { "page": "quickstart", "section": "2. Create a checkout session", "url": "https://railbed.com/docs/quickstart/#2-create-a-checkout-session", "language": "PHP", "label": "PHP", "kind": "code", "code": " true,\n CURLOPT_RETURNTRANSFER => true,\n CURLOPT_HTTPHEADER => [\n 'Authorization: Bearer ' . getenv('RAILBED_SECRET_KEY'),\n 'Content-Type: application/json',\n 'Idempotency-Key: order_1042',\n ],\n CURLOPT_POSTFIELDS => json_encode([\n 'amount' => '49.00',\n 'currency' => 'USD',\n 'description' => 'Pro Membership',\n 'reference' => 'order_1042',\n 'customer_email' => 'buyer@example.com',\n 'success_url' => 'https://yourstore.com/thanks?order={REFERENCE}',\n ]),\n]);\n$session = json_decode(curl_exec($ch), true);\necho $session['url'];" }, { "page": "quickstart", "section": "2. Create a checkout session", "url": "https://railbed.com/docs/quickstart/#2-create-a-checkout-session", "language": "JSON", "label": "Response", "kind": "response", "code": "{\n \"id\": \"pay_7AAiYH0Ykt11ED4hmfiN\",\n \"object\": \"checkout_session\",\n \"url\": \"https://pay.railbed.io/p/pay_7AAiYH0Ykt11ED4hmfiN\",\n \"status\": \"open\",\n \"livemode\": false,\n \"amount\": \"49.00\",\n \"currency\": \"USD\",\n \"description\": \"Pro Membership\",\n \"reference\": \"order_1042\",\n \"customer_email\": \"buyer@example.com\",\n \"created\": 1790380525,\n \"expires_at\": 1790466925,\n \"started_at\": null,\n \"metadata\": null,\n \"order_id\": \"ord_M4tQx8ZkP1vRn6WcLs2B\"\n}" }, { "page": "quickstart", "section": "4. Confirm the payment from your server", "url": "https://railbed.com/docs/quickstart/#4-confirm-the-payment-from-your-server", "language": "cURL", "label": "cURL", "kind": "code", "code": "curl https://pay.railbed.io/v1/payments/pay_7AAiYH0Ykt11ED4hmfiN \\\n -H \"Authorization: Bearer $RAILBED_SECRET_KEY\"" }, { "page": "quickstart", "section": "4. Confirm the payment from your server", "url": "https://railbed.com/docs/quickstart/#4-confirm-the-payment-from-your-server", "language": "Node.js", "label": "Node.js", "kind": "code", "code": "const res = await fetch(`https://pay.railbed.io/v1/payments/${paymentId}`, {\n headers: { Authorization: `Bearer ${process.env.RAILBED_SECRET_KEY}` },\n});\nconst payment = await res.json();\nif (payment.status === 'paid') fulfil(payment.reference);" }, { "page": "quickstart", "section": "4. Confirm the payment from your server", "url": "https://railbed.com/docs/quickstart/#4-confirm-the-payment-from-your-server", "language": "Python", "label": "Python", "kind": "code", "code": "payment = requests.get(\n f\"https://pay.railbed.io/v1/payments/{payment_id}\",\n headers={\"Authorization\": f\"Bearer {os.environ['RAILBED_SECRET_KEY']}\"},\n timeout=15,\n).json()\nif payment[\"status\"] == \"paid\":\n fulfil(payment[\"reference\"])" }, { "page": "quickstart", "section": "4. Confirm the payment from your server", "url": "https://railbed.com/docs/quickstart/#4-confirm-the-payment-from-your-server", "language": "PHP", "label": "PHP", "kind": "code", "code": " true,\n CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . getenv('RAILBED_SECRET_KEY')],\n]);\n$payment = json_decode(curl_exec($ch), true);\nif ($payment['status'] === 'paid') fulfil($payment['reference']);" }, { "page": "quickstart", "section": "4. Confirm the payment from your server", "url": "https://railbed.com/docs/quickstart/#4-confirm-the-payment-from-your-server", "language": "JSON", "label": "Response (trimmed)", "kind": "response", "code": "{\n \"id\": \"pay_7AAiYH0Ykt11ED4hmfiN\",\n \"object\": \"payment\",\n \"status\": \"paid\",\n \"livemode\": false,\n \"amount\": \"49.00\",\n \"currency\": \"USD\",\n \"reference\": \"order_1042\",\n \"paid_at\": 1790381342,\n \"provider\": \"stripe\",\n \"settlement\": {\n \"coin\": \"polygon_usdc\",\n \"value_coin\": \"47.53\",\n \"merchant_received\": \"44.915850\",\n \"txid_in\": \"0x0c65…582e\",\n \"txid_out\": \"0x8202…356f\",\n \"payout_wallet\": \"0xF977814e90dA44bFA03b6295A0616a897441aceC\"\n }\n}" }, { "page": "testing", "section": "Simulate an outcome from your server", "url": "https://railbed.com/docs/testing/#simulate-an-outcome-from-your-server", "language": "cURL", "label": "cURL", "kind": "code", "code": "# Start it (the buyer would normally do this by choosing a provider)\ncurl -X POST \\\n https://pay.railbed.io/v1/checkout_sessions/pay_7AAiYH0Ykt11ED4hmfiN/start \\\n -H \"Authorization: Bearer $RAILBED_SECRET_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{ \"customer_email\": \"buyer@example.com\" }'\n\n# Choose an outcome: \"paid\", \"underpaid\", \"declined\" or \"failed\"\ncurl -X POST \\\n https://pay.railbed.io/v1/payments/pay_7AAiYH0Ykt11ED4hmfiN/simulate \\\n -H \"Authorization: Bearer $RAILBED_SECRET_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{ \"outcome\": \"paid\" }'" }, { "page": "testing", "section": "Simulate an outcome from your server", "url": "https://railbed.com/docs/testing/#simulate-an-outcome-from-your-server", "language": "Node.js", "label": "Node.js", "kind": "code", "code": "const api = (path, body) =>\n fetch(`https://pay.railbed.io/v1${path}`, {\n method: 'POST',\n headers: {\n Authorization: `Bearer ${process.env.RAILBED_SECRET_KEY}`,\n 'Content-Type': 'application/json',\n },\n body: JSON.stringify(body),\n }).then((r) => r.json());\n\nawait api(`/checkout_sessions/${id}/start`, {\n customer_email: 'buyer@example.com',\n});\nconst payment = await api(`/payments/${id}/simulate`, {\n outcome: 'paid', // or 'underpaid', 'declined', 'failed'\n});" }, { "page": "testing", "section": "Simulate an outcome from your server", "url": "https://railbed.com/docs/testing/#simulate-an-outcome-from-your-server", "language": "Python", "label": "Python", "kind": "code", "code": "def api(path, body):\n return requests.post(\n f\"https://pay.railbed.io/v1{path}\",\n headers={\"Authorization\": f\"Bearer {os.environ['RAILBED_SECRET_KEY']}\"},\n json=body,\n timeout=15,\n ).json()\n\napi(f\"/checkout_sessions/{id}/start\", {\"customer_email\": \"buyer@example.com\"})\npayment = api(\n f\"/payments/{id}/simulate\",\n {\"outcome\": \"paid\"}, # or \"underpaid\", \"declined\", \"failed\"\n)" }, { "page": "testing", "section": "Simulate an outcome from your server", "url": "https://railbed.com/docs/testing/#simulate-an-outcome-from-your-server", "language": "PHP", "label": "PHP", "kind": "code", "code": " true,\n CURLOPT_RETURNTRANSFER => true,\n CURLOPT_HTTPHEADER => [\n 'Authorization: Bearer ' . getenv('RAILBED_SECRET_KEY'),\n 'Content-Type: application/json',\n ],\n CURLOPT_POSTFIELDS => json_encode($body),\n ]);\n return json_decode(curl_exec($ch), true);\n}\n\nrailbed_post(\"/checkout_sessions/$id/start\", [\n 'customer_email' => 'buyer@example.com',\n]);\n$payment = railbed_post(\"/payments/$id/simulate\", [\n 'outcome' => 'paid', // or 'underpaid', 'declined', 'failed'\n]);" }, { "page": "guides/hosted-checkout", "section": "Create the session", "url": "https://railbed.com/docs/guides/hosted-checkout/#create-the-session", "language": "Node.js", "label": "Node.js", "kind": "code", "code": "// POST /checkout on your server, after saving the order\napp.post('/checkout', async (req, res) => {\n const order = await orders.create({\n userId: req.user.id,\n sku: 'pro-monthly',\n price: '49.00',\n currency: 'USD',\n });\n\n const response = await fetch('https://pay.railbed.io/v1/checkout_sessions', {\n method: 'POST',\n headers: {\n Authorization: `Bearer ${process.env.RAILBED_SECRET_KEY}`,\n 'Content-Type': 'application/json',\n 'Idempotency-Key': `order_${order.id}`,\n },\n body: JSON.stringify({\n amount: order.price,\n currency: order.currency,\n description: 'Pro Membership · monthly',\n reference: `order_${order.id}`,\n customer_email: req.user.email,\n metadata: { user_id: String(req.user.id) },\n success_url:\n `https://yourstore.com/orders/${order.id}/thanks?payment={PAYMENT_ID}`,\n cancel_url: `https://yourstore.com/cart`,\n }),\n });\n if (!response.ok) {\n return res.status(502).send(\n 'Checkout is unavailable. Try again in a moment.',\n );\n }\n const session = await response.json();\n\n await orders.update(order.id, { paymentId: session.id });\n res.redirect(303, session.url);\n});" }, { "page": "guides/hosted-checkout", "section": "Create the session", "url": "https://railbed.com/docs/guides/hosted-checkout/#create-the-session", "language": "Python", "label": "Python", "kind": "code", "code": "# Flask: after saving the order\n@app.post(\"/checkout\")\ndef checkout():\n order = orders.create(\n user_id=current_user.id,\n sku=\"pro-monthly\",\n price=\"49.00\",\n currency=\"USD\",\n )\n r = requests.post(\n \"https://pay.railbed.io/v1/checkout_sessions\",\n headers={\n \"Authorization\": f\"Bearer {os.environ['RAILBED_SECRET_KEY']}\",\n \"Idempotency-Key\": f\"order_{order.id}\",\n },\n json={\n \"amount\": order.price,\n \"currency\": order.currency,\n \"description\": \"Pro Membership · monthly\",\n \"reference\": f\"order_{order.id}\",\n \"customer_email\": current_user.email,\n \"metadata\": {\"user_id\": str(current_user.id)},\n \"success_url\": (\n f\"https://yourstore.com/orders/{order.id}\"\n f\"/thanks?payment={{PAYMENT_ID}}\"\n ),\n \"cancel_url\": \"https://yourstore.com/cart\",\n },\n timeout=15,\n )\n if not r.ok:\n return \"Checkout is unavailable. Try again in a moment.\", 502\n session = r.json()\n orders.update(order.id, payment_id=session[\"id\"])\n return redirect(session[\"url\"], code=303)" }, { "page": "guides/hosted-checkout", "section": "Create the session", "url": "https://railbed.com/docs/guides/hosted-checkout/#create-the-session", "language": "PHP", "label": "PHP", "kind": "code", "code": " true,\n CURLOPT_RETURNTRANSFER => true,\n CURLOPT_HTTPHEADER => [\n 'Authorization: Bearer ' . getenv('RAILBED_SECRET_KEY'),\n 'Content-Type: application/json',\n 'Idempotency-Key: order_' . $order['id'],\n ],\n CURLOPT_POSTFIELDS => json_encode([\n 'amount' => $order['price'],\n 'currency' => $order['currency'],\n 'description' => 'Pro Membership · monthly',\n 'reference' => 'order_' . $order['id'],\n 'customer_email' => $user['email'],\n 'metadata' => ['user_id' => (string) $user['id']],\n 'success_url' => 'https://yourstore.com/orders/' . $order['id']\n . '/thanks?payment={PAYMENT_ID}',\n 'cancel_url' => 'https://yourstore.com/cart',\n ]),\n]);\n$session = json_decode(curl_exec($ch), true);\nif (curl_getinfo($ch, CURLINFO_HTTP_CODE) >= 300) {\n http_response_code(502);\n exit('Checkout is unavailable.');\n}\nsave_payment_id($order['id'], $session['id']);\nheader('Location: ' . $session['url'], true, 303);" }, { "page": "guides/custom-checkout", "section": "Start the session and get providers", "url": "https://railbed.com/docs/guides/custom-checkout/#start-the-session-and-get-providers", "language": "cURL", "label": "cURL", "kind": "code", "code": "curl -X POST \\\n https://pay.railbed.io/v1/checkout_sessions/pay_7AAiYH0Ykt11ED4hmfiN/start \\\n -H \"Authorization: Bearer $RAILBED_SECRET_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{ \"customer_email\": \"player1042@example.com\", \"country\": \"US\" }'" }, { "page": "guides/custom-checkout", "section": "Start the session and get providers", "url": "https://railbed.com/docs/guides/custom-checkout/#start-the-session-and-get-providers", "language": "Node.js", "label": "Node.js", "kind": "code", "code": "// Your server: POST /api/purchase/:orderId/providers\n// (called by your checkout screen)\nconst res = await fetch(\n `https://pay.railbed.io/v1/checkout_sessions/${order.paymentId}/start`,\n {\n method: 'POST',\n headers: {\n Authorization: `Bearer ${process.env.RAILBED_SECRET_KEY}`,\n 'Content-Type': 'application/json',\n },\n body: JSON.stringify({\n customer_email: buyer.email,\n country: buyer.country, // from the buyer's request, if known\n }),\n },\n);\nif (res.status === 409) {\n const { error } = await res.json(); // e.g. no_providers, already_paid\n return reply.status(409).send({ code: error.code, message: error.message });\n}\nconst started = await res.json();\n// Send only what the screen needs. Never send your API key to the browser.\nreply.send(\n started.providers.map(({ id, name, note, recommended, handoff_url }) => ({\n id,\n name,\n note,\n recommended,\n handoff_url,\n })),\n);" }, { "page": "guides/custom-checkout", "section": "Start the session and get providers", "url": "https://railbed.com/docs/guides/custom-checkout/#start-the-session-and-get-providers", "language": "Python", "label": "Python", "kind": "code", "code": "r = requests.post(\n f\"https://pay.railbed.io/v1/checkout_sessions/{order.payment_id}/start\",\n headers={\"Authorization\": f\"Bearer {os.environ['RAILBED_SECRET_KEY']}\"},\n json={\n \"customer_email\": buyer.email,\n \"country\": buyer.country, # from the buyer's request, if known\n },\n timeout=15,\n)\nif r.status_code == 409:\n error = r.json()[\"error\"] # e.g. no_providers, already_paid\n return {\"code\": error[\"code\"], \"message\": error[\"message\"]}, 409\nproviders = [\n {k: p[k] for k in (\"id\", \"name\", \"note\", \"recommended\", \"handoff_url\")}\n for p in r.json()[\"providers\"]\n]" }, { "page": "guides/custom-checkout", "section": "Start the session and get providers", "url": "https://railbed.com/docs/guides/custom-checkout/#start-the-session-and-get-providers", "language": "PHP", "label": "PHP", "kind": "code", "code": " true,\n CURLOPT_RETURNTRANSFER => true,\n CURLOPT_HTTPHEADER => [\n 'Authorization: Bearer ' . getenv('RAILBED_SECRET_KEY'),\n 'Content-Type: application/json',\n ],\n CURLOPT_POSTFIELDS => json_encode([\n 'customer_email' => $buyer['email'],\n 'country' => $buyer['country'],\n ]),\n]);\n$started = json_decode(curl_exec($ch), true);\nif (curl_getinfo($ch, CURLINFO_HTTP_CODE) === 409) {\n http_response_code(409);\n exit(json_encode($started['error'])); // e.g. no_providers, already_paid\n}\n$fields = array_flip(['id', 'name', 'note', 'recommended', 'handoff_url']);\necho json_encode(array_map(\n fn ($p) => array_intersect_key($p, $fields),\n $started['providers'],\n));" }, { "page": "guides/custom-checkout", "section": "Start the session and get providers", "url": "https://railbed.com/docs/guides/custom-checkout/#start-the-session-and-get-providers", "language": "JSON", "label": "Response (trimmed)", "kind": "response", "code": "{\n \"id\": \"pay_7AAiYH0Ykt11ED4hmfiN\",\n \"object\": \"checkout_session\",\n \"status\": \"open\",\n \"amount\": \"49.00\",\n \"currency\": \"USD\",\n \"started_at\": 1790380611,\n \"country\": \"US\",\n \"providers\": [\n {\n \"id\": \"stripe\",\n \"name\": \"Stripe\",\n \"note\": \"Card, Apple Pay or Google Pay\",\n \"recommended\": true,\n \"handoff_url\": \"https://pay.railbed.io/go/pay_7AAiYH0Ykt11ED4hmfiN?provider=stripe\"\n },\n {\n \"id\": \"paypal\",\n \"name\": \"PayPal\",\n \"note\": \"PayPal balance or card\",\n \"recommended\": false,\n \"handoff_url\": \"https://pay.railbed.io/go/pay_7AAiYH0Ykt11ED4hmfiN?provider=paypal\"\n }\n ]\n}" }, { "page": "guides/custom-checkout", "section": "Show providers and hand off", "url": "https://railbed.com/docs/guides/custom-checkout/#show-providers-and-hand-off", "language": "HTML", "label": "In your checkout screen", "kind": "code", "code": "
    \n

    Choose how to pay.

    \n" }, { "page": "guides/custom-checkout", "section": "Show the result", "url": "https://railbed.com/docs/guides/custom-checkout/#show-the-result", "language": "Node.js", "label": "In your checkout screen", "kind": "code", "code": "async function waitForPayment() {\n // Your server, never Railbed directly\n const res = await fetch(`/api/orders/${orderId}/status`);\n const { status } = await res.json();\n if (status === 'paid') return showPaid();\n if (status === 'held') {\n return showMessage(\n 'Your payment arrived and is being reviewed. We’ll email you.',\n );\n }\n if (status === 'failed' || status === 'expired') {\n return showMessage('The payment didn’t go through. Try again.');\n }\n setTimeout(waitForPayment, 4000);\n}" }, { "page": "guides/fulfilment", "section": "Check before you grant", "url": "https://railbed.com/docs/guides/fulfilment/#check-before-you-grant", "language": "Node.js", "label": "Node.js: one grant per payment, in one transaction", "kind": "code", "code": "async function fulfilFromPayment(payment) {\n // Held, pending, expired: nothing to deliver yet\n if (payment.status !== 'paid') return;\n const order = await db.orders.findByPaymentId(payment.id);\n // Not ours (another store sharing the endpoint), or not saved yet\n if (!order) return;\n if (payment.livemode !== order.livemode) {\n throw new Error('mode mismatch');\n }\n if (payment.reference !== order.reference) {\n throw new Error('reference mismatch');\n }\n if (payment.amount !== order.price || payment.currency !== order.currency) {\n throw new Error('amount mismatch');\n }\n\n await db.transaction(async (tx) => {\n // UNIQUE(payment_id): a duplicate event or a second worker fails here\n // and delivers nothing\n const inserted = await tx.grants.insertIfAbsent({\n paymentId: payment.id,\n orderId: order.id,\n });\n if (!inserted) return;\n await tx.inventory.deliver(order);\n await tx.orders.markPaid(order.id, payment.paid_at);\n });\n}" }, { "page": "guides/fulfilment", "section": "Ship what the order says", "url": "https://railbed.com/docs/guides/fulfilment/#ship-what-the-order-says", "language": "Node.js", "label": "Node.js: ship a paid order once, then report it", "kind": "code", "code": "// railbed() is the small helper from /docs/api/errors/\nasync function shipOrder(paymentId) {\n const payment = await railbed(`/payments/${paymentId}`);\n if (payment.status !== 'paid') return;\n const order = await railbed(`/orders/${payment.order_id}`);\n // The order follows its latest session: check this payment covers it\n if (\n payment.amount !== order.total ||\n payment.currency !== order.currency\n ) {\n return flagForReview(order, payment);\n }\n await db.transaction(async (tx) => {\n // UNIQUE(order_id): a second paid payment for this order ships nothing\n const isNew = await tx.shipments.insertIfAbsent({ orderId: order.id });\n if (!isNew) return;\n await tx.shipments.queue({\n to: order.shipping_address,\n lines: order.items.map((i) => ({ sku: i.sku, quantity: i.quantity })),\n });\n });\n}\n\n// Later, when the parcel leaves the warehouse\nasync function markShipped(orderId) {\n await railbed(`/orders/${orderId}`, {\n method: 'PATCH',\n body: JSON.stringify({ fulfillment: 'fulfilled' }),\n });\n}" }, { "page": "guides/no-code", "section": "Add a buy button to any site", "url": "https://railbed.com/docs/guides/no-code/#add-a-buy-button-to-any-site", "language": "HTML", "label": "A buy button that opens the checkout over your page", "kind": "code", "code": "\n\n" }, { "page": "guides/no-code", "section": "Put the checkout in your page", "url": "https://railbed.com/docs/guides/no-code/#put-the-checkout-in-your-page", "language": "HTML", "label": "The checkout, in your page", "kind": "code", "code": "\n\n" }, { "page": "api", "section": "Authentication", "url": "https://railbed.com/docs/api/#authentication", "language": "cURL", "label": "An authenticated request", "kind": "code", "code": "curl \"https://pay.railbed.io/v1/payments?limit=1\" \\\n -H \"Authorization: Bearer rb_test_…\"" }, { "page": "api", "section": "Agent access tokens", "url": "https://railbed.com/docs/api/#agent-access-tokens", "language": "cURL", "label": "An agent's request", "kind": "code", "code": "curl \"https://pay.railbed.io/v1/payments?limit=1\" \\\n -H \"Authorization: Bearer $ACCESS_TOKEN\"" }, { "page": "api", "section": "Discovery", "url": "https://railbed.com/docs/api/#discovery", "language": "HTTP", "label": "A request without a credential", "kind": "response", "code": "WWW-Authenticate: Bearer resource_metadata=\"https://pay.railbed.io/.well-known/oauth-protected-resource/v1\"" }, { "page": "api", "section": "Discovery", "url": "https://railbed.com/docs/api/#discovery", "language": "JSON", "label": "The protected resource metadata", "kind": "response", "code": "{\n \"resource\": \"https://pay.railbed.io/v1\",\n \"resource_name\": \"Railbed API\",\n \"authorization_servers\": [\"https://astounding-resonance-81.authkit.app\"],\n \"scopes_supported\": [\"payments:read\", \"checkouts:write\", \"orders:read\", \"orders:write\", \"customers:read\"],\n \"bearer_methods_supported\": [\"header\"],\n \"resource_documentation\": \"https://railbed.com/docs/api/\"\n}" }, { "page": "api", "section": "Pagination", "url": "https://railbed.com/docs/api/#pagination", "language": "JSON", "label": "A page", "kind": "response", "code": "{\n \"data\": [{ \"id\": \"pay_…\", \"object\": \"payment\", \"status\": \"paid\" }],\n \"has_more\": true,\n \"next_cursor\": \"pay_Q3cNtwPT0bRqGmS5eZkB\"\n}" }, { "page": "api", "section": "Errors", "url": "https://railbed.com/docs/api/#errors", "language": "JSON", "label": "An error", "kind": "response", "code": "{\n \"error\": {\n \"code\": \"invalid_amount\",\n \"message\": \"amount must be a decimal string between \\\"1.00\\\" and \\\"100000.00\\\".\",\n \"field\": \"amount\"\n }\n}" }, { "page": "api/checkout-sessions", "section": "Create a checkout session", "url": "https://railbed.com/docs/api/checkout-sessions/#create-a-checkout-session", "language": "cURL", "label": "cURL", "kind": "code", "code": "curl https://pay.railbed.io/v1/checkout_sessions \\\n -H \"Authorization: Bearer $RAILBED_SECRET_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -H \"Idempotency-Key: order_1042\" \\\n -d '{\n \"amount\": \"49.00\",\n \"currency\": \"USD\",\n \"description\": \"Pro Membership\",\n \"reference\": \"order_1042\",\n \"customer_email\": \"buyer@example.com\",\n \"metadata\": { \"user_id\": \"player_1042\" },\n \"success_url\":\n \"https://yourstore.com/thanks?order={REFERENCE}&payment={PAYMENT_ID}\",\n \"cancel_url\": \"https://yourstore.com/cart\"\n }'" }, { "page": "api/checkout-sessions", "section": "Create a checkout session", "url": "https://railbed.com/docs/api/checkout-sessions/#create-a-checkout-session", "language": "Node.js", "label": "Node.js", "kind": "code", "code": "const res = await fetch('https://pay.railbed.io/v1/checkout_sessions', {\n method: 'POST',\n headers: {\n Authorization: `Bearer ${process.env.RAILBED_SECRET_KEY}`,\n 'Content-Type': 'application/json',\n 'Idempotency-Key': 'order_1042',\n },\n body: JSON.stringify({\n amount: '49.00',\n currency: 'USD',\n description: 'Pro Membership',\n reference: 'order_1042',\n customer_email: 'buyer@example.com',\n metadata: { user_id: 'player_1042' },\n success_url:\n 'https://yourstore.com/thanks?order={REFERENCE}&payment={PAYMENT_ID}',\n cancel_url: 'https://yourstore.com/cart',\n }),\n});\nif (!res.ok) throw new Error((await res.json()).error.code);\nconst session = await res.json();" }, { "page": "api/checkout-sessions", "section": "Create a checkout session", "url": "https://railbed.com/docs/api/checkout-sessions/#create-a-checkout-session", "language": "Python", "label": "Python", "kind": "code", "code": "r = requests.post(\n \"https://pay.railbed.io/v1/checkout_sessions\",\n headers={\n \"Authorization\": f\"Bearer {os.environ['RAILBED_SECRET_KEY']}\",\n \"Idempotency-Key\": \"order_1042\",\n },\n json={\n \"amount\": \"49.00\",\n \"currency\": \"USD\",\n \"description\": \"Pro Membership\",\n \"reference\": \"order_1042\",\n \"customer_email\": \"buyer@example.com\",\n \"metadata\": {\"user_id\": \"player_1042\"},\n \"success_url\": (\n \"https://yourstore.com/thanks?order={REFERENCE}&payment={PAYMENT_ID}\"\n ),\n \"cancel_url\": \"https://yourstore.com/cart\",\n },\n timeout=15,\n)\nr.raise_for_status()\nsession = r.json()" }, { "page": "api/checkout-sessions", "section": "Create a checkout session", "url": "https://railbed.com/docs/api/checkout-sessions/#create-a-checkout-session", "language": "PHP", "label": "PHP", "kind": "code", "code": " true,\n CURLOPT_RETURNTRANSFER => true,\n CURLOPT_HTTPHEADER => [\n 'Authorization: Bearer ' . getenv('RAILBED_SECRET_KEY'),\n 'Content-Type: application/json',\n 'Idempotency-Key: order_1042',\n ],\n CURLOPT_POSTFIELDS => json_encode([\n 'amount' => '49.00',\n 'currency' => 'USD',\n 'description' => 'Pro Membership',\n 'reference' => 'order_1042',\n 'customer_email' => 'buyer@example.com',\n 'metadata' => ['user_id' => 'player_1042'],\n 'success_url' =>\n 'https://yourstore.com/thanks?order={REFERENCE}&payment={PAYMENT_ID}',\n 'cancel_url' => 'https://yourstore.com/cart',\n ]),\n]);\n$session = json_decode(curl_exec($ch), true);" }, { "page": "api/checkout-sessions", "section": "Create a checkout session", "url": "https://railbed.com/docs/api/checkout-sessions/#create-a-checkout-session", "language": "JSON", "label": "Response", "kind": "response", "code": "{\n \"id\": \"pay_7AAiYH0Ykt11ED4hmfiN\",\n \"object\": \"checkout_session\",\n \"url\": \"https://pay.railbed.io/p/pay_7AAiYH0Ykt11ED4hmfiN\",\n \"status\": \"open\",\n \"livemode\": false,\n \"amount\": \"49.00\",\n \"currency\": \"USD\",\n \"description\": \"Pro Membership\",\n \"reference\": \"order_1042\",\n \"customer_email\": \"buyer@example.com\",\n \"created\": 1790380525,\n \"expires_at\": 1790466925,\n \"started_at\": null,\n \"metadata\": { \"user_id\": \"player_1042\" },\n \"order_id\": \"ord_M4tQx8ZkP1vRn6WcLs2B\"\n}" }, { "page": "api/checkout-sessions", "section": "Orders and customers", "url": "https://railbed.com/docs/api/checkout-sessions/#orders-and-customers", "language": "cURL", "label": "cURL", "kind": "code", "code": "curl https://pay.railbed.io/v1/checkout_sessions \\\n -H \"Authorization: Bearer $RAILBED_SECRET_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -H \"Idempotency-Key: order_1042-attempt-1\" \\\n -d '{\n \"amount\": \"135.31\",\n \"currency\": \"USD\",\n \"description\": \"Order #1042\",\n \"reference\": \"order_1042\",\n \"customer_email\": \"maya@example.com\",\n \"customer\": {\n \"name\": \"Maya Okafor\",\n \"phone\": \"+1 503 555 0142\",\n \"id\": \"88\"\n },\n \"order\": {\n \"id\": \"1042\",\n \"number\": \"1042\",\n \"url\": \"https://yourstore.com/admin/orders/1042\",\n \"store\": {\n \"id\": \"yourstore\",\n \"name\": \"yourstore.com\",\n \"url\": \"https://yourstore.com\"\n },\n \"items\": [\n {\n \"name\": \"Magnesium glycinate\",\n \"variant\": \"120 capsules\",\n \"sku\": \"HN-MG-120\",\n \"quantity\": 2,\n \"unit_amount\": \"32.00\",\n \"amount\": \"64.00\"\n },\n {\n \"name\": \"Daily greens\",\n \"sku\": \"HN-DG-30\",\n \"quantity\": 1,\n \"amount\": \"54.00\"\n },\n { \"name\": \"Shaker bottle\", \"quantity\": 1, \"amount\": \"12.00\" }\n ],\n \"discount\": \"13.00\",\n \"discount_code\": \"WELCOME10\",\n \"shipping\": \"8.95\",\n \"shipping_method\": \"Standard\",\n \"tax\": \"9.36\",\n \"shipping_address\": {\n \"name\": \"Maya Okafor\",\n \"line1\": \"418 Linden Avenue\",\n \"line2\": \"Apt 3B\",\n \"city\": \"Portland\",\n \"region\": \"OR\",\n \"postal_code\": \"97214\",\n \"country\": \"US\"\n }\n },\n \"success_url\": \"https://yourstore.com/orders/1042/thanks\"\n }'" }, { "page": "api/checkout-sessions", "section": "Orders and customers", "url": "https://railbed.com/docs/api/checkout-sessions/#orders-and-customers", "language": "Node.js", "label": "Node.js", "kind": "code", "code": "const res = await fetch('https://pay.railbed.io/v1/checkout_sessions', {\n method: 'POST',\n headers: {\n Authorization: `Bearer ${process.env.RAILBED_SECRET_KEY}`,\n 'Content-Type': 'application/json',\n 'Idempotency-Key': 'order_1042-attempt-1',\n },\n body: JSON.stringify({\n amount: '135.31',\n currency: 'USD',\n description: 'Order #1042',\n reference: 'order_1042',\n customer_email: 'maya@example.com',\n customer: { name: 'Maya Okafor', phone: '+1 503 555 0142', id: '88' },\n order: {\n id: '1042',\n number: '1042',\n url: 'https://yourstore.com/admin/orders/1042',\n store: {\n id: 'yourstore',\n name: 'yourstore.com',\n url: 'https://yourstore.com',\n },\n items: [\n {\n name: 'Magnesium glycinate',\n variant: '120 capsules',\n sku: 'HN-MG-120',\n quantity: 2,\n unit_amount: '32.00',\n amount: '64.00',\n },\n { name: 'Daily greens', sku: 'HN-DG-30', quantity: 1, amount: '54.00' },\n { name: 'Shaker bottle', quantity: 1, amount: '12.00' },\n ],\n discount: '13.00',\n discount_code: 'WELCOME10',\n shipping: '8.95',\n shipping_method: 'Standard',\n tax: '9.36',\n shipping_address: {\n name: 'Maya Okafor',\n line1: '418 Linden Avenue',\n line2: 'Apt 3B',\n city: 'Portland',\n region: 'OR',\n postal_code: '97214',\n country: 'US',\n },\n },\n success_url: 'https://yourstore.com/orders/1042/thanks',\n }),\n});\nif (!res.ok) throw new Error((await res.json()).error.code);\nconst session = await res.json();" }, { "page": "api/checkout-sessions", "section": "Orders and customers", "url": "https://railbed.com/docs/api/checkout-sessions/#orders-and-customers", "language": "Python", "label": "Python", "kind": "code", "code": "r = requests.post(\n \"https://pay.railbed.io/v1/checkout_sessions\",\n headers={\n \"Authorization\": f\"Bearer {os.environ['RAILBED_SECRET_KEY']}\",\n \"Idempotency-Key\": \"order_1042-attempt-1\",\n },\n json={\n \"amount\": \"135.31\",\n \"currency\": \"USD\",\n \"description\": \"Order #1042\",\n \"reference\": \"order_1042\",\n \"customer_email\": \"maya@example.com\",\n \"customer\": {\n \"name\": \"Maya Okafor\",\n \"phone\": \"+1 503 555 0142\",\n \"id\": \"88\",\n },\n \"order\": {\n \"id\": \"1042\",\n \"number\": \"1042\",\n \"url\": \"https://yourstore.com/admin/orders/1042\",\n \"store\": {\n \"id\": \"yourstore\",\n \"name\": \"yourstore.com\",\n \"url\": \"https://yourstore.com\",\n },\n \"items\": [\n {\n \"name\": \"Magnesium glycinate\",\n \"variant\": \"120 capsules\",\n \"sku\": \"HN-MG-120\",\n \"quantity\": 2,\n \"unit_amount\": \"32.00\",\n \"amount\": \"64.00\",\n },\n {\n \"name\": \"Daily greens\",\n \"sku\": \"HN-DG-30\",\n \"quantity\": 1,\n \"amount\": \"54.00\",\n },\n {\"name\": \"Shaker bottle\", \"quantity\": 1, \"amount\": \"12.00\"},\n ],\n \"discount\": \"13.00\",\n \"discount_code\": \"WELCOME10\",\n \"shipping\": \"8.95\",\n \"shipping_method\": \"Standard\",\n \"tax\": \"9.36\",\n \"shipping_address\": {\n \"name\": \"Maya Okafor\",\n \"line1\": \"418 Linden Avenue\",\n \"line2\": \"Apt 3B\",\n \"city\": \"Portland\",\n \"region\": \"OR\",\n \"postal_code\": \"97214\",\n \"country\": \"US\",\n },\n },\n \"success_url\": \"https://yourstore.com/orders/1042/thanks\",\n },\n timeout=15,\n)\nr.raise_for_status()\nsession = r.json()" }, { "page": "api/checkout-sessions", "section": "Orders and customers", "url": "https://railbed.com/docs/api/checkout-sessions/#orders-and-customers", "language": "PHP", "label": "PHP", "kind": "code", "code": " true,\n CURLOPT_RETURNTRANSFER => true,\n CURLOPT_HTTPHEADER => [\n 'Authorization: Bearer ' . getenv('RAILBED_SECRET_KEY'),\n 'Content-Type: application/json',\n 'Idempotency-Key: order_1042-attempt-1',\n ],\n CURLOPT_POSTFIELDS => json_encode([\n 'amount' => '135.31',\n 'currency' => 'USD',\n 'description' => 'Order #1042',\n 'reference' => 'order_1042',\n 'customer_email' => 'maya@example.com',\n 'customer' => [\n 'name' => 'Maya Okafor',\n 'phone' => '+1 503 555 0142',\n 'id' => '88',\n ],\n 'order' => [\n 'id' => '1042',\n 'number' => '1042',\n 'url' => 'https://yourstore.com/admin/orders/1042',\n 'store' => [\n 'id' => 'yourstore',\n 'name' => 'yourstore.com',\n 'url' => 'https://yourstore.com',\n ],\n 'items' => [\n [\n 'name' => 'Magnesium glycinate',\n 'variant' => '120 capsules',\n 'sku' => 'HN-MG-120',\n 'quantity' => 2,\n 'unit_amount' => '32.00',\n 'amount' => '64.00',\n ],\n [\n 'name' => 'Daily greens',\n 'sku' => 'HN-DG-30',\n 'quantity' => 1,\n 'amount' => '54.00',\n ],\n ['name' => 'Shaker bottle', 'quantity' => 1, 'amount' => '12.00'],\n ],\n 'discount' => '13.00',\n 'discount_code' => 'WELCOME10',\n 'shipping' => '8.95',\n 'shipping_method' => 'Standard',\n 'tax' => '9.36',\n 'shipping_address' => [\n 'name' => 'Maya Okafor',\n 'line1' => '418 Linden Avenue',\n 'line2' => 'Apt 3B',\n 'city' => 'Portland',\n 'region' => 'OR',\n 'postal_code' => '97214',\n 'country' => 'US',\n ],\n ],\n 'success_url' => 'https://yourstore.com/orders/1042/thanks',\n ]),\n]);\n$session = json_decode(curl_exec($ch), true);" }, { "page": "api/checkout-sessions", "section": "Orders and customers", "url": "https://railbed.com/docs/api/checkout-sessions/#orders-and-customers", "language": "JSON", "label": "Response", "kind": "response", "code": "{\n \"id\": \"pay_Rt5Wm2KxQ8zLb3NvYc7P\",\n \"object\": \"checkout_session\",\n \"url\": \"https://pay.railbed.io/p/pay_Rt5Wm2KxQ8zLb3NvYc7P\",\n \"status\": \"open\",\n \"livemode\": true,\n \"amount\": \"135.31\",\n \"currency\": \"USD\",\n \"description\": \"Order #1042\",\n \"reference\": \"order_1042\",\n \"customer_email\": \"maya@example.com\",\n \"created\": 1790380525,\n \"expires_at\": 1790466925,\n \"started_at\": null,\n \"metadata\": null,\n \"order_id\": \"ord_Vd3kR8mQ1xTn6LpZs0Wa\"\n}" }, { "page": "api/checkout-sessions", "section": "Retrieve a checkout session", "url": "https://railbed.com/docs/api/checkout-sessions/#retrieve-a-checkout-session", "language": "cURL", "label": "cURL", "kind": "code", "code": "curl https://pay.railbed.io/v1/checkout_sessions/pay_7AAiYH0Ykt11ED4hmfiN \\\n -H \"Authorization: Bearer $RAILBED_SECRET_KEY\"" }, { "page": "api/checkout-sessions", "section": "Retrieve a checkout session", "url": "https://railbed.com/docs/api/checkout-sessions/#retrieve-a-checkout-session", "language": "Node.js", "label": "Node.js", "kind": "code", "code": "const session = await fetch(`https://pay.railbed.io/v1/checkout_sessions/${id}`, {\n headers: { Authorization: `Bearer ${process.env.RAILBED_SECRET_KEY}` },\n}).then((r) => r.json());" }, { "page": "api/checkout-sessions", "section": "Retrieve a checkout session", "url": "https://railbed.com/docs/api/checkout-sessions/#retrieve-a-checkout-session", "language": "Python", "label": "Python", "kind": "code", "code": "session = requests.get(\n f\"https://pay.railbed.io/v1/checkout_sessions/{id}\",\n headers={\"Authorization\": f\"Bearer {os.environ['RAILBED_SECRET_KEY']}\"},\n timeout=15,\n).json()" }, { "page": "api/checkout-sessions", "section": "Retrieve a checkout session", "url": "https://railbed.com/docs/api/checkout-sessions/#retrieve-a-checkout-session", "language": "PHP", "label": "PHP", "kind": "code", "code": " true,\n CURLOPT_HTTPHEADER => [\n 'Authorization: Bearer ' . getenv('RAILBED_SECRET_KEY'),\n ],\n]);\n$session = json_decode(curl_exec($ch), true);" }, { "page": "api/checkout-sessions", "section": "Start a checkout session", "url": "https://railbed.com/docs/api/checkout-sessions/#start-a-checkout-session", "language": "cURL", "label": "cURL", "kind": "code", "code": "curl -X POST \\\n https://pay.railbed.io/v1/checkout_sessions/pay_7AAiYH0Ykt11ED4hmfiN/start \\\n -H \"Authorization: Bearer $RAILBED_SECRET_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{ \"country\": \"US\" }'" }, { "page": "api/checkout-sessions", "section": "Start a checkout session", "url": "https://railbed.com/docs/api/checkout-sessions/#start-a-checkout-session", "language": "Node.js", "label": "Node.js", "kind": "code", "code": "const url = `https://pay.railbed.io/v1/checkout_sessions/${id}/start`;\nconst started = await fetch(url, {\n method: 'POST',\n headers: {\n Authorization: `Bearer ${process.env.RAILBED_SECRET_KEY}`,\n 'Content-Type': 'application/json',\n },\n body: JSON.stringify({ country: 'US' }),\n}).then((r) => r.json());" }, { "page": "api/checkout-sessions", "section": "Start a checkout session", "url": "https://railbed.com/docs/api/checkout-sessions/#start-a-checkout-session", "language": "Python", "label": "Python", "kind": "code", "code": "started = requests.post(\n f\"https://pay.railbed.io/v1/checkout_sessions/{id}/start\",\n headers={\"Authorization\": f\"Bearer {os.environ['RAILBED_SECRET_KEY']}\"},\n json={\"country\": \"US\"},\n timeout=15,\n).json()" }, { "page": "api/checkout-sessions", "section": "Start a checkout session", "url": "https://railbed.com/docs/api/checkout-sessions/#start-a-checkout-session", "language": "PHP", "label": "PHP", "kind": "code", "code": " true,\n CURLOPT_RETURNTRANSFER => true,\n CURLOPT_HTTPHEADER => [\n 'Authorization: Bearer ' . getenv('RAILBED_SECRET_KEY'),\n 'Content-Type: application/json',\n ],\n CURLOPT_POSTFIELDS => json_encode(['country' => 'US']),\n]);\n$started = json_decode(curl_exec($ch), true);" }, { "page": "api/checkout-sessions", "section": "Start a checkout session", "url": "https://railbed.com/docs/api/checkout-sessions/#start-a-checkout-session", "language": "JSON", "label": "Response", "kind": "response", "code": "{\n \"id\": \"pay_7AAiYH0Ykt11ED4hmfiN\",\n \"object\": \"checkout_session\",\n \"url\": \"https://pay.railbed.io/p/pay_7AAiYH0Ykt11ED4hmfiN\",\n \"status\": \"open\",\n \"livemode\": false,\n \"amount\": \"49.00\",\n \"currency\": \"USD\",\n \"description\": \"Pro Membership\",\n \"reference\": \"order_1042\",\n \"customer_email\": \"buyer@example.com\",\n \"created\": 1790380525,\n \"expires_at\": 1790466925,\n \"started_at\": 1790380611,\n \"metadata\": { \"user_id\": \"player_1042\" },\n \"order_id\": \"ord_M4tQx8ZkP1vRn6WcLs2B\",\n \"country\": \"US\",\n \"providers\": [\n {\n \"id\": \"stripe\",\n \"name\": \"Stripe\",\n \"note\": \"Card, Apple Pay or Google Pay\",\n \"recommended\": true,\n \"handoff_url\": \"https://pay.railbed.io/go/pay_7AAiYH0Ykt11ED4hmfiN?provider=stripe\"\n },\n {\n \"id\": \"cashapp\",\n \"name\": \"Cash App\",\n \"note\": \"Cash App balance or card\",\n \"recommended\": false,\n \"handoff_url\": \"https://pay.railbed.io/go/pay_7AAiYH0Ykt11ED4hmfiN?provider=cashapp\"\n }\n ]\n}" }, { "page": "api/payments", "section": "Retrieve a payment", "url": "https://railbed.com/docs/api/payments/#retrieve-a-payment", "language": "cURL", "label": "cURL", "kind": "code", "code": "curl https://pay.railbed.io/v1/payments/pay_7AAiYH0Ykt11ED4hmfiN \\\n -H \"Authorization: Bearer $RAILBED_SECRET_KEY\"" }, { "page": "api/payments", "section": "Retrieve a payment", "url": "https://railbed.com/docs/api/payments/#retrieve-a-payment", "language": "Node.js", "label": "Node.js", "kind": "code", "code": "const payment = await fetch(`https://pay.railbed.io/v1/payments/${id}`, {\n headers: { Authorization: `Bearer ${process.env.RAILBED_SECRET_KEY}` },\n}).then((r) => r.json());" }, { "page": "api/payments", "section": "Retrieve a payment", "url": "https://railbed.com/docs/api/payments/#retrieve-a-payment", "language": "Python", "label": "Python", "kind": "code", "code": "payment = requests.get(\n f\"https://pay.railbed.io/v1/payments/{id}\",\n headers={\"Authorization\": f\"Bearer {os.environ['RAILBED_SECRET_KEY']}\"},\n timeout=15,\n).json()" }, { "page": "api/payments", "section": "Retrieve a payment", "url": "https://railbed.com/docs/api/payments/#retrieve-a-payment", "language": "PHP", "label": "PHP", "kind": "code", "code": " true,\n CURLOPT_HTTPHEADER => [\n 'Authorization: Bearer ' . getenv('RAILBED_SECRET_KEY'),\n ],\n]);\n$payment = json_decode(curl_exec($ch), true);" }, { "page": "api/payments", "section": "Retrieve a payment", "url": "https://railbed.com/docs/api/payments/#retrieve-a-payment", "language": "JSON", "label": "Response", "kind": "response", "code": "{\n \"id\": \"pay_7AAiYH0Ykt11ED4hmfiN\",\n \"object\": \"payment\",\n \"url\": \"https://pay.railbed.io/p/pay_7AAiYH0Ykt11ED4hmfiN\",\n \"status\": \"paid\",\n \"livemode\": true,\n \"amount\": \"49.00\",\n \"currency\": \"USD\",\n \"description\": \"Pro Membership\",\n \"reference\": \"order_1042\",\n \"customer_email\": \"buyer@example.com\",\n \"created\": 1790380525,\n \"expires_at\": 1790466925,\n \"started_at\": 1790380611,\n \"metadata\": { \"user_id\": \"player_1042\" },\n \"order_id\": \"ord_M4tQx8ZkP1vRn6WcLs2B\",\n \"paid_at\": 1790381342,\n \"provider\": \"stripe\",\n \"hold_reason\": null,\n \"hold_acceptable\": false,\n \"canceled_at\": null,\n \"settlement\": {\n \"coin\": \"polygon_usdc\",\n \"value_coin\": \"47.53\",\n \"merchant_received\": \"46.341750\",\n \"txid_in\": \"0x0c651ba1d59c7a32e8b1f4bd2c7e0e4f96a55d13a6b0f2d1c8e7a9b4f3d29b58\",\n \"txid_out\": \"0x8202d1373e0a9c4f1b6d5e2c7a8f9b0e1d2c3b4a5f6e7d8c9b0a1f2e3d7356ff\",\n \"payout_wallet\": \"0xF977814e90dA44bFA03b6295A0616a897441aceC\"\n }\n}" }, { "page": "api/payments", "section": "Retrieve a payment", "url": "https://railbed.com/docs/api/payments/#retrieve-a-payment", "language": "JSON", "label": "A held payment (trimmed)", "kind": "response", "code": "{\n \"id\": \"pay_Kx81mQv2PzR0dT7eWcYa\",\n \"object\": \"payment\",\n \"status\": \"held\",\n \"amount\": \"49.00\",\n \"currency\": \"USD\",\n \"paid_at\": null,\n \"hold_reason\": \"The provider sent 24.50 USDC, below 90% of the order’s 49.00 USD value.\",\n \"hold_acceptable\": true,\n \"settlement\": { \"coin\": \"polygon_usdc\", \"value_coin\": \"24.50\", \"merchant_received\": null }\n}" }, { "page": "api/payments", "section": "List payments", "url": "https://railbed.com/docs/api/payments/#list-payments", "language": "cURL", "label": "cURL", "kind": "code", "code": "curl \"https://pay.railbed.io/v1/payments?limit=50\" \\\n -H \"Authorization: Bearer $RAILBED_SECRET_KEY\"" }, { "page": "api/payments", "section": "List payments", "url": "https://railbed.com/docs/api/payments/#list-payments", "language": "Node.js", "label": "Node.js", "kind": "code", "code": "// Every payment, page by page\nlet cursor = null;\ndo {\n const url = new URL('https://pay.railbed.io/v1/payments');\n url.searchParams.set('limit', '100');\n if (cursor) url.searchParams.set('starting_after', cursor);\n const page = await fetch(url, {\n headers: { Authorization: `Bearer ${process.env.RAILBED_SECRET_KEY}` },\n }).then((r) => r.json());\n for (const payment of page.data) reconcile(payment);\n cursor = page.next_cursor;\n} while (cursor);" }, { "page": "api/payments", "section": "List payments", "url": "https://railbed.com/docs/api/payments/#list-payments", "language": "Python", "label": "Python", "kind": "code", "code": "cursor = None\nwhile True:\n params = {\"limit\": 100, **({\"starting_after\": cursor} if cursor else {})}\n page = requests.get(\n \"https://pay.railbed.io/v1/payments\",\n headers={\"Authorization\": f\"Bearer {os.environ['RAILBED_SECRET_KEY']}\"},\n params=params,\n timeout=15,\n ).json()\n for payment in page[\"data\"]:\n reconcile(payment)\n cursor = page[\"next_cursor\"]\n if not cursor:\n break" }, { "page": "api/payments", "section": "List payments", "url": "https://railbed.com/docs/api/payments/#list-payments", "language": "PHP", "label": "PHP", "kind": "code", "code": " 100,\n 'starting_after' => $cursor,\n ]));\n $ch = curl_init('https://pay.railbed.io/v1/payments?' . $query);\n curl_setopt_array($ch, [\n CURLOPT_RETURNTRANSFER => true,\n CURLOPT_HTTPHEADER => [\n 'Authorization: Bearer ' . getenv('RAILBED_SECRET_KEY'),\n ],\n ]);\n $page = json_decode(curl_exec($ch), true);\n foreach ($page['data'] as $payment) reconcile($payment);\n $cursor = $page['next_cursor'];\n} while ($cursor);" }, { "page": "api/payments", "section": "List payments", "url": "https://railbed.com/docs/api/payments/#list-payments", "language": "JSON", "label": "Response", "kind": "response", "code": "{\n \"data\": [\n {\n \"id\": \"pay_7AAiYH0Ykt11ED4hmfiN\",\n \"object\": \"payment\",\n \"status\": \"paid\",\n \"amount\": \"49.00\",\n \"currency\": \"USD\"\n },\n {\n \"id\": \"pay_Kx81mQv2PzR0dT7eWcYa\",\n \"object\": \"payment\",\n \"status\": \"held\",\n \"amount\": \"49.00\",\n \"currency\": \"USD\"\n }\n ],\n \"has_more\": true,\n \"next_cursor\": \"pay_Kx81mQv2PzR0dT7eWcYa\"\n}" }, { "page": "api/payments", "section": "Simulate a payment", "url": "https://railbed.com/docs/api/payments/#simulate-a-payment", "language": "cURL", "label": "cURL", "kind": "code", "code": "curl -X POST \\\n https://pay.railbed.io/v1/payments/pay_7AAiYH0Ykt11ED4hmfiN/simulate \\\n -H \"Authorization: Bearer $RAILBED_SECRET_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{ \"outcome\": \"paid\" }'" }, { "page": "api/payments", "section": "Simulate a payment", "url": "https://railbed.com/docs/api/payments/#simulate-a-payment", "language": "Node.js", "label": "Node.js", "kind": "code", "code": "const payment = await fetch(`https://pay.railbed.io/v1/payments/${id}/simulate`, {\n method: 'POST',\n headers: {\n Authorization: `Bearer ${process.env.RAILBED_SECRET_KEY}`,\n 'Content-Type': 'application/json',\n },\n body: JSON.stringify({ outcome: 'paid' }),\n}).then((r) => r.json());" }, { "page": "api/payments", "section": "Simulate a payment", "url": "https://railbed.com/docs/api/payments/#simulate-a-payment", "language": "Python", "label": "Python", "kind": "code", "code": "payment = requests.post(\n f\"https://pay.railbed.io/v1/payments/{id}/simulate\",\n headers={\"Authorization\": f\"Bearer {os.environ['RAILBED_SECRET_KEY']}\"},\n json={\"outcome\": \"paid\"},\n timeout=15,\n).json()" }, { "page": "api/payments", "section": "Simulate a payment", "url": "https://railbed.com/docs/api/payments/#simulate-a-payment", "language": "PHP", "label": "PHP", "kind": "code", "code": " true,\n CURLOPT_RETURNTRANSFER => true,\n CURLOPT_HTTPHEADER => [\n 'Authorization: Bearer ' . getenv('RAILBED_SECRET_KEY'),\n 'Content-Type: application/json',\n ],\n CURLOPT_POSTFIELDS => json_encode(['outcome' => 'paid']),\n]);\n$payment = json_decode(curl_exec($ch), true);" }, { "page": "api/orders", "section": "The order object", "url": "https://railbed.com/docs/api/orders/#the-order-object", "language": "JSON", "label": "An order from a store", "kind": "response", "code": "{\n \"id\": \"ord_Vd3kR8mQ1xTn6LpZs0Wa\",\n \"object\": \"order\",\n \"livemode\": true,\n \"number\": 1187,\n \"status\": \"paid\",\n \"needs_review\": false,\n \"fulfillment\": \"unfulfilled\",\n \"fulfilled_at\": null,\n \"customer_id\": \"cus_Hc7nQ2wVz9KpT4mRb1Ye\",\n \"currency\": \"USD\",\n \"subtotal\": \"130.00\",\n \"discount\": \"13.00\",\n \"discount_code\": \"WELCOME10\",\n \"shipping\": \"8.95\",\n \"shipping_method\": \"Standard\",\n \"tax\": \"9.36\",\n \"total\": \"135.31\",\n \"amount_paid\": \"135.31\",\n \"items\": [\n {\n \"name\": \"Magnesium glycinate\",\n \"variant\": \"120 capsules\",\n \"sku\": \"HN-MG-120\",\n \"quantity\": 2,\n \"unit_amount\": \"32.00\",\n \"amount\": \"64.00\"\n },\n {\n \"name\": \"Daily greens\",\n \"variant\": null,\n \"sku\": \"HN-DG-30\",\n \"quantity\": 1,\n \"unit_amount\": null,\n \"amount\": \"54.00\"\n },\n {\n \"name\": \"Shaker bottle\",\n \"variant\": null,\n \"sku\": null,\n \"quantity\": 1,\n \"unit_amount\": null,\n \"amount\": \"12.00\"\n }\n ],\n \"shipping_address\": {\n \"name\": \"Maya Okafor\",\n \"line1\": \"418 Linden Avenue\",\n \"line2\": \"Apt 3B\",\n \"city\": \"Portland\",\n \"region\": \"OR\",\n \"postal_code\": \"97214\",\n \"country\": \"US\"\n },\n \"billing_address\": null,\n \"store\": {\n \"platform\": \"other\",\n \"id\": \"yourstore\",\n \"name\": \"yourstore.com\",\n \"url\": \"https://yourstore.com\",\n \"order_id\": \"1042\",\n \"order_number\": \"1042\",\n \"order_url\": \"https://yourstore.com/admin/orders/1042\",\n \"customer_id\": \"88\"\n },\n \"payment_ids\": [\"pay_Rt5Wm2KxQ8zLb3NvYc7P\"],\n \"created\": 1790380525,\n \"paid_at\": 1790381342\n}" }, { "page": "api/orders", "section": "Retrieve an order", "url": "https://railbed.com/docs/api/orders/#retrieve-an-order", "language": "cURL", "label": "cURL", "kind": "code", "code": "curl https://pay.railbed.io/v1/orders/ord_Vd3kR8mQ1xTn6LpZs0Wa \\\n -H \"Authorization: Bearer $RAILBED_SECRET_KEY\"" }, { "page": "api/orders", "section": "Retrieve an order", "url": "https://railbed.com/docs/api/orders/#retrieve-an-order", "language": "Node.js", "label": "Node.js", "kind": "code", "code": "const order = await fetch(`https://pay.railbed.io/v1/orders/${id}`, {\n headers: { Authorization: `Bearer ${process.env.RAILBED_SECRET_KEY}` },\n}).then((r) => r.json());" }, { "page": "api/orders", "section": "Retrieve an order", "url": "https://railbed.com/docs/api/orders/#retrieve-an-order", "language": "Python", "label": "Python", "kind": "code", "code": "order = requests.get(\n f\"https://pay.railbed.io/v1/orders/{id}\",\n headers={\"Authorization\": f\"Bearer {os.environ['RAILBED_SECRET_KEY']}\"},\n timeout=15,\n).json()" }, { "page": "api/orders", "section": "Retrieve an order", "url": "https://railbed.com/docs/api/orders/#retrieve-an-order", "language": "PHP", "label": "PHP", "kind": "code", "code": " true,\n CURLOPT_HTTPHEADER => [\n 'Authorization: Bearer ' . getenv('RAILBED_SECRET_KEY'),\n ],\n]);\n$order = json_decode(curl_exec($ch), true);" }, { "page": "api/orders", "section": "List orders", "url": "https://railbed.com/docs/api/orders/#list-orders", "language": "cURL", "label": "cURL", "kind": "code", "code": "curl \"https://pay.railbed.io/v1/orders?store_id=yourstore&store_order_id=1042\" \\\n -H \"Authorization: Bearer $RAILBED_SECRET_KEY\"" }, { "page": "api/orders", "section": "List orders", "url": "https://railbed.com/docs/api/orders/#list-orders", "language": "Node.js", "label": "Node.js", "kind": "code", "code": "const url = new URL('https://pay.railbed.io/v1/orders');\nurl.searchParams.set('store_id', 'yourstore');\nurl.searchParams.set('store_order_id', '1042');\nconst page = await fetch(url, {\n headers: { Authorization: `Bearer ${process.env.RAILBED_SECRET_KEY}` },\n}).then((r) => r.json());\nconst order = page.data[0] ?? null;" }, { "page": "api/orders", "section": "List orders", "url": "https://railbed.com/docs/api/orders/#list-orders", "language": "Python", "label": "Python", "kind": "code", "code": "page = requests.get(\n \"https://pay.railbed.io/v1/orders\",\n headers={\"Authorization\": f\"Bearer {os.environ['RAILBED_SECRET_KEY']}\"},\n params={\"store_id\": \"yourstore\", \"store_order_id\": \"1042\"},\n timeout=15,\n).json()\norder = page[\"data\"][0] if page[\"data\"] else None" }, { "page": "api/orders", "section": "List orders", "url": "https://railbed.com/docs/api/orders/#list-orders", "language": "PHP", "label": "PHP", "kind": "code", "code": " 'yourstore',\n 'store_order_id' => '1042',\n]);\n$ch = curl_init('https://pay.railbed.io/v1/orders?' . $query);\ncurl_setopt_array($ch, [\n CURLOPT_RETURNTRANSFER => true,\n CURLOPT_HTTPHEADER => [\n 'Authorization: Bearer ' . getenv('RAILBED_SECRET_KEY'),\n ],\n]);\n$page = json_decode(curl_exec($ch), true);\n$order = $page['data'][0] ?? null;" }, { "page": "api/orders", "section": "List orders", "url": "https://railbed.com/docs/api/orders/#list-orders", "language": "JSON", "label": "Response (trimmed)", "kind": "response", "code": "{\n \"data\": [\n {\n \"id\": \"ord_Vd3kR8mQ1xTn6LpZs0Wa\",\n \"object\": \"order\",\n \"number\": 1187,\n \"status\": \"paid\",\n \"fulfillment\": \"unfulfilled\",\n \"total\": \"135.31\"\n }\n ],\n \"has_more\": false,\n \"next_cursor\": null\n}" }, { "page": "api/orders", "section": "Update an order", "url": "https://railbed.com/docs/api/orders/#update-an-order", "language": "cURL", "label": "cURL", "kind": "code", "code": "curl -X PATCH \\\n https://pay.railbed.io/v1/orders/ord_Vd3kR8mQ1xTn6LpZs0Wa \\\n -H \"Authorization: Bearer $RAILBED_SECRET_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{ \"fulfillment\": \"fulfilled\" }'" }, { "page": "api/orders", "section": "Update an order", "url": "https://railbed.com/docs/api/orders/#update-an-order", "language": "Node.js", "label": "Node.js", "kind": "code", "code": "const order = await fetch(`https://pay.railbed.io/v1/orders/${id}`, {\n method: 'PATCH',\n headers: {\n Authorization: `Bearer ${process.env.RAILBED_SECRET_KEY}`,\n 'Content-Type': 'application/json',\n },\n body: JSON.stringify({ fulfillment: 'fulfilled' }),\n}).then((r) => r.json());" }, { "page": "api/orders", "section": "Update an order", "url": "https://railbed.com/docs/api/orders/#update-an-order", "language": "Python", "label": "Python", "kind": "code", "code": "order = requests.patch(\n f\"https://pay.railbed.io/v1/orders/{id}\",\n headers={\"Authorization\": f\"Bearer {os.environ['RAILBED_SECRET_KEY']}\"},\n json={\"fulfillment\": \"fulfilled\"},\n timeout=15,\n).json()" }, { "page": "api/orders", "section": "Update an order", "url": "https://railbed.com/docs/api/orders/#update-an-order", "language": "PHP", "label": "PHP", "kind": "code", "code": " 'PATCH',\n CURLOPT_RETURNTRANSFER => true,\n CURLOPT_HTTPHEADER => [\n 'Authorization: Bearer ' . getenv('RAILBED_SECRET_KEY'),\n 'Content-Type: application/json',\n ],\n CURLOPT_POSTFIELDS => json_encode(['fulfillment' => 'fulfilled']),\n]);\n$order = json_decode(curl_exec($ch), true);" }, { "page": "api/orders", "section": "Report a cancellation or refund", "url": "https://railbed.com/docs/api/orders/#report-a-cancellation-or-refund", "language": "cURL", "label": "cURL", "kind": "code", "code": "curl https://pay.railbed.io/v1/orders/ord_Vd3kR8mQ1xTn6LpZs0Wa/events \\\n -H \"Authorization: Bearer $RAILBED_SECRET_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{ \"type\": \"refunded\", \"id\": \"refund-5521\", \"amount\": \"12.00\" }'" }, { "page": "api/orders", "section": "Report a cancellation or refund", "url": "https://railbed.com/docs/api/orders/#report-a-cancellation-or-refund", "language": "Node.js", "label": "Node.js", "kind": "code", "code": "const event = await fetch(`https://pay.railbed.io/v1/orders/${id}/events`, {\n method: 'POST',\n headers: {\n Authorization: `Bearer ${process.env.RAILBED_SECRET_KEY}`,\n 'Content-Type': 'application/json',\n },\n body: JSON.stringify({ type: 'refunded', id: 'refund-5521', amount: '12.00' }),\n}).then((r) => r.json());" }, { "page": "api/orders", "section": "Report a cancellation or refund", "url": "https://railbed.com/docs/api/orders/#report-a-cancellation-or-refund", "language": "Python", "label": "Python", "kind": "code", "code": "event = requests.post(\n f\"https://pay.railbed.io/v1/orders/{id}/events\",\n headers={\"Authorization\": f\"Bearer {os.environ['RAILBED_SECRET_KEY']}\"},\n json={\"type\": \"refunded\", \"id\": \"refund-5521\", \"amount\": \"12.00\"},\n timeout=15,\n).json()" }, { "page": "api/orders", "section": "Report a cancellation or refund", "url": "https://railbed.com/docs/api/orders/#report-a-cancellation-or-refund", "language": "PHP", "label": "PHP", "kind": "code", "code": " true,\n CURLOPT_RETURNTRANSFER => true,\n CURLOPT_HTTPHEADER => [\n 'Authorization: Bearer ' . getenv('RAILBED_SECRET_KEY'),\n 'Content-Type: application/json',\n ],\n CURLOPT_POSTFIELDS => json_encode(['type' => 'refunded', 'id' => 'refund-5521', 'amount' => '12.00']),\n]);\n$event = json_decode(curl_exec($ch), true);" }, { "page": "api/orders", "section": "Report a cancellation or refund", "url": "https://railbed.com/docs/api/orders/#report-a-cancellation-or-refund", "language": "JSON", "label": "The recorded event", "kind": "response", "code": "{\n \"id\": \"oev_Tb8vN3qLx5WmR2kZc9Hd\",\n \"object\": \"order_event\",\n \"order_id\": \"ord_Vd3kR8mQ1xTn6LpZs0Wa\",\n \"type\": \"refunded\",\n \"store_event_id\": \"refund-5521\",\n \"amount\": \"12.00\",\n \"currency\": \"USD\",\n \"created\": 1790467742\n}" }, { "page": "api/customers", "section": "The customer object", "url": "https://railbed.com/docs/api/customers/#the-customer-object", "language": "JSON", "label": "A customer", "kind": "response", "code": "{\n \"id\": \"cus_Hc7nQ2wVz9KpT4mRb1Ye\",\n \"object\": \"customer\",\n \"livemode\": true,\n \"email\": \"maya@example.com\",\n \"name\": \"Maya Okafor\",\n \"phone\": \"+1 503 555 0142\",\n \"shipping_address\": {\n \"name\": \"Maya Okafor\",\n \"line1\": \"418 Linden Avenue\",\n \"line2\": \"Apt 3B\",\n \"city\": \"Portland\",\n \"region\": \"OR\",\n \"postal_code\": \"97214\",\n \"country\": \"US\"\n },\n \"billing_address\": null,\n \"store_accounts\": [],\n \"orders_count\": 3,\n \"paid_orders_count\": 2,\n \"spent\": { \"USD\": \"224.31\" },\n \"created\": 1787702525,\n \"last_order_at\": 1790380525,\n \"erased\": false\n}" }, { "page": "api/customers", "section": "Retrieve a customer", "url": "https://railbed.com/docs/api/customers/#retrieve-a-customer", "language": "cURL", "label": "cURL", "kind": "code", "code": "curl https://pay.railbed.io/v1/customers/cus_Hc7nQ2wVz9KpT4mRb1Ye \\\n -H \"Authorization: Bearer $RAILBED_SECRET_KEY\"" }, { "page": "api/customers", "section": "Retrieve a customer", "url": "https://railbed.com/docs/api/customers/#retrieve-a-customer", "language": "Node.js", "label": "Node.js", "kind": "code", "code": "const customer = await fetch(`https://pay.railbed.io/v1/customers/${id}`, {\n headers: { Authorization: `Bearer ${process.env.RAILBED_SECRET_KEY}` },\n}).then((r) => r.json());" }, { "page": "api/customers", "section": "Retrieve a customer", "url": "https://railbed.com/docs/api/customers/#retrieve-a-customer", "language": "Python", "label": "Python", "kind": "code", "code": "customer = requests.get(\n f\"https://pay.railbed.io/v1/customers/{id}\",\n headers={\"Authorization\": f\"Bearer {os.environ['RAILBED_SECRET_KEY']}\"},\n timeout=15,\n).json()" }, { "page": "api/customers", "section": "Retrieve a customer", "url": "https://railbed.com/docs/api/customers/#retrieve-a-customer", "language": "PHP", "label": "PHP", "kind": "code", "code": " true,\n CURLOPT_HTTPHEADER => [\n 'Authorization: Bearer ' . getenv('RAILBED_SECRET_KEY'),\n ],\n]);\n$customer = json_decode(curl_exec($ch), true);" }, { "page": "api/customers", "section": "List customers", "url": "https://railbed.com/docs/api/customers/#list-customers", "language": "cURL", "label": "cURL", "kind": "code", "code": "curl -G https://pay.railbed.io/v1/customers \\\n --data-urlencode \"email=maya@example.com\" \\\n -H \"Authorization: Bearer $RAILBED_SECRET_KEY\"" }, { "page": "api/customers", "section": "List customers", "url": "https://railbed.com/docs/api/customers/#list-customers", "language": "Node.js", "label": "Node.js", "kind": "code", "code": "const url = new URL('https://pay.railbed.io/v1/customers');\nurl.searchParams.set('email', 'maya@example.com');\nconst page = await fetch(url, {\n headers: { Authorization: `Bearer ${process.env.RAILBED_SECRET_KEY}` },\n}).then((r) => r.json());\nconst customer = page.data[0] ?? null;" }, { "page": "api/customers", "section": "List customers", "url": "https://railbed.com/docs/api/customers/#list-customers", "language": "Python", "label": "Python", "kind": "code", "code": "page = requests.get(\n \"https://pay.railbed.io/v1/customers\",\n headers={\"Authorization\": f\"Bearer {os.environ['RAILBED_SECRET_KEY']}\"},\n params={\"email\": \"maya@example.com\"},\n timeout=15,\n).json()\ncustomer = page[\"data\"][0] if page[\"data\"] else None" }, { "page": "api/customers", "section": "List customers", "url": "https://railbed.com/docs/api/customers/#list-customers", "language": "PHP", "label": "PHP", "kind": "code", "code": " 'maya@example.com']);\n$ch = curl_init('https://pay.railbed.io/v1/customers?' . $query);\ncurl_setopt_array($ch, [\n CURLOPT_RETURNTRANSFER => true,\n CURLOPT_HTTPHEADER => [\n 'Authorization: Bearer ' . getenv('RAILBED_SECRET_KEY'),\n ],\n]);\n$page = json_decode(curl_exec($ch), true);\n$customer = $page['data'][0] ?? null;" }, { "page": "api/customers", "section": "List customers", "url": "https://railbed.com/docs/api/customers/#list-customers", "language": "JSON", "label": "Response (trimmed)", "kind": "response", "code": "{\n \"data\": [\n {\n \"id\": \"cus_Hc7nQ2wVz9KpT4mRb1Ye\",\n \"object\": \"customer\",\n \"email\": \"maya@example.com\",\n \"name\": \"Maya Okafor\",\n \"paid_orders_count\": 2\n }\n ],\n \"has_more\": false,\n \"next_cursor\": null\n}" }, { "page": "api/errors", "section": "The error object", "url": "https://railbed.com/docs/api/errors/#the-error-object", "language": "JSON", "label": "An error", "kind": "response", "code": "{\n \"error\": {\n \"code\": \"no_payout_wallet\",\n \"message\": \"Add a payout wallet in the dashboard before taking live payments.\"\n }\n}" }, { "page": "api/errors", "section": "Handling errors", "url": "https://railbed.com/docs/api/errors/#handling-errors", "language": "Node.js", "label": "A small error handler", "kind": "code", "code": "async function railbed(path, init = {}) {\n const res = await fetch(`https://pay.railbed.io/v1${path}`, {\n ...init,\n headers: {\n Authorization: `Bearer ${process.env.RAILBED_SECRET_KEY}`,\n 'Content-Type': 'application/json',\n ...init.headers,\n },\n });\n const body = await res.json();\n if (res.ok) return body;\n const err = Object.assign(new Error(body.error.message), {\n status: res.status,\n code: body.error.code,\n field: body.error.field,\n });\n err.retryable = res.status === 429 || res.status >= 500;\n err.retryAfter = Number(res.headers.get('Retry-After')) || null;\n throw err;\n}" }, { "page": "webhooks", "section": "A receiver, end to end", "url": "https://railbed.com/docs/webhooks/#a-receiver-end-to-end", "language": "Node.js", "label": "Node.js · Express", "kind": "code", "code": "import crypto from 'node:crypto';\nimport express from 'express';\n\nconst app = express();\n\n// The raw body: verify exactly the bytes that were signed.\nconst rawJson = express.raw({ type: 'application/json' });\n\napp.post('/webhooks/railbed', rawJson, async (req, res) => {\n const raw = req.body.toString('utf8');\n const secret = process.env.RAILBED_WEBHOOK_SECRET;\n const header = req.get('Railbed-Signature');\n if (!verify(raw, header, secret)) return res.sendStatus(400);\n\n const event = JSON.parse(raw);\n const isNew = await db.events.insertIfAbsent(event.id); // UNIQUE(id)\n if (isNew && event.type === 'payment.paid') {\n await queue.add('fulfil', { paymentId: event.data.payment.id });\n }\n res.sendStatus(200);\n});\n\nfunction verify(raw, header, secret) {\n const m = /^t=(\\d+),v1=([0-9a-f]{64})$/.exec(header ?? '');\n if (!m) return false;\n if (Math.abs(Date.now() / 1000 - Number(m[1])) > 300) return false;\n const expected = crypto\n .createHmac('sha256', secret)\n .update(`${m[1]}.${raw}`)\n .digest('hex');\n return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(m[2]));\n}" }, { "page": "webhooks", "section": "A receiver, end to end", "url": "https://railbed.com/docs/webhooks/#a-receiver-end-to-end", "language": "Python", "label": "Python · Flask", "kind": "code", "code": "import hashlib, hmac, os, re, time\nfrom flask import Flask, request\n\napp = Flask(__name__)\n\n@app.post(\"/webhooks/railbed\")\ndef railbed_webhook():\n raw = request.get_data() # the raw bytes, before any JSON parsing\n header = request.headers.get(\"Railbed-Signature\", \"\")\n if not verify(raw, header, os.environ[\"RAILBED_WEBHOOK_SECRET\"]):\n return \"\", 400\n event = request.get_json()\n is_new = db.events.insert_if_absent(event[\"id\"])\n if is_new and event[\"type\"] == \"payment.paid\":\n queue.enqueue(\"fulfil\", event[\"data\"][\"payment\"][\"id\"])\n return \"\", 200\n\ndef verify(raw: bytes, header: str, secret: str) -> bool:\n m = re.fullmatch(r\"t=(\\d+),v1=([0-9a-f]{64})\", header or \"\")\n if not m:\n return False\n expected = hmac.new(\n secret.encode(), m[1].encode() + b\".\" + raw, hashlib.sha256\n ).hexdigest()\n return (\n abs(time.time() - int(m[1])) < 300\n and hmac.compare_digest(expected, m[2])\n )" }, { "page": "webhooks", "section": "A receiver, end to end", "url": "https://railbed.com/docs/webhooks/#a-receiver-end-to-end", "language": "PHP", "label": "PHP", "kind": "code", "code": " toleranceSeconds) return false;\n const expected = crypto\n .createHmac('sha256', secret)\n .update(`${timestamp}.${rawBody}`)\n .digest('hex');\n return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(signature));\n}" }, { "page": "webhooks/signatures", "section": "Verify a delivery", "url": "https://railbed.com/docs/webhooks/signatures/#verify-a-delivery", "language": "TypeScript", "label": "Web Crypto · Cloudflare Workers, Deno, Bun, Next.js route handlers", "kind": "code", "code": "export async function verifyRailbedSignature(\n rawBody: string,\n header: string | null,\n secret: string,\n toleranceSeconds = 300,\n) {\n const match = /^t=(\\d+),v1=([0-9a-f]{64})$/.exec(header ?? '');\n if (!match) return false;\n const [, timestamp, signature] = match;\n const age = Math.abs(Date.now() / 1000 - Number(timestamp));\n if (age > toleranceSeconds) return false;\n const enc = new TextEncoder();\n const key = await crypto.subtle.importKey(\n 'raw',\n enc.encode(secret),\n { name: 'HMAC', hash: 'SHA-256' },\n false,\n ['verify'],\n );\n const bytes = new Uint8Array(\n signature.match(/../g)!.map((h) => parseInt(h, 16)),\n );\n const signedPayload = enc.encode(`${timestamp}.${rawBody}`);\n // subtle.verify compares in constant time\n return crypto.subtle.verify('HMAC', key, bytes, signedPayload);\n}" }, { "page": "webhooks/signatures", "section": "Verify a delivery", "url": "https://railbed.com/docs/webhooks/signatures/#verify-a-delivery", "language": "Python", "label": "Python", "kind": "code", "code": "import hashlib, hmac, re, time\n\ndef verify_railbed_signature(\n raw_body: bytes,\n header: str,\n secret: str,\n tolerance_seconds: int = 300,\n) -> bool:\n match = re.fullmatch(r\"t=(\\d+),v1=([0-9a-f]{64})\", header or \"\")\n if not match:\n return False\n timestamp, signature = match.groups()\n if abs(time.time() - int(timestamp)) > tolerance_seconds:\n return False\n expected = hmac.new(\n secret.encode(), timestamp.encode() + b\".\" + raw_body, hashlib.sha256\n ).hexdigest()\n return hmac.compare_digest(expected, signature)" }, { "page": "webhooks/signatures", "section": "Verify a delivery", "url": "https://railbed.com/docs/webhooks/signatures/#verify-a-delivery", "language": "PHP", "label": "PHP", "kind": "code", "code": " $toleranceSeconds) return false;\n $expected = hash_hmac('sha256', $timestamp . '.' . $rawBody, $secret);\n return hash_equals($expected, $signature);\n}" }, { "page": "webhooks/signatures", "section": "Verify a delivery", "url": "https://railbed.com/docs/webhooks/signatures/#verify-a-delivery", "language": "Ruby", "label": "Ruby", "kind": "code", "code": "require 'openssl'\nrequire 'rack/utils' # secure_compare; Rails and Sinatra already load it\n\ndef verify_railbed_signature(raw_body, header, secret, tolerance_seconds = 300)\n match = /\\At=(\\d+),v1=([0-9a-f]{64})\\z/.match(header.to_s)\n return false unless match\n timestamp, signature = match.captures\n return false if (Time.now.to_i - timestamp.to_i).abs > tolerance_seconds\n expected = OpenSSL::HMAC.hexdigest('SHA256', secret, \"#{timestamp}.#{raw_body}\")\n Rack::Utils.secure_compare(expected, signature)\nend" }, { "page": "webhooks/signatures", "section": "Verify a delivery", "url": "https://railbed.com/docs/webhooks/signatures/#verify-a-delivery", "language": "Go", "label": "Go", "kind": "code", "code": "package railbed\n\nimport (\n\t\"crypto/hmac\"\n\t\"crypto/sha256\"\n\t\"encoding/hex\"\n\t\"regexp\"\n\t\"strconv\"\n\t\"time\"\n)\n\nvar signatureHeader = regexp.MustCompile(`^t=(\\d+),v1=([0-9a-f]{64})$`)\n\nfunc VerifySignature(\n\trawBody []byte,\n\theader, secret string,\n\ttolerance time.Duration,\n) bool {\n\tm := signatureHeader.FindStringSubmatch(header)\n\tif m == nil {\n\t\treturn false\n\t}\n\tts, err := strconv.ParseInt(m[1], 10, 64)\n\tif err != nil {\n\t\treturn false\n\t}\n\tif age := time.Since(time.Unix(ts, 0)); age > tolerance || age < -tolerance {\n\t\treturn false\n\t}\n\tmac := hmac.New(sha256.New, []byte(secret))\n\tmac.Write([]byte(m[1] + \".\"))\n\tmac.Write(rawBody)\n\texpected := hex.EncodeToString(mac.Sum(nil))\n\treturn hmac.Equal([]byte(expected), []byte(m[2]))\n}" }, { "page": "webhooks/signatures", "section": "Use the raw body", "url": "https://railbed.com/docs/webhooks/signatures/#use-the-raw-body", "language": "TypeScript", "label": "A complete Cloudflare Worker or Next.js route handler", "kind": "code", "code": "export async function POST(request: Request) {\n const raw = await request.text();\n const header = request.headers.get('Railbed-Signature');\n const secret = process.env.RAILBED_WEBHOOK_SECRET!;\n if (!(await verifyRailbedSignature(raw, header, secret))) {\n return new Response('Invalid signature', { status: 400 });\n }\n const event = JSON.parse(raw);\n // Record event.id with a unique constraint, queue the work, then answer.\n return new Response(null, { status: 200 });\n}" }, { "page": "webhooks/signatures", "section": "Test vector", "url": "https://railbed.com/docs/webhooks/signatures/#test-vector", "language": "cURL", "label": "Reproduce it with OpenSSL", "kind": "code", "code": "printf '%s' '1790380800.' \\\n '{\"id\":\"evt_ExampleEventId0001\",\"type\":\"ping\",\"created\":1790380800,' \\\n '\"livemode\":false,\"data\":{\"payment\":null}}' \\\n | openssl dgst -sha256 -hmac 'whsec_4mJ9pQx2VtR7cY1nKs8LwZ3bHd6fGa0e'" } ] }