How to Generate a New Address for Every Invoice in BTCPay Server
When a customer is ready to pay, you need a unique receiving address for that specific invoice. BTCPay Server can generate a new address automatically for every invoice, so you never reuse an address. This is done by configuring your store to use a derivation scheme that supports address generation, and then ensuring your checkout settings request a new address per invoice. Here is how to set that up.
Prerequisites
Before you can generate per-invoice addresses, you need:
- A running BTCPay Server instance (self-hosted or via a hosting service).
- A wallet connected to your store. This is usually done by importing an xpub (extended public key) from a hardware wallet or software wallet that supports BIP32 derivation.
- The store must be configured to use a payment method that supports address generation - typically Bitcoin on-chain or Lightning Network (which uses invoices, not addresses, but the principle is similar).
If you have not yet connected a wallet, follow the BTCPay Server setup guide on this site. The key requirement is that your wallet's xpub allows BTCPay to derive new addresses without needing your private keys.
Step-by-Step: enabling per-invoice addresses
1. open your store settings
Log into your BTCPay Server dashboard. From the main menu, select Stores and click the name of the store you want to configure.
2. Navigate to Payment Methods
In the store settings, go to Payment Methods. You will see a list of enabled payment methods (e.g., BTC On-Chain, Lightning, etc.). Click Modify next to the payment method you plan to use.
3. Check the Derivation Scheme
On the payment method configuration page, look for the Derivation Scheme field. This is the xpub or wallet fingerprint you imported. BTCPay uses this to generate addresses. For per-invoice addresses to work, the derivation scheme must support address re-use prevention. Most modern wallets (including BTCPay's internal wallet) do this by default.
If you see a warning that the derivation scheme does not support address generation (rare with proper xpubs), you may need to re-import the wallet using a compatible format. Consult your wallet's documentation.
4. configure invoice settings
Scroll down to the Invoice Settings section. You will see an option labeled Generate a new address for each invoice. Ensure this is enabled (checked). This is the core setting. When enabled, BTCPay will derive a fresh address from your xpub every time a new invoice is created.
Some versions of BTCPay also have a setting called Show recommended fee or Payment tolerance. These do not affect address generation but are worth reviewing for your business needs.
5. Save and Test
Click Save at the bottom of the page. To confirm it works, create a test invoice:
- Go to your store's Invoices page.
- Click Create Invoice.
- Enter an amount (e.g., 0.001 BTC) and a description.
- Click Create Invoice.
The invoice page will display a unique Bitcoin address. Create another invoice with the same amount. The second invoice will show a different address. If both invoices show the same address, check that the "Generate a new address for each invoice" setting is enabled and that your derivation scheme is correct.
How address derivation works (briefly)
BTCPay uses a hierarchical deterministic (HD) wallet structure. Your xpub defines a tree of addresses. For each invoice, BTCPay increments an internal counter and derives the next unused address. This ensures:
- No two invoices share the same address.
- You can always identify which invoice a payment belongs to by matching the address to the invoice record.
- Your private keys remain offline, so the server cannot spend funds.
This is the same mechanism used by most modern crypto payment processors. It does not require any interaction with your hardware wallet or seed phrase.
Common issues and checks
- Addresses stop generating after a large number of invoices. HD wallets have a practical limit (typically 2^31 addresses). In practice, you will not reach this with normal business use. If you do, you can rotate your xpub by creating a new wallet and reconnecting it to your store.
- Customers report the address does not match what they expected. This usually means the customer's wallet software is checking an old or incorrect derivation path. Ensure your BTCPay store is using the same derivation path as your wallet (commonly
m/84'/0'/0'for native segwit). - The same address appears for two invoices. This can happen if the "Generate a new address" setting is off, or if your xpub is not configured for address generation. Double-check the setting and re-import your wallet if needed.
After you enable per-invoice addresses
Once this is working, your checkout flow becomes straightforward: each invoice gets its own address, and you can track payments by address. For settlement and accounting, you will still need to match transactions to invoices and convert crypto to fiat. See the guides on crypto payment reconciliation and exchange settlement rails on this site for those steps.
Not financial advice. unidexai.xyz publishes market data and general information about digital assets. Crypto assets are volatile and you can lose everything you put in. Nothing here is a recommendation to buy, sell or hold, and we make no price predictions.
Prices are sourced from third parties and may be delayed or wrong. Verify anything you intend to act on against a primary source.