Define the wallet boundary
A watch-only wallet can detect payments without holding the private spending keys. An extended public key still reveals sensitive wallet activity and should be protected. Lightning integration can require an online wallet and introduces additional operational risk.
Size for the full stack
A Bitcoin backend, database, web service and optional Lightning node have different storage and memory needs. Review current supported deployment instructions and growth requirements before choosing a small machine.
Secure the merchant interface
Use a dedicated hostname, HTTPS, strong login protection and restricted administrative access. Keep the server updated and verify webhook signatures or supported verification mechanisms in the receiving application. Do not ship goods based only on a browser redirect.
Back up and reconcile
Protect store configuration, database, wallet recovery information and Lightning-specific material according to the relevant documentation. Test recovery and reconcile invoices against the payment system, especially around expiry, underpayment and refunds.
Check the deployment and chain strategy
Use the current supported deployment instructions, a dedicated hostname and a verified HTTPS route. A pruned chain can reduce ongoing storage requirements where supported, but rescan and recovery needs must be understood. Do not choose a disk from the current chain size alone; leave room for the full stack and growth.
- Verify the payment callback from an external test
- Use test payments before a live store
- Confirm the invoice settlement policy
Official documentation: BTCPay deployment options
Keep the spending key where you intend it
A watch-only setup can detect payments from an extended public key without giving the server the spending key. The xpub is sensitive because it can reveal wallet activity. A hot wallet changes this risk by placing spending capability online. Review wallet and Lightning custody separately and follow the supported backup process.
Official documentation: BTCPay wallet model
Build a deployment checklist around the chosen stack
Begin with a dedicated domain, supported deployment method, intended chain mode and enough disk headroom for synchronisation. Review the upstream Docker generator and its selected components before installation; preserve the non-secret deployment choices so another machine can be rebuilt consistently. Check domain resolution, certificate issuance and administrative account ownership before showing a checkout to customers. A generic Docker Compose example is not proof that every optional BTCPay component is configured.
- Decide which instance owner controls updates, monitoring, backups and incident response.
- Separate reverse-proxy exposure from private Bitcoin RPC, database and Lightning administration.
- Document a pruned backend’s recovery/rescan limits before connecting a wallet with historical payments.
- Keep a supported test environment or small controlled payment exercise for integrations before fulfilling valuable orders.
Official documentation: BTCPay Server: deployment choices · BTCPay Server: supported Docker deployment
Investigate missing wallet payments without importing a seed
A store can use a wallet’s xpub/derivation information while the spending key remains on another device. Test receiving and the recovery path with the chosen wallet. If BTCPay sees an invoice payment but an external wallet does not show it, inspect its derivation scheme and address gap-limit behaviour before assuming the funds vanished. Long runs of unpaid generated addresses can affect a wallet’s discovery. Use supported wallet diagnostics rather than copying recovery words into the server.
Official documentation: BTCPay Server: wallet and derivation troubleshooting
Reconcile invoices before fulfilment
Record invoice identifiers and make the fulfilment operation idempotent. A browser’s return to the shop is a navigation event, not proof of settlement. Verify the payment state through your authenticated server integration, handle expired, late or underpaid invoices explicitly, and keep a review path for unresolved outcomes. If a callback repeats, returning a successful acknowledgement must not ship or credit the order twice.
- Test a payment arriving near expiry and verify the order remains associated with the correct invoice.
- Keep database, store configuration and wallet recovery material in a tested independent backup.
- Lightning adds a separate liquidity and channel-backup responsibility; restoring yesterday’s entire VPS is not a safe universal recovery procedure.
- Hosting a BTCPay instance does not add Lightning or XMR to KoalaVPS customer checkout; payment methods on this hosting site remain its seven published routes.
Official documentation: Bitcoin developer guide: payment verification · LND: disaster recovery · Core Lightning: wallet and channel backups