BTCPay Server Interface

BTCPay Server - Payments

Mastering BTC Pay Server

BTCPay Server - Payments

General
Requests
Pull payments
Payouts
Pull payments
Skill Summary
Knowledge assessment

An invoice is a document that the seller issues to a buyer to collect payment.

In BTCPay Server, an invoice represents a document that must be paid within a defined time interval at a fixed exchange rate. Invoices have expiration dates because they lock the exchange rate within a specified time frame, protecting the receiver from price fluctuations.

The core of BTCPay Server is the ability to act as a Bitcoin invoice management system. An invoice is an essential tool for tracking and managing received payments.

Unless you use a built-in Wallet to receive payments manually, all payments within a store will be shown on the Invoices page. This page cumulatively sorts payments by date and serves as a central resource for invoice management and payment troubleshooting.

General

Invoice statuses

The table below lists and describes the standard invoice statuses in BTCPay, along with suggested common actions. Actions are just recommendations. It’s up to users to define the best course of action for their use case and business.

Invoice Status	Description	Action
New	Not paid, invoice timer still has not expired	None
New (paidPartial)	Paid, not in full, invoice timer still has not expired	None
Expired	Not paid, invoice timer expired	None
Expired (paidPartial) **	Paid, not in full amount, and expired	Contact buyer to arrange a refund or ask for them to pay their due. Optionally mark the invoice as settled or invalid
Expired (paidLate)	Paid, in full amount, after the invoice timer has expired	Contact buyer to arrange a refund or process order if late confirmations are acceptable.
Settled (paidOver)	Paid more than the invoice amount, settled, received sufficient amount of confirmations	Contact buyer to arrange a refund for the extra amount, or optionally wait for buyer to contact you
Processing	Paid in full, but has not received sufficient amount of confirmations specified in the store settings	Contact buyer to arrange a refund for the extra amount, or optionally wait for buyer to contact you
Processing (paidOver)	Paid more than the invoice amount, not received sufficient amount of confirmations	Wait to be settled, then contact the buyer to arrange a refund for the extra amount, or optionally wait for buyer to contact you
Settled	Paid, in full, received sufficient amount of confirmations in store	Fulfil the order
Settled (marked)	Status was manually changed to settled from a processing or invalid status	Store admin has marked the payment as settled
Invalid*	Paid, but failed to receive sufficient amount of confirmations within the time specified in store settings	Check the transaction on a blockchain explorer, if it received sufficient confirmations, mark as settled
Invalid (marked)	Status was manually changed to invalid from a settled or expired status	Store admin has marked the payment as invalid
Invalid (paidOver)	Paid more than the invoice amount, but failed to receive sufficient amount of confirmations within the time specified in store settings	Check the transaction on a blockchain explorer, if it received sufficient confirmations, mark as settled

Invoice details

The invoice details page contains all information related to an invoice.

Invoice information is created automatically based on invoice status, exchange rate, etc. Product information is created automatically if the invoice was created with product information, such as in the Point of Sale app.

Invoice filtering

Invoices can be filtered via the quick filters located next to the search button or the advanced filters, which can be toggled by clicking the (Help) link at the top. Users can filter invoices by store, order ID, item ID, status, or date.

Invoice export

BTCPay Server Invoices can be exported in CSV or JSON format. For more information about invoice export and accounting.

Refunding an invoice

If, for any reason, you would like to issue a refund, you can easily create a refund from the invoice view.

Archiving invoices

As a result of the no address re-use feature of BTCPay Server, it is common to see many expired invoices on your store’s invoice page. To hide them from your view, select them in the list and mark them as archived. Invoices that have been marked as archived are not deleted. Payment to an archived invoice will still be detected by your BTCPay Server (paidLate status). You can view the store’s archived invoices at any time by selecting archived invoices from the search filter dropdown.

Default Currency

Store default currency, which was set at the store creation wizard.

Allow anyone to create an invoice

You should enable this option if you want to allow the outside world to create invoices in your store. This option is only useful if you're using the payment button or if you're issuing invoices via API or a third-party HTML website. The PoS app is pre-authorised and does not require this setting to be enabled for a random visitor to open your POS store and create an invoice.

Add an Additional fee (network fee) to the invoice

Only if the customer makes more than one payment for the invoice
On every payment
Never add a network fee

Invoice expires if the full amount has not been paid after .. Minutes.

The invoice timer is set to 15 minutes by default. The timer serves as a protection mechanism against volatility, as it locks the cryptocurrency amount based on the crypto-to-fiat 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 considered "complete" when it reaches the number of confirmations the merchant has defined (usually 1-6). The timer is customizable.

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

In a situation where 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." If a merchant wants to accept underpaid invoices, you can set the percentage rate here

Requests

Payment Requests are a feature that allows BTCPay store owners to create long-lived invoices. Funds are paid according to the payment request using the exchange rate in effect at the time of payment. This allows users to make payments at their convenience without needing to negotiate or verify exchange rates with the store owner at the time of payment.

Users can pay for requests in partial payments. The payment request will remain valid until it is paid in full or if the store owner requires an expiration time. Addresses are never reused. A new address is generated each time the user clicks pay to create an invoice for the payment request.

Store owners can print payment requests (or export invoice data) for record-keeping and accounting. BTCPay automatically labels invoices as Payment Requests in your store’s invoice list.

Customize Your Payment Requests

Invoice Amount - Set Requested Payment Amount
Denomination - Show Requested Amount in Fiat or Cryptocurrency
Payment Quantity - Allow only single payments or partial payments
Expiration Time - Allow payments until a date or without expiry
Description - Text Editor, Data Tables, Embed Photos & Videos
Appearance - Color and Style with CSS Themes

Create a Payment Request

In the left menu, go to Payment Request and click "Create Payment Request".

Provide the Request Name, Amount, Display Denomination, Associated Store, Expiration Time & Description (Optional)

Select the option Allow payee to create invoices in their denomination if you want to allow partial payments.

Click Save & View to review your payment request.

BTCPay creates a URL for the payment request. Share this URL to view your payment request. Need multiple of the same request? You can duplicate payment requests using the Clone option in the main menu.

WARNING

Payment requests are store-dependent, meaning each payment request is associated with a store during creation. Be sure to have a wallet connected to your store that the payment request belongs to.

Paid Request

The payee and requester can view the status of the payment request after the payment has been sent. The status will appear as Settled if payment has been received in full. If only partial payments have been made, the Amount Due will display the remaining balance.

Customize Payment Requests

The description content can be edited using the payment request’s text editor. Both options are available if you want to use additional color themes or custom CSS styling.

Non-technical users can use a bootstrap theme. Further customization can be done by providing additional CSS code, as shown below.

:root {
  --btcpay-font-family-base: "Source Sans Pro", -apple-system,
    BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif;
  --btcpay-primary: #7d4698;
  --btcpay-primary-accent: #59316b;
  --btcpay-body-text: #333a41;
  --btcpay-body-bg: #fff;
  --btcpay-bg-tile: #f8f9fa;
}

#mainNav {
  color: white;
  background: linear-gradient(#59316b, #331840);
}

#mainNav .btn-link {
  color: white;
}

Pull payments

Traditionally, a receiver shares their Bitcoin address to make a Bitcoin payment, and the sender later sends money to this address. Such a system is called a Push payment, as the sender initiates the payment while the receiver may be unavailable, pushing the payment to the receiver.

However, what about reversing the role?

What if, instead of a sender pushing the payment, the sender allows the receiver to pull the payment at a time the receiver sees fit? This is the concept of a Pull payment. This allows several new applications, such as:

A subscription service (where the subscriber allows the service to pull money every x amount of time)
Refunds (where the merchant allows the customer to pull the refund money to their wallet when they see fit)
Time-based billing for freelancers (where the person hiring allows the freelancer to pull money into their wallet as time gets reported)
Patronage (where the patron allows the recipient to pull money every month to continue supporting their work)
Automatic selling (where a customer of an exchange would allow an exchange to pull money from their wallet to sell every month automatically)
Balance withdrawal system (where a high-volume service allows users to request withdrawals from their balance, the service can then easily batch all the payouts to many users at fixed intervals)

Payouts

The payout functionality is tied to the Pull Payments feature. This feature allows you to create payouts within your BTCPay. This feature allows you to process pull payment (refunds, salary payouts, or withdrawals).

Example 1: Refund

Let's start with the refund example. The customer has purchased an item in your store, but unfortunately, they have to return it. They want a refund. Within BTCPay, you can create a Refund and provide the customer with the link to claim their funds. Once the customer has provided their address and claimed the funds, it will be displayed in the Payouts section.

The first status it has is Awaiting Approval. Store clerks can check if multiple ones are waiting, and after making the selection, you use the Actions button.

Options on the action button

Approve selected payouts
Approve & send selected payouts
Cancel selected payouts

The next step is to approve & send selected payouts, as we want to refund the customer. Check the Customer's Address, which shows the amount and whether we wish the fees to be subtracted from the refund or not. Once you've completed the checks, signing the transaction is the only remaining step.

The customer now gets updated on the Claiming page. He can follow the transaction as he's provided with a link to a block explorer and his transaction. Once the transaction has been confirmed, its status changes to 'Completed'.

Example 2: Salary

Now let's get into Salary payout, since this is driven from inside the store and not according to the Customer's request. The underlying concept is the same; it utilises pull payments. But instead of creating a refund, we will make a Pull Payment.

Go to the Pull Payments tab in your BTCPay server. In the top right, click the Create Pull Payment Button.

Now we are in the creation of the Payout, give it a name and the desired amount in the chosen currency. Fill out the Description, so the employee knows what it's about. The next portion is similar to refunds. The employee fills out the Destination address and the amount he wants to claim from this Payout. He might decide to make it 2 separate claims, to different addresses, or even partly claim over lightning.

If there are multiple waiting Payouts, you can batch these to be signed and sent out. Once signed, the payouts are moved to the In Progress tab and show the Transaction. When accepted by the network, the payout moves to the Completed tab. The completed tab is purely for historical purposes. It holds the processed Payouts and the transactions that belong to it

Pull payments

Concept

When a sender configures a Pull payment, they can configure a number of properties:

Pull request Name
A limit amount
A Unit (such as BTC, SAT, USD)
Payment Methods
- BTC On-chain
- BTC Off-chain
Description
Custom CSS
End date (optional for Lightning Network BOLT11)

After this, the sender can share the pull payment using a link with the receiver, allowing the receiver to create a payout. The receiver will choose their payout:

Which payment method to use
Where to send the money

Once a payout is created, it will count toward the pull payment’s limit for the current period. The sender will then approve the payout by setting the rate at which the payout will be sent and proceed with payment.

For the sender, we provide an easy-to-use method for batching multiple payouts from the BTCPay Internal Wallet.

Greenfield API

BTCPay Server provides a full API to both the sender and receiver that is documented in the /docs page of your instance. (or on the documentation website https://docs.btcpayserver.org)

Since our API exposes the full capability of pull payments, a sender can automate payments to their own needs.

Skill Summary

In this section, you learned the following:

In-depth understanding of BTCPay Server’s invoice statuses, as well as actions that can be performed on them
Customize and manage extended-life invoice mechanisms known as Requests.
The additional flexible payment possibilities opened up with BTCPay Server’s unique Pull Payment feature, particularly in handling refunds and salary payments.

Knowledge assessment

KA Conceptual Review

What are some differences between invoices and payment requests, and what might be a good reason for using the latter?

KA Conceptual Review

How do pull payments expand on what typically can be done on-chain? Describe some use cases they enable.