BTCPay Server Interface

BTCPay Server - Store settings

Mastering BTC Pay Server

BTCPay Server - Store settings

General
Rates
Checkout Appearance
Access Tokens
Users
Roles
Webhooks
Payout Processors
Emails
Forms
Skill Summary
Knowledge Assessments

Within the BTCPay Server software, we are aware of two types of settings. BTCPay Server Store-specific settings, the settings button found in the left menu bar below the Dashboard, and BTCPay Server settings, found at the bottom of the menu bar, right above Account. The BTCPay Server Server-specific settings can only be viewed by Server administrators.

The store settings consist of many tabs to categorize each set of settings.

General
Rates
Checkout Appearance
Access Tokens
Users
Roles
Webhooks
Payout Processors
Emails
Forms

General

In the General Settings tab, store owners set their branding and payment defaults. At the initial setup of the store, a store name was given; this will be reflected in the General settings under Store Name. Here, the store owner can also set their website to match branding and a Store ID for the Administrator to recognize in the database.

Branding

As BTCPay Server is FOSS, a store owner can do custom branding to match their store. Set the brand color, store your brand’s logos, and add custom CSS for public/customer-facing pages (Invoices, Payment Requests, Pull payments)

Payment

In the payments settings, store owners can set their store's default currency (either Bitcoin or any fiat currency).

Allow anyone to create invoices

This setting is meant for developers or builders on top of BTCPay Server. With this setting enabled for your store, it allows the outside world to create invoices on your BTCPay Server instance.

Add additional Fee (network fee) to invoices

A feature within BTCPay to protect merchants from dust attacks or clients from incurring a high cost in fees later on when the merchant needs to move a large amount of bitcoin at once. For example, the customer created an invoice for 20$ and paid it partially, paying 1$ 20 times until the invoice was fully paid. The merchant now has a larger transaction, which increases the mining cost if the merchant decides to move those funds later. By default, BTCPay applies an additional network cost to the total invoice amount to cover that expense for the merchant when the invoice is paid in multiple transactions. BTCPay offers several options to customize this protection feature. You can apply a network fee:

Only if the customer makes more than one payment for the invoice (In the above example, if the customer created an invoice for 20$ and paid 1$, the total invoice due is now 19$ + the network fee. The network fee is applied after the first payment)
On every payment (including the first payment, in our example, the total will be 20$ + network fee right away, even on the first payment)
Never add network fee (disables the network fee entirely)

While it protects from dust transactions, it can also reflect negatively on businesses if not communicated properly. Customers may have additional questions and think you are overcharging them.

Invoice expires if the full amount has not been paid after?

The invoice timer is set to 15 minutes by default. The timer serves as a protection mechanism against volatility, as it locks the Bitcoin amount according to the Bitcoin-to-fiat exchange rates. If the customer does not pay the invoice within the defined period, the invoice is considered expired. The invoice is considered "paid" as soon as the transaction is visible on the blockchain (with zero confirmations), and is "complete" when it reaches the number of confirmations the merchant has defined (usually 1-6). The timer is customizable by minutes.

Consider the invoice paid even if the paid amount is X% less than expected?

When a customer uses an exchange wallet to pay directly for an invoice, the exchange takes a small fee. This means that such an invoice is not considered fully completed. The invoice is marked as "paid partially". You can set the percentage rate here if a merchant wants to accept underpaid invoices.

Rates

In BTCPay Server, when an invoice gets generated, it always needs the most up-to-date and accurate Bitcoin-to-fiat price. When creating a new store in BTCPay Server, administrators are asked to set their preferred price source. After the store is set up, store owners can change their price source in this tab at any time.

Advanced rate rule scripting

Mainly used by power users. If toggled on, store owners can create scripts around price behavior and how to charge their customers.

Testing

A quick testing place for your preferred currency pairs. This feature also includes the ability to check default currency pairs via a REST query.

Checkout Appearance

The Checkout Appearance tab begins with invoice-specific settings and a default payment method, and enables specific payment methods when the set requirements are met.

Invoice settings

Default payment methods. The BTCPay Server, in its standard configuration, offers three options.

BTC (on-chain)
BTC (LNURL-pay)
BTC (Off-chain & Lightning)

We can set parameters for our store, where a customer will only interact with Lightning when the price is less than X amount, and vice versa for On-chain transactions, when X is greater than Y, always present the On-chain payment option.

Checkout

As of BTCPay Server release 1.7, a new Checkout interface, Checkout V2, was introduced. Since release 1.9 was standardized, administrators and store owners can still set the checkout to the previous release. By using the toggle "Use the classic checkout", a store owner can revert the store to its previous checkout experience. BTCPay Server also has a select set of presets for Online commerce or an in-store experience.

When a customer interacts with the store and generates an invoice, there is an expiration time for the invoice. By default, BTCPay Server sets this to 5 minutes, and administrators can adjust it to their preference. The checkout page can further be customized by checking the following parameters:

Celebrate payment by showing confetti
Show the store header (Name and logo)
Show the "Pay in wallet" button
Unify on-chain and off-chain payments URL/QRs
Display Lightning payment amounts in Satoshis
Auto-detect language on checkout

When Auto-detect language is not set, BTCPay Server, by default, will display English. A store owner can change this default to their preferred language.

Click on the drop-down, and Store owners can set a Custom HTML title to be displayed on the checkout page.

To ensure customers know their payment method, a store owner can explicitly set their checkout always to require users to choose their preferred payment method. Once the invoice is paid, BTCPay Server allows the customer to return to the webshop. Store owners can set this redirect to be automatically applied after the customer has paid.

Public receipt

Within the public receipt settings, a store owner can set the receipt pages to be public, displaying the payment list on the receipt page and the QR code for the customer to access it easily.

Access Tokens

Access tokens are used for pairing with certain e-commerce integrations or custom-built integrations.

Users

Store users are where the store owner can manage his staff members, their accounts, and access to the store. After staff members create their accounts, the store owner can add specific users to the store as Guest users or owners. To further define the staffer’s role, refer to the next section on “BTCPay Server Store settings - Roles.”

Roles

A store owner might not find the user’s standard roles significant enough. In the custom roles settings, a store owner can define the exact needs for each role in their business.

(1) To create a new role, click the "+ Add role" button.

(2) Enter a Role name, for example, "Cashier".

(3) Configure the individual permissions for the role.

Modify your stores.
Manage exchange accounts linked to your stores.
- View exchange accounts linked to your stores.
Manage your pull payments.
Create pull payments.
- Create non-approved pull payments.
Modify invoices.
- View invoices.
- Create an invoice.
- Create invoices from the lightning nodes associated with your stores.
View your stores.
- View invoices.
- View your payment requests.
- Modify stores’ webhooks.
Modify your payment requests.
- View your payment requests.
Use the lightning nodes associated with your stores.
- View the lightning invoices associated with your stores.
- Create invoices from the lightning nodes associated with your stores.
Deposit funds to exchange accounts linked to your stores.
Withdraw funds from exchange accounts to your store.
Trade funds on your store’s exchange accounts.

When the role gets created, the name is fixed and cannot be changed after it is in edit mode.

Webhooks

Within BTCPay Server, it's reasonably easy to make a new "Webhook". In the BTCPay Server Store settings - Webhooks tab, a store owner can easily create a new webhook by clicking on the "+ Create Webhook". Webhooks allow BTCPay Server to send HTTP events related to your store to other servers or ecommerce integrations.

You're now in the view for creating a Webhook. Make sure you know your Payload URL and paste this into your BTCPay Server. While you pasted the payload URL, underneath it shows the webhook secret. Copy the webhook secret and provide it on the endpoint. When everything has been set, you can toggle in BTCPay Server to "Automatic redelivery." BTCPay Server will try to redeliver any failed delivery after 10 seconds, 1 minute, and up to 6 times after 10 minutes. You can toggle between every event or specify the events for your needs. Make sure to enable the webhook and hit the "Add webhook" button to save it.

Webhooks are not meant to be compatible with the Bitpay API. There are two separate IPNs (in BitPay terms: "Instant Payment Notifications") in BTCPay Server.

Webhookp
Notifications

Only use the Notification URL when you create invoices through the Bitpay API.

Payout Processors

Payout processors work together with the Payouts concept in BTCPay Server. A payout aggregator to batch multiple transactions and send them at once. With payout processors, a store owner can automate the batched payouts. BTCPay Server offers two methods of automated payouts: on-chain and Off-chain (LN).

The store owner can click and configure both payout processors separately. A store owner might only want to run the on-chain processor once every X hours, whereas the off-chain processor might run every few minutes. For On-chain, you may also set a target for which block it should be included. By default, this is set to 1 (or the next block available). Notice that setting the Off-chain payout processor only has the interval timer and no block target. Lightning network payments are instant.

Store owners can only configure the on-chain processor if they have a Hot wallet connected to their store.

After setting up a Payout processor, you can quickly remove or modify it by returning to the Payout processor tab in BTCPay Server Store settings.

Note

Payout processor on-chain - The on-chain payouts processor can only work on a store configured with a Hot wallet connected. If no hot wallet is connected, the BTCPay Server does not hold the wallet keys and won’t be able to process payouts automatically.

Emails

BTCPay Server can use Emails for Notifications or, when set correctly, to recover accounts created on the instance. As standard, BTCPay Server does not send an email when the password is lost, for example.

Before a store owner can set Email rules to trigger specific events in their store, they must first set up some basic email settings. BTCPay Server requires these settings to send emails for events related to your store or for password resets.

BTCPay Server made it easier to fill out this information by using the "Quick Fill" Option:

Gmail.com
Yahoo.com
Mailgun
Office365
SendGrid

By using the quick fill option, BTCPay Server will pre-populate the fields for the SMTP server and port. Now, the store owner only needs to fill out their credentials, including an Email address, Login (which is usually equal to your email address), and their password. The advanced option in the BTCPay Server email settings is to Disable TLS Certificate security checks; by default, this is enabled.

With Email rules, a store owner can set specific events to trigger emails to specific email addresses.

Invoice Created
Invoice Received Payment
Invoice Processing
Invoice Expired
Invoice Settled
Invoice Invalid
Invoice Payment Settled

If the customer has provided an Email address, these triggers can also send the information to the customer. Store owners can pre-fill the Subject line to make it clear why this Email happened and what triggered it.

Forms

As BTCPay Server does not gather any data, a store owner might want to add a custom form to their checkout experience; this way, the store owner can collect additional information from their customer. BTCPay Server Form builder consists of two parts: a visual and more advanced code view of the forms.

When creating a new form, BTCPay Server opens a new window requesting basic information on what you want your new form to ask. At first, the store owner needs to give a clear name for their new form; this name cannot be changed after it is set.

After the store owner gives the form a name, you may also toggle the switch for "Allow form for public use" to ON, and it will turn green. This ensures the form is used in every customer-facing location. For example, if a store owner creates a separate invoice not through their Point Of Sale, they might still want to gather information from the customer. This toggle allows for that information to be collected.

Every form starts with at least 1 New form field. A store owner can pick what type of field it should be.

Text
Number
Password
Email
URL
Telephone numbers
Date
Hidden fields
Fieldset
A text area for open comments.
Option selector

Every type comes with its parameters to fill. The store owner can set it to his liking. Below the first created field, store owners can add new fields to this form.

Advanced custom forms

BTCPay Server also allows you to build Forms in code. JSON, in particular. Instead of looking at the editor, store owners can click on the CODE button right next to the editor and get into the code of their Forms. In a field definition, only the following fields can be set; the values of the fields are stored in the metadata of the invoice:

Field	Description
.fields.constant	If true, the .value must be set in the form definition, and the user will not be able to change the field's value. ( example: the form definition's version)
.fields.type	The HTML input type text, radio, checkbox, password, hidden, button, color, date, datetime-local, month, week, time, email, number, range, search, url, select, tel
.fields.options	If .fields.type is select, the list of selectable values
.fields.options.text	The text displayed for this option
.fields.options.value	The value of the field if this option is selected
.fields.type=fieldset	Create a HTML fieldset around the children .fields.fields (see below)
.fields.name	The JSON property name of the field as it will appear in the invoice's metadata
.fields.value	The default value of the field
.fields.required	if true, the field will be required
.fields.label	The label of the field
.fields.helpText	Additional text to provide an explanation for the field.
.fields.fields	You can organize your fields in a hierarchy, allowing child fields to be nested within the invoice’s metadata. This structure can help you better organize and manage the collected information, making it easier to access and interpret. For example, if you have a form that collects customer information, you can group the fields under a parent field called customer. Within this parent field, you might have child fields like name, Email, and address.

The field name represents the JSON property name that stores the user-provided value in the invoice’s metadata. Some well-known names can be interpreted and modified to adjust the invoice’s settings.

Field name	Description
invoice_amount	The invoice's amount
invoice_currency	The invoice's currency

You can pre-fill the fields of an invoice automatically by adding query strings to the form’s URL, such as "?your_field=value".

Here are some use cases for this feature:

Assisting user input: Pre-fill fields with known customer information to make it easier for them to complete the form. For example, if you already know a customer’s email address, you can pre-fill the email field to save them time.
Personalization: Customize the form based on customer preferences or segmentation. For instance, if you have different customer tiers, you can pre-fill the form with relevant data, such as their membership level or specific offers.
Tracking: Track the source of customer visits using hidden fields and pre-filled values. For example, you can create links with pre-filled utm_media values for each marketing channel (e.g., Twitter, Facebook, Email). This helps you analyze the effectiveness of your marketing efforts.
A/B testing: Pre-fill fields with different values to test different form versions, enabling you to optimize the user experience and conversion rates.

Skill Summary

In this section, you learned the following:

The layout and functions of the tabs in the Store Settings
A multitude of options for fine-tuning the handling of underlying exchange rates, partial payments, slight underpayments, and more.
Customize the checkout appearance, including price-dependent main chain vs. Lightning enablement on invoices.
Manage levels of store access and permissions across roles.
Configure automated emails and their triggers
Create custom forms for gathering additional customer information at checkout.

Knowledge Assessments

KA Review

What is the difference between Store Settings and Server Settings?

KA Hypothetical

Describe some options you might select in Checkout Appearance > Invoice Settings, and why.