explaingit

earonesty/qpayd

2RustAudience · developerComplexity · 4/5ActiveLicenseSetup · hard

TLDR

Self-hosted Rust daemon that lets a merchant accept on-chain Bitcoin and Lightning payments, create invoices, and fire signed webhooks to their store.

Mindmap

mindmap
  root((qpayd))
    Inputs
      Invoice request
      Wallet descriptor
      Price feed
    Outputs
      Bitcoin invoice
      Webhook callback
      Admin portal
    Use Cases
      Accept BTC on a shop
      Self-host payments
      Track refunds
    Tech Stack
      Rust
      SQLite
      Postgres
      Electrum
      Lightning

Things people build with this

USE CASE 1

Run a self-hosted Bitcoin checkout for a small shop without a payment processor

USE CASE 2

Add Lightning payments to a Node.js storefront using the @qpayd/checkout popup

USE CASE 3

Receive signed webhooks on order paid, expired, or refunded events with retry and replay protection

USE CASE 4

Operate multiple stores with separate API tokens from one qpayd instance

Tech stack

RustSQLitePostgresElectrumLightningDocker

Getting it running

Difficulty · hard Time to first run · 1day+

Needs a watch-only wallet descriptor and either an Electrum source or a Lightning backend like Phoenixd before any invoice can be paid.

MIT license, free to use and modify with attribution and no warranty.

In plain English

qpayd is a small server program, written in Rust, that lets a merchant accept Bitcoin payments on their own infrastructure. Instead of paying a payment processor, you run qpayd on your own machine; it creates invoices, locks the fiat price (for example 10 US dollars) to the equivalent Bitcoin amount using a configured price feed, watches the blockchain for the payment, and tracks whether the invoice was paid, expired, or refunded. When something happens, it can call a URL on your website (a webhook) so your shopping cart can mark the order as paid. The daemon supports both regular on-chain Bitcoin payments and Lightning Network payments. For on-chain it uses watch-only wallet descriptors, with Electrum as a fallback or rotation source so it does not need its own full node. For Lightning it can talk to Phoenixd or barkd as the backend. Invoices and state can be stored in SQLite for small setups or Postgres for bigger ones. The README also lists features like multiple stores, public payment links, signed webhooks with retry and replay protection, refund tracking, and an optional browser admin portal. Installation is either through Cargo (cargo install --path .) or by building a Docker image with the provided Dockerfile and running the container on port 8080 with a mounted config file and a data volume. Configuration is done in a TOML file based on qpayd.example.toml, and there are subcommands for one-time checks, database migrations, syncing, and sweeping. The README shows a minimal HTTP API: a POST to /v1/stores/main/invoices with a Bearer token creates an invoice, and a GET on the same path reads its current state. There are also two JavaScript packages, @qpayd/checkout for the customer-facing payment popup and @qpayd/admin for a merchant admin panel. The project is MIT licensed and has 1 star.

Copy-paste prompts

Prompt 1
Walk me through cargo install qpayd, writing a qpayd.toml from the example, and creating my first store invoice
Prompt 2
Build the Dockerfile for qpayd, mount a config and data volume, and start the container on port 8080
Prompt 3
Add the @qpayd/checkout JavaScript package to a Next.js page and trigger an invoice on the buy button
Prompt 4
Configure qpayd to use Phoenixd as the Lightning backend and Electrum as the on-chain watch source
Prompt 5
Verify a qpayd signed webhook in a Node Express handler and reject replays older than five minutes
Open on GitHub → Explain another repo

Generated 2026-05-22 · Model: sonnet-4-6 · Verify against the repo before relying on details.