Building your own cryptocurrency payment infrastructure gives you full control over transaction flow, data ownership, and fee structure. While hosted solutions like crypto payment gateway architecture build own offer quick setup for merchants who want zero maintenance, self-hosted BTCPay Server delivers complete independence for businesses willing to manage their own infrastructure. This guide walks through the entire architecture, deployment process, and operational considerations for running a production-ready Bitcoin payment gateway.
Why Self-Host Instead of Using a Third Party
Third-party payment processors take a cut of every transaction and hold your funds in escrow. They can freeze accounts, impose arbitrary limits, or change terms overnight. A self-hosted approach eliminates these risks entirely. You process payments directly from your wallet to your customer’s wallet with no intermediary holding capital.
The trade-off is technical responsibility. You manage node health, server security, software updates, and uptime monitoring. For teams with DevOps capability, this trade-off pays off through lower per-transaction costs, deeper branding customization, and access to features that hosted gateways charge premium prices for.
Core Architecture Components
A production BTCPay deployment consists of several interconnected services. Understanding how they communicate helps you design proper infrastructure and troubleshoot issues when they arise.
Bitcoin Full Node
Your Bitcoin node validates every transaction against consensus rules. BTCPay relies on it to detect incoming payments with confidence. You run either bitcoind in regtest mode for development or a mainnet node for production. Mainnet requires approximately 650 GB of storage for the blockchain data directory and sufficient RAM for the UTXO set — 4 GB minimum, 8 GB recommended.
┌─────────────┐ ┌──────────────┐ ┌────────────────┐
│ Customer │────▶│ BTCPay │────▶│ Bitcoin Node │
│ Checkout │ │ Server │ │ (bitcoind) │
└─────────────┘ └──────────────┘ └────────────────┘
│ │
▼ ▼
┌──────────────┐ ┌──────────────┐
│ Light Wallet│ │ Mempool/ │
│ (Electrum) │ │ Blockstream │
└──────────────┘ └──────────────┘
BTCPay Server Application
The application layer handles merchant dashboards, invoice creation, webhook delivery, and API management. It runs as a .NET Core application behind a reverse proxy. The server connects to your Bitcoin node via RPC and optionally uses an Electrum server for lightweight wallet queries that reduce bandwidth on your full node.
Lightning Network Support
For fast, low-fee microtransactions, integrate LND or Core Lightning alongside your on-chain node. BTCPay treats Lightning channels as a separate payment method within the same interface. You fund channels through the dashboard or CLI, and incoming payments settle instantly without blockchain confirmations.
| Component | Minimum Specs | Recommended Specs | Purpose |
|---|---|---|---|
| Bitcoin Node | 4 GB RAM, 650 GB SSD | 8 GB RAM, NVMe SSD | Transaction validation |
| BTCPay Server | 2 GB RAM, 2 vCPU | 4 GB RAM, 4 vCPU | Application layer |
| Postgres Database | 10 GB storage | 50 GB storage | Invoice and order data |
| Nginx Reverse Proxy | 512 MB RAM, 1 vCPU | 1 GB RAM, 2 vCPU | TLS termination, routing |
Deployment Options
Choose your deployment path based on team size, technical comfort, and scaling needs.
Docker Compose (Recommended Starting Point)
The official Docker Compose file provisions all services — BTCPay Server, Postgres, Nginx, and optional components — in a single orchestration file. This is the fastest path from zero to running instance.
version: '3'
services:
postgres:
image: postgres:15-alpine
volumes:
- pgdata:/var/lib/postgresql/data
environment:
POSTGRES_DB: btcpay
POSTGRES_USER: btcpay
POSTGRES_PASSWORD: <secure-password>
btcpayserver:
image: nbolr/btcpayserver:latest
depends_on:
- postgres
- bitcoind
environment:
BTCPAY_NETWORK: mainnet
BTCPAY_POSTGRES: Host=postgres;Database=btcpay;Username=btcpay;Password=<secure-password>
BTCPAY_EXPLORERPORT: 8332
BTCPAY_BIND: 0.0.0.0:443
ports:
- "8080:80"
bitcoind:
image: docker.io/library/bitcoin:latest
volumes:
- ./bitcoin-data:/data
command:
- daemon
- -regtest=0
- -server=1
- -rpcuser=btcpay
- -rpcpassword=<secure-password>
- -txindex=1
Replace placeholder values with strong passwords before deployment. Never commit credentials to version control.
Kubernetes Production Deployment
Organizations managing multiple instances or requiring horizontal scaling deploy BTCPay on Kubernetes. Each component becomes a managed deployment with persistent volume claims for Postgres data and Bitcoin chain data. Ingress controllers handle TLS termination and domain routing. This approach adds operational complexity but provides auto-scaling, rolling updates, and multi-region redundancy.
Managed Hosting Alternatives
If container management isn’t feasible, several providers run pre-configured BTCPay instances on dedicated hardware. You pay a monthly fee for server management while retaining full control over the application layer. This option suits merchants who want self-hosted benefits without maintaining infrastructure themselves.
Security Hardening Checklist
Payment infrastructure is a high-value target. Follow these security practices before going live.
Network isolation. Run your Bitcoin node and BTCPay Server on a private network segment. Only expose the reverse proxy to the public internet. Use firewall rules to restrict Postgres and Electrum connections to localhost or container network only.
TLS certificates. Always serve traffic over HTTPS with valid certificates from a trusted CA. Let’s Encrypt through Certbot automates renewal and removes certificate expiry as an operational surprise.
API key rotation. Generate API keys with minimal required permissions. Rotate them quarterly and revoke any keys associated with decommissioned integrations. Store keys in environment variables or a secrets manager, never in configuration files.
Regular updates. BTCPay releases security patches regularly. Subscribe to their release announcements and apply updates within a week of publication for critical fixes. Test upgrades on a staging instance before applying to production.
Backup strategy. Back up your Postgres database daily and your Bitcoin data directory weekly. Store backups encrypted and geographically separate from your primary server. Test restoration procedures monthly to verify backup integrity.
Integration Patterns
Connecting BTCPay to your existing systems follows standard API patterns. The platform exposes REST endpoints for creating invoices, querying payment status, and managing store settings. Webhooks push real-time notifications to your backend when payments arrive, confirm, or expire.
Most e-commerce platforms have community-built plugins that handle the integration automatically. For custom applications, implement webhook signature verification to authenticate incoming events and prevent spoofed payment confirmations. Process webhooks idempotently since network retries may duplicate delivery.
Operational Monitoring
Track these metrics to maintain healthy operations:
- Node sync status — Confirm your Bitcoin node stays within 10 blocks of chain tip. Desynced nodes cause missed payment detections.
- Invoice success rate — Monitor the ratio of created invoices to confirmed payments. Sudden drops indicate integration issues or pricing problems.
- Webhook delivery latency — Track time between payment confirmation and webhook processing. Delays beyond 30 seconds suggest background job queue congestion.
- Disk utilization — Alert when blockchain storage exceeds 80% capacity to prevent node crashes during peak sync periods.
When Self-Hosted Makes Sense
Self-hosting BTCPay Server is worth the investment when you process more than $5,000 monthly in crypto, require custom payment flows, need to retain full customer data, or operate in jurisdictions where third-party processors face restrictions. For smaller volumes or teams without DevOps capacity, hosted solutions provide faster time-to-market at the cost of higher fees and less control.
Many businesses start with a hosted gateway and migrate to self-hosted as volume grows and technical resources become available. The migration path is straightforward since BTCPay’s API mirrors common hosted gateway patterns. Replacing a hosted checkout with BTCPay typically requires updating endpoint URLs and configuring webhook handlers — usually a matter of days rather than weeks.