
Signing up for a payment processor is supposedly "instant" — until it isn't. Between business verification, ID uploads, country eligibility checks, approval queues and the 2–3% cut taken from every sale, "getting paid online" quietly becomes one of the slowest parts of launching anything. There is a faster way, and this guide walks you through it step by step.
Using LibrePay Node — a free, open-source (AGPL-3.0), self-hosted Bitcoin payment gateway — you can go from zero to a working payment endpoint in about ten minutes. No accounts, no KYC, no fees, and no custody of your funds: the node holds only watch-only data, so it is architecturally incapable of touching your money. We covered the full platform in our LibrePay Node review; this tutorial is the hands-on, do-it-now version.
What You Need Before You Start
Nothing exotic. If you have these four things, you have everything:
- A Linux server. Any cheap VPS works (Debian/Ubuntu, Fedora/RHEL, Arch, openSUSE or Alpine) — a $3–6/month instance with 1–2 GB RAM is plenty. A Raspberry Pi on your home connection works too, as does Docker on any host.
- A Bitcoin wallet you control that can export a watch-only
zpubor a BIP47 payment code. Most modern wallets can export a zpub from their account/extended-key settings. This is public data — your private keys stay on your device and never touch the server. - (Optional) A domain for automatic HTTPS, e.g.
pay.yourstore.com. Skipping it is fine for testing; the node works over HTTP or an IP address on testnet. - Ten minutes. Genuinely. The table below shows where they go.
| Time | Step |
|---|---|
| 0:00 – 2:00 | Fork the repository on GitHub |
| 2:00 – 4:00 | Run the one-command installer on your server |
| 4:00 – 7:00 | Complete the five-question setup wizard |
| 7:00 – 9:00 | Create your first testnet4 invoice |
| 9:00 – 10:00 | Switch to your mainnet wallet and test a webhook |
Step 1: Fork the Repository (2 minutes)
Start by forking the librepay-node repository on GitHub. A fork copies the project into your own GitHub account — which is not just a formality. Because LibrePay Node is "software, not a service," your gateway is meant to live in your account, under your control, with zero runtime calls back to any platform. If the original project disappeared tomorrow, your payment gateway would not notice.
Click Fork on the repository page, accept the defaults, and you are done. There is nothing to configure here yet — the next step pulls the code directly onto your server.
Step 2: Run the One-Command Installer (2 minutes)
SSH into your server and run the installer. It detects your distribution (Debian/Ubuntu, Fedora/RHEL, Arch, openSUSE, Alpine — or Docker) and handles dependencies, systemd services and optional HTTPS automatically:
curl -fsSL https://raw.githubusercontent.com/radhwendalyhamdouni/librepay-node/main/install.sh | bash
Two useful variants:
# with automatic HTTPS for your domain:
bash install.sh --domain pay.example.com
# fully containerized:
bash install.sh --docker
When the installer finishes it prints two things: your node URL and a one-time setup code. Note both down — the setup code proves you have shell access to the server and is required exactly once, during the wizard. (If you lose it, you can read it again from the server with cat data/SETUP_TOKEN.)
That was the entire "infrastructure" phase: no blockchain to sync, no external database, no platform account. One process, one SQLite file.
Step 3: Complete the Five-Question Setup Wizard (3 minutes)
Open https://your-node/setup in a browser. The built-in wizard asks five questions — and each one maps to a real configuration file on your own server, not to a profile stored on someone else's cloud:
- Setup code — paste the one-time code from the installer.
- Store identity — your store or project name and a brand color; these style the buyer-facing checkout page.
- Receiving wallet — paste your watch-only
zpubor BIP47 payment code. Here is the clever part: the node immediately derives a real Bitcoin address from it and shows it to you as proof that it can see your wallet — before it will accept a single payment. - Payment policy — how many confirmations you require before an invoice settles, and how long unpaid invoices stay open.
- Backups — an automatic schedule (encrypted with AES-256-GCM), retention count, and an optional off-server copy over SSH.
Press LAUNCH NODE. Your API key is issued and shown exactly once — treat it like a password and store it in your password manager immediately — and the setup code self-destructs. The node is now live and receiving Bitcoin.

Step 4: Create Your First Testnet4 Invoice (2 minutes)
Resist the urge to paste your mainnet wallet first. Do a complete dress rehearsal on Bitcoin's testnet4, where coins are worthless and mistakes are free. The project's landing page even has a 90-second demo of this exact flow: one environment variable, one command, watch-only cold wallet, first invoice, paid, settled, webhook.
Create an invoice with a single API call:
curl -X POST https://your-node.example.com/api/v1/invoices \
-H "Authorization: Bearer lp_live_YOUR_KEY" \
-H "Content-Type: application/json" \
-d '{"amountFiat": 25.00, "currency": "USD", "orderId": "order-42"}'
# → 201 {"invoice": {"id": "…", "status": "waiting"}, "checkoutUrl": "https://…/pay/…"}
Open the returned checkoutUrl — the buyer-side checkout speaks six languages automatically (English, Arabic with full RTL, French, Spanish, Portuguese and Filipino), detects the buyer's browser language, and shows a QR code plus the exact amount. Pay it from any testnet wallet and watch the status lifecycle tick over: waiting → detected → confirmed → settled, with reorg-safe confirmations enforced before it settles and underpayments held (never silently accepted) beyond a 1% tolerance.
Seconds after settlement, your webhook receives a signed invoice.confirmed event — HMAC-SHA256 over the raw body, SSRF-guarded, retried up to 8 times over roughly 24 hours if your endpoint hiccups. That signature is what lets your shop trust the notification without exposing itself to forged callbacks.
Step 5: Go Live — Wallet, Store and Widget (1 minute)
Happy with the testnet run? Repeat step 3 with your mainnet zpub or payment code, and you are accepting real payments. From here you have three ways to plug the gateway into whatever you sell:
- WooCommerce or Shopify — official integrations are included; install the plugin, point it at your node URL and API key, done. 0% fees and final payments mean chargebacks simply stop existing.
- Your own code — two API endpoints, signed webhooks, and ready-made PHP, Node and Python snippets. Developers can ship a paid product in an afternoon.
- The embed widget — drop a payment button into any page, newsletter or link-in-bio, with no backend of your own required.
For Lightning, run the bundled phoenixd sidecar: it manages channels and liquidity automatically via the ACINQ LSP, so buyers can pay instant, low-fee bolt11 invoices while large orders ride the slower on-chain rail. You never touch channel management.
Why This Is Safe: Watch-Only by Architecture
If you followed the steps above, notice what never happened: you never gave the server a private key. The node holds a public descriptor (your zpub or payment code) and nothing else. It can derive addresses and detect payments — but it cannot sign, spend or freeze anything. If the VPS is compromised tomorrow, the attacker walks away with your invoice history, not your funds. There is no hot wallet to drain, no withdrawal path to forge, and no account to freeze because there is no account.
Every line of code that touches money is public and auditable in the repository — the project's philosophy is "verify it, don't believe it." Chain data comes from a configurable Esplora API (mempool.space by default) which you can point at your own instance for full independence; a fully offline node even keeps issuing invoices at the last-known rate.
Troubleshooting Common Issues
Most first runs go smoothly, but here are the four snags people hit and their one-line fixes:
- "Command not found" or a failed install — you are probably not root or lack
curl. Runsudo -ifirst, or use the Docker variant:bash install.sh --docker. - Setup page rejects your code — the one-time code changes per install; read the current one straight from the server with
cat data/SETUP_TOKEN. - HTTPS not working — re-run the installer with
--domain pay.example.comand make sure the domain's DNS A record points at the server before you do. - Invoices stuck in "waiting" — confirmations take time on-chain; lower the confirmation policy for testing, or verify chain data by opening your Esplora API URL in a browser. The node's self-monitoring alarms (
esplora_downwebhooks and Prometheus/metrics) exist precisely so a fallen chain provider can never fail silently.
If you get stuck deeper than that, the good news is that the project is a living open-source community: issues on GitHub get read by people who care, and the maintainer answers. Which brings us to the last point.
Like the Tool? Support the Project
You just installed professional payment infrastructure that cost you $0 in software fees. The cheapest way to say thanks takes five seconds: star the repository on GitHub — stars are how open-source projects become visible. Fork it, break it, report bugs; contribute a translation or a docs fix; or donate via the project's support page, which — fittingly — uses LibrePay's own BIP47 stealth-invoice engine and accepts Lightning zaps. Our full LibrePay Node review breaks down every support option in detail.
Frequently Asked Questions
Is ten minutes realistic, or marketing?
Realistic, with two caveats. The software steps genuinely take about ten minutes on a fresh VPS if you already have SSH access. Add five to ten minutes if you also want a custom domain with HTTPS (DNS propagation), and a few minutes to export your wallet's zpub if you have never done it before.
What does running it cost?
The software is free forever (AGPL-3.0, no fees, no tiers). Your only cost is the server: roughly $3–6 per month for a small VPS, or $0 if you repurpose a Raspberry Pi or an existing box with Docker.
Do I need to sync a full Bitcoin node?
No. The embedded chain watcher reads a configurable Esplora API (mempool.space by default), so there is no blockchain to download. Privacy purists can point the node at their own Esplora or Electrum-backed instance — the gateway then never touches a public service.
Can I test without real money?
Yes — that is the recommended path. Bitcoin's testnet4 is fully supported, the landing page has a 90-second walkthrough of the complete flow, and testnet coins are free. Switch to a mainnet wallet only after a successful testnet invoice.
What happens if my server is hacked?
The attacker gets your invoice data — not your money. The node holds watch-only public data and mathematically cannot sign or spend. Restore from an AES-256-GCM encrypted backup, rotate your API key, and you are back in business.
Does it work with WooCommerce and Shopify?
Yes, both integrations are included, alongside signed webhooks, a two-endpoint REST API with ready-made PHP/Node/Python snippets, and an embeddable widget for static pages.
Final Word
For twenty years, "accept payments online" has meant asking a company for permission and paying it a percentage forever. Self-hosting flips that: one fork, one command, five wizard questions — and a payment gateway that is yours the way your website is yours. Ten minutes from now, that can simply be done.