The core idea behind accepting BTC with BTCPay Server is simple: you do not need to move your coins to any third-party account. The BTC your customer pays goes directly into a wallet you control. The whole process revolves around three steps: create a Store to lock in your payment settings, generate an Invoice so the customer can pay, and finally use the built-in reports and wallet records to reconcile everything.
A leading global cryptocurrency platform,suitable for both beginners and experienced traders.
New user benefit: 20% off trading fees upon registration!！
Creating a Store: A Store Is a Container for Payment Settings
A Store in BTCPay Server is not a "shop page." It is a management unit that bundles a group of payment settings together. One instance can create any number of Stores, and each Store has its own wallet, invoices, user permissions, and integration settings.
After you register an admin account, the system guides you to create your first Store. There are only two core fields you need to fill in: the Store name, which is for your own reference, and the default pricing currency, which determines what fiat currency invoices are quoted in. The BTC amount is then calculated by the system based on the exchange rate.
Once the Store is created, the key step is to configure a wallet. A Store without a wallet cannot receive on-chain payments. BTCPay Server accepts two options: import an existing extended public key, or xPub, or generate a new wallet using the built-in wallet. To import an xPub, go to Store Settings → Wallet → Setup → Connect an existing wallet → Enter extended public key. If you use an external wallet like Wasabi or Sparrow, simply paste the xPub generated by that wallet into the field. BTCPay will then derive a new receiving address for each invoice based on this public key. The private key always stays in your own wallet, and BTCPay never has access to it.
One practical tip: if you plan to use BTCPay as a long-term payment tool, the built-in wallet is usually more convenient than an external wallet. The built-in wallet communicates directly with your full node and avoids the "gap limit" problem. External lightweight wallets typically only track about 20 consecutive unused addresses, but BTCPay generates a new address for every invoice. After 20 consecutive unpaid invoices, an external wallet may no longer see later payments.
Invoices: What the Customer Pays, How Much, and Where
Under your Store, go to Payments → Invoices and click Create Invoice. The fields you need to fill in are: amount, currency, and optional order ID and item description. Keep at least one payment method enabled, either on-chain or Lightning, and then create the invoice.
After creation, the system generates a Checkout page where the customer sees the receiving address, a QR code, and a countdown timer. On-chain invoices expire after 15 minutes by default. This is to prevent BTC price swings from causing the fiat value you actually receive to drift too far from your quote.
Payment status has three stages. Do not mix them up:
- Processing: The transaction has appeared on the blockchain or in the mempool, and BTCPay has detected it, but it has not yet reached the number of confirmations you set. The default policy is usually 1 confirmation.
- Settled: The transaction has reached the number of confirmations you set. This is the status where it is safe to ship the order.
- Expired: The invoice was not fully paid within the 15-minute window. If a payment arrives later, the status will include a Paid Late marker, but the base status remains Expired. You need to decide manually whether to accept it.
Be careful with manual marking. You can mark an invoice as Settled, but this is not proof of blockchain confirmation. If you mistakenly mark an invoice as settled when the full amount has not actually arrived, the gap will show up later during reconciliation.
Reconciliation: Look at Two Data Sources Separately
BTCPay Server has two lines of reconciliation, each with a different purpose.
The invoice report, or Invoices Export, is for accounting and tax purposes. Go to the Invoices page and click Export → CSV. The downloaded file contains the payment date, BTC amount, and the fiat value converted at the time of payment for every invoice. This CSV includes fields such as order ID, item description, buyer information if you filled it in, and tax-related fields. Tax software like CoinTracking can import this format directly and automatically calculate income based on the market price at the time of receipt, as well as track capital gains when you later sell or spend the coins.
Wallet Transactions are for fund management. Go to the Wallets page. Here you see every actual on-chain incoming and outgoing transaction, sorted by date. Green means income, red means spending, and gray means unconfirmed. You can click into each transaction to view details on a block explorer, and you can also add labels and notes.
Common reasons why the two data sources do not match:
- Transfers not received through an invoice. If someone sends BTC directly to your Store wallet address without going through the Invoice process, the money will appear in Wallet transactions but not in the invoice report. BTCPay invoices only track payment requests generated by BTCPay itself.
- Partial Payment. If the customer pays less than the invoice requires, the invoice status will carry a Paid partial marker. The money is actually received in the Wallet, but at the invoice level it may not be counted as "settled."
- Network fee deduction. By default, BTCPay adds a "Network Fee" on top of the invoice amount. This is not a miner fee. It is meant to prevent customers from splitting one payment into many small outputs, which would increase your future spending costs. Customers can expand the details on the Checkout page to see this fee. If you think it will confuse customers, you can turn it off in Store Settings.
When Reconciliation Is Complete
The full chain for judging that an invoice has gone from "issued" to "can be ignored" is: Checkout page displayed → customer pays → invoice status changes from New to Processing → after reaching the required confirmations it changes to Settled → the invoice amount and order ID can be found in Wallet transactions or the CSV report. Once this chain is complete, the payment is closed. If an invoice stays in Expired or carries an unusual marker, go back to the invoice details page to confirm what actually happened with the underlying payment, and then decide whether to mark it, refund it, or abandon it.
A leading global cryptocurrency platform,suitable for both beginners and experienced traders.
New user benefit: 20% off trading fees upon registration!！
