Administer BTCPay Shop

This post is also available in: German

BTCPay Shop administrieren


Administer BTCPay Shop

In a step-by-step guide, we explain how to create and administer a BTCPay shop. As an example we use the setup of a BTCPay store, which you can create at

You can also use this manual if you have set up your own payment server and want to create a shop on it or if you have your shop with another third-party provider.

This guide is divided into the following sub-items:

Set up and administer BTCPay Shop

The first chapter can be found under SET up BTCPay Shop. Once you have set up or created the BTCPay Shop, you will learn how to administer the BTCPay Shop in this chapter.

Administer BTCPay Shop

In the area of the shop or store configuration, the basic settings and functions for the shop are defined. These settings also apply to the apps that are created below the shop.

There is another subdivision called Apps. Apps can be called applications.

Any user can create any number of stores. There are no restrictions on this.

General Settings

BTCPay Store General Settings


The “Add additional fee (network fee) to invoice” field is about an additional fee that can be charged when an end customer sends the invoice amount into numerous instalments. The network fees for a payment are always borne by the payer. If a trader wants to forward the payment receipt later to another Bitcoin address, he must pay the network fee himself. The amount of this fee depends, among other things, on how many previous inbound transactions the new forwarding transaction is made up of. You can protect yourself from these more fees if you leave the default setting this way and only charge an additional fee if a payment is made in several instalments.

External access

The “Allow anyone to create invoice” function is disabled. Must be enabled if external applications are to communicate with the BTCPay Store via API or HTML pages or create invoices. If the apps provided via the BTCPay server (POS and Button) are used, this function does not have to be activated, otherwise it must be activated.

Validity period

The payer will see a QR code on the payment page/checkout page for a certain period of time, through which the Bitcoin will be sent. The requested Bitcoin amount has been calculated based on the exchange rate. Since the exchange rate is very volatile and can change permanently, the exchange rate should remain valid only for a limited period of time.

It is recommended that the exchange rate is guaranteed to the customer for 15 minutes. This is a period of time that is granted by almost all traders. Accordingly, it is recommended to use the value in the field “Invoice expires if the full amount has not been paid after … minutes” to 15 minutes.

After the payment has been made, it will take a while for the receipt to be credited to the merchant’s wallet. This may depend on how much the network fee was, which the payer was willing to pay. If the payer has paid no or only a very small network fee, a transaction may take a little longer. To protect yourself as a trader from the fact that in the meantime the Bitcoin price can fluctuate too much with “Payment invalid if transactions fails to confirm … minutes after invoice expiration” will determine how long it may take for the payment to be confirmed by the network. The default is one day (=1440 minutes).


When asked “Consider the invoice paid even if the paid amount is … less than expected” is about underpayments of the invoice amount. The system expects a certain Bitcoin amount. If less Satoshi actually arrives, there is an underpayment.

This can happen if the payment is not made directly from the payer’s wallet, but from an exchange or exchange office. Here, the network fee is deducted from the balance when a withdrawal is made and correspondingly less arrives.

What is to be done about this? Should the payment be rejected or is there a tolerance where you are still willing to accept the payment anyway? The default is 0 tolerance.

Number of Confirmations

When setting “Consider the invoice confirmed when the payment transaction…” it is a question of how much confirmation a payment was successful. There are different views of payers and merchants. For a customer, the payment is made after the wallet is clicked Send. For the merchant, the payment is not completed until it has entered Final on his wallet.

Once the customer has made the payment, this payment is immediately visible in the mempool or blockchain.

However, this transaction has not yet been confirmed by the network. Depending on the amount of network fee paid, this can be the next block after 10 minutes or may take an hour or more. There is also a theoretical risk that a sent transaction will not be confirmed at all. This would be the case if the end customer did not pay a network fee at all.

According to how many confirmations a merchant wants to make the service available to his customer depends on the product and the potential risk of fraud.

A low value product can already be provided with the status “unconfirmed”. Especially with digital accesses or downloads, the failure is more likely to be tolerated. The damage is less than dissatisfied customers who have to wait a long time for service after payment.

For products that are shipped by mail order, 1 or 2 Confirmation are responsible.

A guaranteed payment receipt is available after 6 Confirmation, this should be applied to high-priced products.

Derivation Scheme

In the Derivation Scheme area, your own Bitcoin address is stored so that the payment receipts are credited directly to your own wallet.

The Bitcoin addresses are stored as xPub Public Bitcoin addresses. You can deposit the XPub Key from an existing Bitcoin Wallet or use the internal BTCPay Wallet.

The article Creating XPub Key with an Electrum Wallet explains how to create your own Electrum Wallet on your own computer and generate an XPub Key.

The article Deposit Xpub Key at BTCPayexplains how to deposit an xPub Key in the BTCPay Shop. Alternatively, you can use the internal BTCPay Wallet to manage your Bitcoin.


Within Rates, the exchange rate and currencies are configured.

To convert the currency used in an online store (for example Euro, USD or another Fiat currency) to Bitcoin, a conversion value must be used. The value should always correspond to the exchange rate valid at the time of payment. Therefore the BTCPay Shop queries the current price at a stock exchange.

By default the course of Coin Gecko is set. You have the possibility to choose the stock exchange yourself.


Exchange rates

Exchange rates

In the field “Add a spread on exchange rate of … ” is set to 0. This means that one takes 1:1 the exchange rate of the exchange as a basis. You can also set a small mark-up to achieve a hidden margin over the exchange rate.

The “Default currency pairs” field determines which currencies to switch to. This depends on the currencies that are required in your store. If your shop shows the products in Euros, then you have to deposit the trading pair BTC_EUR. If your shop is in USD or in pounds, then all values: BTC_USD, BTC_EUR, BTC_GBP

Save the currency pairs required for your store and run a test. Then you will receive the respective courses, which will be used as the basis for calculation at this time.

Exchange rate pairs with Coin Gecko

Exchange rate pairs with Coin Gecko

Checkout experience

In the “Checkout Experience” area, the checkout page or payment page is designed, which the end customer will see during the payment process.

The stored standard page is in the design of BTCPay:

BTCPay Checkout Page

BTCPay Checkout Page

However, this payment page can be individually designed and adapted in the look & feel of the shop page.


e.g. own PaymentPage

How this is done is explained in detail in the chapter“Create a payment page“.

Access tokens

This area generates a token to enable communication between an external application and the BTCPay server.

Access Tokens

Access Tokens

After clicking “Create a new token”, there is still the option to define a “label”.



After that you click on Request Pairing and the following page will appear

Administer BTCPay Shop 1

with the “Server initiated pairing code:”. In addition, if no wallet has been connected to the BTCPay Store.

Since the API connection of BTCPay is analogous to Bitpay, the Bitpay Doko is referred for further information on the pairing procedure.

The Bitpay API documentation can be used analogously for the BTCPay API documentation.


The Users section manages the users who have access to this shop.

Manage User

Manage User

Pay Button

The Pay button is intended as a donation button for your own page.

Pay Button Note

Pay Button Note

It is revisited that an external application is approving access to the system. The external application, the Pay button, allows invoices to be created, which users can then pay.

If you have clicked on the green button, the following page will appear:

Pay Button

Pay Button

The configuration and setup of the Pay button is described in detail under: Application example Payment Button
To the table of contents

This post is also available in: German