n8n

#What you get

The Railbed package for n8n adds two nodes and one credential:

• Railbed Trigger starts a workflow when a payment starts, is paid, needs your review or closes unpaid. It subscribes itself when you publish the workflow and checks every event's signature before anything runs.
• Railbed creates checkout sessions and reads or updates your records. n8n's AI Agent can also use it as a tool.
• Railbed API is the credential both nodes use: one secret key.

Build and test everything in Test mode first (turn it on in the business block at the top of the sidebar). Test payments move no money, and Test and Live each have their own keys, endpoints and records.

#Install the node

The package is @railbed/n8n-nodes-railbed.

Self-hosted n8n. An owner or admin of the n8n instance installs it once:

1. In n8n, open Settings → Community Nodes and choose Install.
2. Enter @railbed/n8n-nodes-railbed, confirm that you understand the risks of installing code from a public source, and choose Install.
3. Search the nodes panel for "Railbed". Everyone on the instance can now use it.

If your n8n is managed with configuration rather than the Settings page, follow n8n's guide to installing community nodes.

n8n Cloud. n8n Cloud only offers community nodes that n8n has reviewed and verified. Railbed's node has been submitted for that review and isn't verified yet, so for now it works on self-hosted n8n only. Once it's verified, an owner or admin will find it by searching the nodes panel for "Railbed" and choosing Install, with no settings to change.

#Connect your Railbed account

1. In Railbed, open Developers in the mode you're building in and choose Create key. Name it after the workflow or the n8n instance, such as "n8n: fulfilment". Keep Full access if the workflow uses the trigger, creates checkout sessions or updates orders; a Read only key is enough for workflows that only look things up. The key is shown once, so copy it now.
2. In n8n, add a Railbed or Railbed Trigger node and, under Credential to connect with, choose Create new credential.
3. Paste the key into Secret Key and leave Base URL as it is. Save: n8n checks the key by reading one payment.

A key starting rb_test_ works only with Test data and one starting rb_live_ only with Live data, so make one credential for each mode and name them so you can tell them apart, such as "Railbed (Test)". Your key is stored encrypted in n8n's credentials, not in the workflow, and anyone who can use the credential in your n8n can act with it.

#The Railbed Trigger

1. Add the Railbed Trigger node and choose its credential (a Full access key: subscribing adds a webhook endpoint).
2. Under Events, choose what starts the workflow. Payment Paid is the one to fulfil orders from.
3. Choose Listen for test event (n8n's Execute step). n8n adds a temporary endpoint for its test address. In Railbed, open Developers, find the endpoint whose description starts with "n8n:" and choose Send test event, or simulate a Test payment. The event appears in n8n.
4. Build the rest of the workflow, then publish it (in older versions of n8n, turn it on). n8n adds the workflow's own endpoint, described as "n8n:" and the workflow's name.

Unpublishing the workflow (or turning it off) removes its endpoint. If you change the events, or n8n's address changes, the trigger replaces its endpoint the next time the workflow is published.

Each event comes out of the trigger as Railbed sent it: type, id (evt_…), livemode, and data with the payment, its order and the customer (every field). In expressions that looks like {{ $json.data.payment.amount }} or {{ $json.data.order.displayNumber }}. The trigger adds sample, which is true for the made-up payment that Send test event sends; it isn't in your account, so skip any step that looks it up.

Railbed may deliver an event more than once, and Resend in the delivery log sends the same event again. To act on each event only once, add n8n's Remove Duplicates node right after the trigger, choose Remove Items Processed in Previous Executions, and set Value to Dedupe On to {{ $json.id }}.

Under Options, Include Current Payment reads the payment from the API as well and adds it as currentPayment. Events can arrive out of order; the API's answer is always the payment as it is now.

#n8n's address

Railbed sends Live events only to a public https:// address, and its servers can't reach localhost on your computer. If n8n runs on your own machine, give it a public address, for example through a tunnel, and set n8n's N8N_WEBHOOK_URL setting to it (WEBHOOK_URL in versions before 2.35). n8n Cloud and most hosted n8n already have one.

Each mode allows 10 webhook endpoints. Every published workflow with a Railbed Trigger holds one, and so does a trigger while it listens for a test event.

#Example workflows

#Add each paid payment to a sheet and tell the team

1. Railbed Trigger with Payment Paid.
2. Google Sheets → Append Row, with columns mapped like these:

1. Slack → Send Message, such as Paid: {{ $json.data.order.summary }}, {{ $json.data.payment.amount }} {{ $json.data.payment.currency }}.

amount is the price you set, and merchantReceived is what reached your payout wallet after fees, in dollars, once it's reported (it can be empty at first and arrive with Payment Updated). Keep amounts in their own currency; don't add USD and EUR together.

#Fulfil the order, then mark it fulfilled

1. Railbed Trigger with Payment Paid.
2. Your shipping, licence or delivery step. When it must happen only once, put Remove Duplicates on the event's id before it (see the trigger), and check in your own system for the payment's id, which also covers a workflow you rebuilt.
3. Railbed → Order → Update Fulfillment, with Order ID {{ $('Railbed Trigger').item.json.data.order.id }} and Fulfillment set to Fulfilled. The order's timeline in Railbed records it.

If your store refunds or cancels the order itself, Order → Record Cancellation or Refund notes it on the order's timeline. It moves no money: Railbed can't send money back to a buyer.

#Create a checkout session and email the link

1. Your trigger, such as a form submission or a new deal in your CRM.
2. Railbed → Checkout Session → Create, with Amount (decimal text, such as 49.00), Currency and Description. Under Additional Fields, add Customer Email, a Reference (your own order id) and an Idempotency Key that is unique to this order, such as the form entry's id: if n8n runs the step again, you get the same session back instead of a second one.
3. Gmail → Send (or any email node) to the buyer with the session's url.

When the buyer pays, a workflow with the Railbed Trigger receives Payment Paid with your reference in data.payment.reference. Sessions stay open for 24 hours; every field is in Create a checkout session.

#Let an AI agent look things up

Connect the Railbed node to an AI Agent node's Tool input, choose the resource and operation, and let the model fill in fields with Let the model define this parameter. Good fits are questions like "has my store's order 1042 been paid?" (Order → Get Many filtered by Store Order ID) or "what did nathan@example.com buy?" (Customer → Get Many filtered by email).

Give agent tools a Read only key unless the agent needs to create sessions or update orders, and give each tool node one operation, so the agent can do only what you chose. Fulfil orders from the Railbed Trigger and a paid payment, not from what an agent says happened.

#Test mode first

With a Test credential you can run a whole payment without a card:

1. Checkout Session → Create with a Test amount.
2. Checkout Session → Start with the session's id and a Customer Email under Additional Fields.
3. Payment → Simulate with the same id and an Outcome: Paid, Underpaid (the payment is held for your decision), Declined (it stays open for another try) or Failed.

Your Test trigger receives the same events a real payment would send. Use a new session for each scenario; a finished payment keeps its outcome. When it all works, make a Live key, a second credential, and switch the workflow's nodes to it.

#Without the node

If you can't install community nodes, n8n's built-in nodes still work with Railbed:

• Call the API with the HTTP Request node. Use a Header Auth credential with the name Authorization and the value Bearer followed by a space and your secret key. Requests and responses are in the API reference, such as POST https://pay.railbed.io/v1/checkout_sessions.
• Receive events with the Webhook node: add its production address as an endpoint in Developers, turn on the node's Raw Body option, and check the Railbed-Signature header in a Code node exactly as Verify signatures describes before any other step. The signature covers the exact bytes Railbed sent, so check the raw body, never JSON that n8n parsed and wrote out again.

The node does both for you, so prefer it when you can.

#Troubleshooting

• Event typesEvery event, what it means and the full payload→
• Fulfil orders safelyDeliver each order once, only for money that arrived→
• Webhook endpointsHow the trigger subscribes, and how to do the same from code→