Alby Hub Setup

Connect your Lightning wallet to SatsRail in minutes.

Developer Docs

Why Alby Hub?

SatsRail is non-custodial — we never touch your money. But we need a way to generate Lightning invoices and detect when they get paid. That's where Alby Hub comes in.

Alby Hub does two critical things for your integration:

Generates Invoices

When a customer clicks "Pay," SatsRail asks your Alby Hub to create a Lightning invoice with the correct amount.

Confirms Payments

Alby Hub listens for incoming transactions and notifies SatsRail when an invoice has been paid.

Important: Alby Hub must be running for your SatsRail integration to work. No Alby Hub = no invoices = no payments.
1

Get Alby Hub

Recommended for merchants
Alby Hub Cloud

Never miss a sale. Alby Hub Cloud runs 24/7 on Alby's infrastructure so your checkout is always ready to accept payments — even when your computer is off.

  • Always online — no downtime during updates, restarts, or outages
  • No hardware to maintain
  • Professional-grade reliability for your business
Start with Alby Hub Cloud
Free
Self-Hosted Desktop

Run Alby Hub on your own machine at no cost. Great for testing or if you have a dedicated always-on computer.

Your computer must stay online 24/7. If it's off or asleep, customers cannot complete checkout.

macOS Windows Linux

Also available for Raspberry Pi, Umbrel, and Start9.

2

Connect to SatsRail

  1. Install and open Alby Hub
  2. Create a new wallet or connect an existing Lightning node (LND, Core Lightning, etc.)
  3. Fund your wallet — you'll need some inbound liquidity to receive payments
  4. Generate an NWC connection string — go to Settings → Connections → Create New Connection
  5. Copy the NWC URL — it looks like:
    nostr+walletconnect://...
  6. Paste it into SatsRail — in your merchant dashboard under Wallet Settings
That's it! SatsRail will use this connection to request invoices and listen for payments.
3

How Payments Flow

Here's what happens when a customer pays:

1 Customer clicks your SatsRail payment button
2 SatsRail connects to your Alby Hub via NWC
3 Alby Hub generates a Lightning invoice
4 Customer pays the invoice from their wallet
5 Alby Hub detects the payment and notifies SatsRail
6 SatsRail marks the order as paid ✓

Keep Alby Hub Running

If Alby Hub is offline, SatsRail cannot generate invoices and checkout will fail.

Best practices:

  • Run Alby Hub on a machine that stays on (desktop, server, Raspberry Pi, or cloud)
  • Enable "Start on boot" / auto-launch so it survives restarts
  • If using Alby Cloud, uptime is handled for you
  • Check periodically that channels are healthy and you have inbound liquidity

Troubleshooting

Alby Hub is likely offline or the NWC connection expired. Open Alby Hub, check it's running, and verify the connection in your SatsRail dashboard.

The invoice was generated but Alby Hub may have gone offline before confirming. Restart Alby Hub — it will sync and pick up the payment.

Your Lightning channels don't have enough capacity to receive. Open a new channel or use Alby Hub's built-in liquidity tools.

For a deeper dive, read the full article on our blog:

Read: Setting Up Alby Hub for SatsRail