How to Set a Timeout for an Invoice When Using a Self-Hosted Node

11 November 2026

You set a timeout for an invoice on a self-hosted node by configuring the invoice expiration period in your payment processing software, such as BTCPay Server, before generating the invoice link or QR code. This timeout determines how long the invoice remains valid for payment, after which it automatically expires and cannot be paid.

Why set an invoice timeout

Timeouts prevent indefinite open invoices that could cause accounting confusion, reduce the risk of stale or mismatched payments, and align with your business's payment terms. Without a timeout, a customer might pay an invoice weeks after it was issued, when the exchange rate or your inventory has changed. A timeout also helps your system clean up unpaid invoices automatically, avoiding manual tracking of abandoned requests.

Where to Configure the Timeout

In a typical self-hosted setup like BTCPay Server, the timeout setting is part of the invoice creation interface, not a global node configuration. You set it per invoice or as a default for your store. The timeout is defined in minutes, hours, or days, depending on the software options.

Step-by-Step: Setting a Timeout in BTCPay Server

1. Log into your BTCPay Server dashboard as a store owner or administrator.
2. Navigate to your store's settings. Look for a section labeled "Payment" or "Invoice" settings.
3. Find the "Invoice expiration" field. This may be called "Invoice expires after" or "Payment window duration". The default is often 15 minutes for Lightning invoices and 1 hour for on-chain invoices, but you can change it.
4. Enter your desired timeout value. For example, set 60 minutes for on-chain payments to account for confirmation time, or 30 minutes for Lightning payments since they confirm almost instantly. Consider your typical transaction speed and block confirmation requirements.
5. Save the setting. This will apply to all new invoices generated from that point forward, unless you override it per invoice.

If you need a different timeout for a specific invoice, most self-hosted systems allow you to override the default when creating the invoice manually through the "Create invoice" form. Look for an "Expiration" or "Timeout" field in that form.

Choosing the right timeout duration

The ideal timeout depends on the payment method and your business needs:

• On-chain Bitcoin invoices: Allow 30 minutes to several hours. A 1-hour timeout is common, but if you require multiple confirmations (e.g., 2 or 3), you may need a longer window. Factor in potential network congestion; during busy periods, a 2-hour timeout reduces the chance of the invoice expiring before the transaction is mined.
• Lightning Network invoices: 5 to 30 minutes is typical. Lightning payments settle in seconds, so a short timeout is fine. A longer timeout increases the risk of a routed payment failing due to stale invoices in routing nodes.
• Altcoin invoices: Use the same logic as on-chain Bitcoin, adjusted for each coin's average block time. For example, a coin with 2-minute block times can use a shorter timeout than Bitcoin.
• Manual override for large payments: For high-value invoices, you might extend the timeout to accommodate slower payment methods or customer delays. Document this override in your payment policy.

What happens when an invoice expires

Once the timeout is reached, the invoice status changes to "Expired" or "Invalid". The customer cannot pay it anymore, even if they send funds to the associated address. If funds arrive after expiration, the transaction may be visible on the blockchain but will not be credited to the invoice. Your system might treat it as an "unaccounted" payment that requires manual reconciliation.

Handling Late Payments

Set up a process for expired invoices that receive payment after expiration. Options include: - Manually creating a new invoice for the same amount and linking the late transaction to it. - Refunding the customer if you cannot accept the late payment. - Adjusting your accounting ledger to record the payment as a separate entry, if you decide to honor it.

BTCPay Server and similar tools typically do not auto-accept late payments; you must manually intervene.

Testing your timeout configuration

After setting a timeout, test it by creating a test invoice and waiting for it to expire. Verify that the invoice becomes unpayable and that your system handles the expiration cleanly. Check that the QR code and payment link no longer work. If you use a payment gateway integration, confirm that expired invoices trigger the correct status in your checkout flow.

Common Pitfalls

• Setting too short a timeout for on-chain payments: A 15-minute timeout for Bitcoin on-chain invoices is risky during network congestion. The transaction might not confirm before the invoice expires.
• Not updating the timeout when changing coin types: If you accept multiple cryptocurrencies, each may need a different default timeout. BTCPay Server allows per-payment-method settings; use them.
• Forgetting to override for manual invoices: If you generate invoices outside the standard flow (e.g., via API or manual creation), check that the timeout is set explicitly, not left at a default that may be too short or too long.

Summary

Setting an invoice timeout on a self-hosted node is a straightforward configuration step in your payment processing software. The timeout should be long enough to accommodate the chosen payment method and network conditions but short enough to avoid stale invoices. Test your settings and document your timeout policy for consistency across your business.

Back to crypto payments