WooCommerce

#What the plugin does

Railbed for WooCommerce adds Railbed as a payment method at your store's checkout. When a buyer places an order, the plugin creates a checkout session and sends the buyer to Railbed's hosted page. The order completes only after the plugin has verified the payment with Railbed: a signed webhook starts the check, and the plugin confirms it with an authenticated status request before marking the order paid. Card details never touch WordPress.

From version 1.1, each checkout also sends the order's items, totals and addresses and the buyer's contact details, so the order and its customer appear in Railbed's Orders and Customers, and the plugin keeps the order's fulfilment in step with WooCommerce. See Orders, customers and fulfilment.

Requirements: WordPress 6.9 or later, WooCommerce 10.9 or later, PHP 8.3 or later. Works with classic checkout and Checkout Blocks, and with both order storage modes. Order currencies USD, EUR, GBP, CAD and AUD; amounts from 1.00 to 100,000.00.

#Install and connect

The dashboard walks you through it: open Integrations → WooCommerce in the dashboard. It has four steps, one open at a time, and Railbed checks each one as you go (the plugin using your key, the test webhook answered, the first order in).

1. Install the plugin. Download the ZIP from that page. In WordPress, open Plugins → Add new → Upload plugin, upload it and activate it alongside WooCommerce.
2. Connect Railbed. Create an API key on the setup page (it's shown once: copy it) and add your store's webhook by typing your store's address (or pasting the webhook URL the plugin's settings show; it ends in ?wc-api=railbed_webhook). Then open WooCommerce → Settings → Payments → Railbed, choose Test mode, paste the key into Test API key and the webhook's secret into Test webhook secret, and save. Saving checks the key.
3. Send a test webhook from the setup page, then reload the plugin settings: they say Connection verified. If something is missing, the plugin's settings list it, including why the last webhook was refused.
4. Try a test order. Tick Enable (Offer Railbed at checkout) and save. In Test mode, shoppers don't see Railbed: only store managers who are signed in, and browsers that open the preview link shown in the plugin's settings (for seven days). Open it in the browser you test with, place an order and pay it with Simulate successful payment. The order waits as Pending payment, then becomes Processing (or Completed when every item is virtual and downloadable), as with any paid order. Make a new link retires the old one.

#Provider choice

Checkout settings on the setup page decides how your WooCommerce buyers reach a card provider, as on checkout pages: Smart Routing (the best provider for each buyer, opened straight from Continue to pay), Buyers choose (the ranked list) or One provider. It covers Test and Live orders, and the plugin needs no change. Your first WooCommerce key starts it on Smart Routing.

#Going live

Add your payout wallet in Railbed. Switch the dashboard to Live: the setup page follows, and you repeat steps 2 and 3 with a live key and a live webhook (a live webhook takes a ping as its test). Then set the plugin's Payment mode to Live and save; saving checks the payout wallet, and without one the plugin says so and keeps Railbed off your checkout. The payment method is offered only on an HTTPS store, in Test mode too (unless WordPress's environment type is local). Orders keep the mode they were placed in, so switching the plugin to Live doesn't affect test orders in progress.

#Order status while the buyer pays

• Pending payment while the buyer is on Railbed's page, like any payment method that sends the buyer away to pay. WooCommerce holds the stock for its usual hold time and sends no email yet.
• Processing (or Completed for downloads) when Railbed confirms the payment: WooCommerce reduces stock and sends its New order email to you and Processing order email to the buyer.
• On hold when money arrived but Railbed is reviewing it. Don't ship until it's confirmed.
• Failed when the checkout closed unpaid (after 24 hours). If a slow provider's payment still arrives and nobody changed the order, it completes as usual. A changed or cancelled order gets a private note to review instead.

From version 1.1.2, a buyer returning from a closed checkout can place a fresh order with the cart still in their browser. Both classic checkout and Checkout Blocks create a new order for that retry. If the cart is empty, the buyer returns to the shop to choose the items again. The old order keeps its original payment record.

#Orders, customers and fulfilment

Each checkout sends Railbed the WooCommerce order along with the payment. Nothing needs setting up.

• What's sent. The items (with SKU, quantity and the variation's attributes), fees, the discount and coupon codes, shipping and its method, tax, the billing and shipping addresses, the order number and a link back to the order, and the buyer's name, email, phone and WooCommerce customer ID. In the dashboard the order carries WooCommerce's number and an Open in WooCommerce button.
• When the totals don't add up. If the lines, discount, shipping and tax don't come to the order total to the cent (tax rounding, or an extension that changes totals), the order is sent without its items and totals and shows as one line for the total. The WooCommerce order gets a private note. Payment works the same either way.
• Existing payment attempts. A buyer's second try at the same WooCommerce order joins its order in Railbed. If Railbed already has a paid payment for that order, or one held for review, no new checkout is created: the buyer is asked to contact you, and the order gets a private note to review.
• Fulfilment. Orders that ship start as Not fulfilled; orders with only virtual products have nothing to ship. Marking an order Completed marks it fulfilled in Railbed, and moving it from Completed back to Processing or On hold marks it not fulfilled. Orders WooCommerce completes on payment (downloads) are marked fulfilled the same way.
• Fulfilment updates run in the background and are retried four times over about two and a half hours if Railbed can't be reached. If one still fails, the order gets a private note, and Order actions → Send fulfilment status to Railbed sends it again. The dashboard shows these orders' fulfilment but doesn't change it: change it in WooCommerce.
• Cancellations and refunds. Cancelling an order in WooCommerce, or recording a refund, shows on the Railbed order as Canceled or Refund recorded with the amount. It doesn't change the payment: Railbed can't send money back, so arrange any refund with the buyer yourself. These are sent in the background and retried like fulfilment; Order actions → Send cancellations and refunds to Railbed sends one again. See Report a cancellation or refund.
• Orders placed before 1.1 aren't linked to a Railbed order, so their fulfilment, cancellations and refunds aren't sent.

For day-to-day tasks, see Orders and fulfilment and Customers. The plugin uses the API's order fields and Update an order, so a store you build yourself can do the same.

#Updates

From version 1.1.1, WordPress shows new Railbed versions on its Plugins and Updates screens like any other plugin: choose Update now, or turn on automatic updates for it. The plugin installs a download only if its checksum matches the one Railbed publishes. To check for new versions it contacts Railbed about twice a day and sends nothing about your store.

To get to 1.1.1 from an earlier version, download the plugin from Integrations in the dashboard, upload it in Plugins → Add new → Upload plugin, and choose Replace current with uploaded. Settings, keys and orders carry over, and nothing needs reconnecting. Orders placed before the upgrade finish as they would have.

#Staging copies

If you copy your site (to staging, or by restoring a backup somewhere else), the copy notices its new address and pauses Railbed: no checkout, webhooks or background updates there until an administrator answers the notice at the top of the WordPress admin. Choose Same store, new address after moving your store, then send another test event. Choose A copy (staging): disconnect it on a copy: it removes the copy's keys so it can't change your real store's Railbed orders. Connect a staging copy with Test keys if you want to test there.

#Store settings that matter

• Deleting the plugin in WordPress removes its keys and secrets and keeps your orders' payment records. WooCommerce's REST API never returns the saved keys.
• Your store must accept a public POST to its webhook address without a login, cache or bot challenge, and keep the Railbed-Signature header and the request body unchanged. Security plugins and CDN rules sometimes block it; allow the address.
• Run WordPress cron regularly (a real cron job is best). The plugin uses it to re-check orders whose webhook was missed.
• If you change the webhook address, send another test event before new checkouts are offered.
• When you roll the signing secret in Railbed, paste the new one into the plugin straight away. From the roll on, deliveries are signed with the new secret and the plugin rejects them until it has it; they're retried for about a day, and the plugin's status checks keep orders moving meanwhile. After saving the new secret, send another test event: until a delivery signed with it arrives, the payment method isn't offered at checkout.

#Moving from another gateway

Install Railbed as a separate payment method. Keep your old gateway active until its outstanding orders finish, then disable it for new purchases. Orders aren't moved between gateways.