BTCPay Server

BTCPay Server is a self‑hosted, non‑custodial payment processor that exposes a rich REST API and GraphQL endpoints for developers to integrate Bitcoin (and altcoin) payments into custom applications. From a technical standpoint, it functions as an intermediary between merchants and the underlying blockchain infrastructure, handling invoice creation, payment monitoring, and wallet management without ever touching private keys. The platform is built to be modular, allowing developers to plug in alternative Lightning nodes (LND, Core Lightning, Eclair) or full‑node backends while keeping the core service agnostic to the specific blockchain implementation.

Architecture

The core application is written in C# and runs on the .NET 8 runtime, leveraging ASP.NET Core for HTTP services and SignalR for real‑time invoice status updates. The data layer uses PostgreSQL (or SQLite in lightweight deployments) for transactional storage, while a Redis cache is optional for scaling read traffic and queuing background jobs. Wallet operations are delegated to external node binaries via RPC, which can be a local Bitcoin Core instance or a remote node exposed over HTTPS. BTCPay Server also supports Tor and I2P for privacy‑first deployments, with the ability to expose services over onion addresses. The application is container‑ready; official Docker images are provided, and the codebase includes Helm charts for Kubernetes deployments.

Core Capabilities

• Invoice API: Create, query, and cancel invoices; retrieve payment status via polling or WebSocket callbacks.
• Lightning Integration: Generate Lightning invoices, monitor settlement, and support multiple LN implementations through a pluggable interface.
• Webhooks: Emit events for payment received, confirmed, or failed to external services in real time.
• Multi‑Tenant: Separate stores and merchants can coexist on a single instance, each with isolated credentials and wallets.
• Hardware Wallet Support: Connect Ledger or Trezor devices for signing without exposing private keys to the server.
• Extensibility: A plugin architecture allows developers to add custom authentication backends, currency support, or UI extensions. The community maintains separate builds for Bitcoin‑only and altcoin variants.

Deployment & Infrastructure

BTCPay Server can run on any machine with .NET 8, PostgreSQL, and a Bitcoin node. For high‑availability, the recommended stack is Docker Compose or Kubernetes with persistent volumes for wallets and database data. The service can be scaled horizontally by running multiple instances behind a load balancer, as the state is stored in PostgreSQL and shared across replicas. In cloud environments, managed Postgres and container orchestration services simplify operations, while on‑premise deployments can leverage existing hardware wallets or full nodes.

Integration & Extensibility

Developers interact with BTCPay Server primarily through its REST API (Greenfield v1) and WebSocket streams. The API is versioned, well‑documented, and includes SDKs for several languages (C#, JavaScript, Python). Custom plugins can hook into the request pipeline to add authentication schemes or modify invoice data. The platform also exposes a GraphQL endpoint for fine‑grained queries, useful in single‑page applications. For UI integration, the JavaScript SDK allows embedding payment buttons or generating QR codes directly on a web page.

Developer Experience

The project follows an open‑source workflow with GitHub issues, pull requests, and a dedicated Mattermost channel for real‑time support. Documentation is comprehensive, covering setup guides, API references, and contribution guidelines. Continuous integration via CircleCI ensures that new releases are automatically tested against the full test suite, giving confidence in stability. The license is permissive (MIT), allowing commercial use without royalty obligations.

Use Cases

• E‑commerce Platforms: Embed BTCPay Server invoices into Shopify, WooCommerce, or custom backends to accept Bitcoin payments without third‑party fees.
• Point‑of‑Sale Systems: Deploy the built‑in POS app in retail environments, leveraging local Bitcoin nodes for instant settlements.
• Crowdfunding & Donations: Generate payment links or tipping buttons that route funds directly to a merchant’s wallet.
• Enterprise Payment Gateways: Host a multi‑tenant instance for multiple clients, each with isolated wallets and audit logs.

Advantages

BTCPay Server offers developers unparalleled control and privacy: all funds flow directly into the merchant’s wallet, with no intermediaries. Its modular architecture allows swapping out Lightning implementations or full nodes without code changes. The permissive license and active community reduce risk for commercial deployments, while the extensive API surface makes it easy to integrate into modern web stacks. Compared to hosted payment processors, BTCPay eliminates transaction fees (beyond network costs) and offers censorship resistance, making it a compelling choice for developers building resilient, privacy‑centric financial services.