This post describes how you can accept Bitcoin and Lightning payments in a WooCommerce store with the help of BTCPay server.
WooCommerce is the store system of WordPress and allows to extend any website under WordPress to an online store.
This post is about how to install and configure the BTCPay plugin in an already existing WooCommerce.
In addition to WooCommerce, you are required to have a BTCPay store set up on a BTCPay server.
The BTCPay Store manual describes how to set up or share a BTCPay Store.
If you have a WooCommerce online store and have created a BTCPay store, we can get started.
This paper is divided into the following sections:
- Install BTCPay plugin on WordPress
- Install BTCPay for WooCommerce V2
- WooCommerce Payments
- BTCPay Plugin Payments Settings
- BTCPay Settings Part 1
- BTCPay Server
- BTCPay Settings Part 2
- Order Status
- Customer view in store
- proceed to BTCPay
- Implementation of Bitcoin in your WooCommerce online store from Coincharge
By clicking on the respective images you will get to a detailed view.
Install BTCPay plugin on WordPress
In March 2022, a new version of WooCommerce plugin by BTCPay Server has been released.
The previous plugin (BTCPay for WooCommerce – Legacy) is therefore no longer up to date. For those who still use the old plugin, it is recommended to change the new plugin.
If you are using the old plugin and want to switch to the latest version now, then deactivate the old plugin and after successfully setting up the new plugin, it can then also be removed.
The first step is to install the BTCPay for WooCommerce V2 plugin. To do this, go to the Plugins section within WordPress.
There you will find the Add Plugins section. There is a search field. Enter the search term BTCPay in this search field.
You will see all plugins that are related to BTCPay. You select the plugin called BTCPay for WooCommerce V2. The legacy version is the obsolete version which should not be used.
After BTCPay for WooCommerce V2 plugin is installed and activated on WordPress, it will be listed as another payment method on WooCommerce.
In addition, in the upper area of WordPress with a red bar the notice is displayed. “please configure the plugin here“.
You can click on the corresponding link or go directly to the payment settings at WooCommerce.
Switch to WooCommerce => Settings => Payments and there BTCPay is listed as inactive.
Also on the far right is a new tab labeled BTCPay Settings.
BTCPay Plugin Payments Settings
In the WooCommerce settings in the Payments section are the settings options, which are displayed to the payer on the checkout page.
On this checkout page all payment methods are listed, which are offered to the customer.
One payment method will be Bitcoin. The Title field specifies what the label will be.
In the deposited setting, the option “BTCPay (Bitcoin, Lightning Network, …)” would be displayed to the payer.
Since we assume that a payer will not be able to do anything with BTCPay, we recommend a unique name such as Bitcoin only.
The Customer Message is used to explain to the customer what happens when he selects the appropriate payment method. Since the default setting indicates that you will be redirected to a BTCPay page, we change the text to Bitcoin. “You will be redirected to a Bitcoin payment page to complete your order.”
An icon is displayed behind the information from the Title field described above. This gateway icon is the BTCPay logo. Instead of the BTCPay logo, you can store a Bitcoin logo, which will then be displayed.
Enforce payment tokens
Since we do not want to use a separate payment gateway, we will keep the default setting and leave this option disabled.
We want to allow payment by Bitcoin worldwide and do not restrict it to certain countries.
BTCPay Settings Part 1
In the WooCommerce settings there is another tab called BTCPay Settings.
WooCommerce => Settings => BTCPay Settings
At this point, a connection is made between our WooCommerce online store and our BTCPay store.
If no data has been stored yet, then it looks like this:
BTCPay Server URL
Here the url of the BTCPay server is entered, on which the BTCPay store is located, to which the connection is to be made.
Enter the url of your own BTCPay server. In our example, we use the BTCPay server from Coincharge.
BTCPay API Key
When the BTCPay Server Url is entered, under BTCPay API Key the link appears with the text: “click here to generate API keys”
You will be redirected to the url of the BTCPay server that was previously entered as the BTCPay server url.
After clicking on the above link, you will see the login window of the BTCPay server.
Here you log in with the access data you used to create a BTCPay store in advance.
If such a BTCPay store has not been created yet, you can do so now. Here you can find instructions on how to create a BTCPay Store.
After successful login, you will automatically be taken to the Authorization Request page, as shown in the image below.
If this page is not displayed, go back to the BTCPay plugin and click on the corresponding link again.
Various functions are listed for which permission is given to allow the WooCommerce store to process this information.
In the first step we assign a label name. In our example WooCommerce.
Then we give permission to each individual function. If we have more than one BTCPay store, we need to select the specific BTCPay store for which the authorization is granted under “select specific store”.
It is mandatory that the respective BTCPay store is selected. This is also necessary if you have only one BTCPay store.
If the selection is not made for all possibilities, then it does not work.
After that we click on Authorize App.
BTCPay Settings Part 2
After clicking Authorize App, we will be automatically redirected to the BTCPay Settings section on WooCommerce.
The API Key and Store ID previously created on the BTCPay Server are automatically pre-filled.
Default Customer Message
Here the information is displayed for the customers what will happen when they select the payment method. The text displayed here will be overwritten by the note we have stored in the Payments section.
There we had already changed the text in the form that customers are redirected to a Bitcoin payment page.
Therefore, it is not necessary to change the text at this point.
Invoice pass to “settled” state after
Here you can define after how many confirmations on the blockchain a Bitcoin payment is considered as received (“settled”).
When a payment is considered to be received, then the WooCommerce store sends the customer a confirmation of the order.
So when should the customer be informed that the order was successful?
It can be selected that after 0, 1, 2 or 6 confirmations on the blockchain the payment is considered settled.
The selection of the number of confirmations depends on the type of product (digital or physical) and the value of the product.
A digital product worth a few cents should be discontinued with 0 Confirmation, because no end customer wants to wait a long time for such a product.
If I sell a high quality product, which is sent by mail, then you should choose a high confirmation number.
Basically we recommend that this setting is made in the BTCPay Store settings and therefore “Keep BTCPay Server store level configuration” is made at this point.
Wallet Payment Settings
The setting, after how many confirmations on the blockchain a Bitcoin payment is considered as settled, should be made in the payment settings for the Bitcoin wallet.
You can access the settings via:
BTCPay Server => Wallet => Settings => Payment
Here, as described above, the number of confirmations on the blockchain can be set, from when a payment is considered confirmed (“settled”).
If the input in the mempool is already sufficient, then these are 0 confirmations and you select ls unconfirmed. This is recommended for low amounts and digital goods. For higher quality products, there are the setting options for 1,2 or 6 confirmations.
In the Order States field the order status is processed.
Depending on your business model and store settings, you can configure the order status.
We recommend keeping the preset values.
For better understanding, an explanation of the different values.
- New – New order – Order has been placed but not yet paid. The payment is pending
- Paid – Order is paid, but not yet confirmed on the blockchain. The status is On hold.
- Settled – Order completed and confirmed on the blockchain.
- Settled (Paid over) – More sats were sent by the payer than were requested.
- Invalid – order paid but did not receive the sufficient number of confirmations within the predefined time frame set in the BTCPay settings.
- Expired – Invoice expired, order not paid
- Expired with partial payment – Expired after partial payment.
You can adapt these values to your individual business models.
Each BTCPay status has an impact on what WooCommerce then executes.
What information should be communicated to the buyer through WooCommerce?
Ideally, you should keep the predefined settings and perform appropriate test orders in your WooCommerce online store.
Customer view in store
On the so-called checkout page, the customer enters his personal data and is then shown the available payment methods.
In our example store from https://store.coincharge.io/there is only the payment method Bitcoin and Lightning.
Accordingly, it then looks like this:
The customer then has the option to switch to the Bitcoin payment page by clicking on the button with the text “Proceed to BTCPay”.
The Bitcoin payment page can also be customized and adapted. You can find more information at: Bitcoin payment page.
If you want to change the text “Proceed to BTCPay”, this is only possible if the corresponding PHP file is changed.
If you want to change the text to “Pay with Bitcoin now”, for example, you can find the corresponding instructions in the next sections.
proceed to BTCpay
Then there is the button “proceed to BTCpay”.
Most end customers will not be able to do much with BTCPay. In order not to confuse these customers, we have changed the text to “proceed to Bitcoin”.
For this we need to go to the file server in the directory where the BTCPay WooCommerce plugin is placed.
Located in: / httpdocs / wp-content / plugins / btcpay-for-woocommerce /
and there we have to edit the file: class-wc-gateway-btcpay.php edit.
We open the file and look for the phrase “proceed to BTCpay” and change the text to “proceed to Bitcoin” and save the file.
Any online store which is based on WooCommerce can accept Bitcoin payments.
This requires a BTCPay store, which can be set up on a BTCPay server. If you don’t have your own BTCPay server, you can use Coincharge’s BTCPay server.
Then you only need the plugin BTCPay WooCommerce V2 and with the help of this guide, you can receive Bitcoin on your own Bitcoin wallet.
If you want to set up the BTCPay for WooCommerce V2 plugin for your online store, you can find more information on the BTCPay server itself at: https://docs.btcpayserver.org/WooCommerce/and as a YouTube video at: How to accept bitcoin in WooCommerce
Implementation of Bitcoin in your WooCommerce online store from Coincharge
If you don’t want to do the Bitcoin integration in your WooCommerce online store yourself, you can also let Coincharge do it for you.
For a one-time fee of €249,- we implement Bitcoin into your WooCommerce online store.
The service includes the following:
BTCPay integration into your online store
249,00 € – 449,00 €
BTCPay integration into your online store
- Install Bitcoin payment plugin in online store
- Creating a BTCPay Store on a BTCPay Server
- Configuration of the BTCPay Store
- Deposit Bitcoin address (xPub key) of the store owner
- Creation Bitcoin payment page in store design
- Connecting the online store with the BTCPay Store
- Activation Bitcoin as a payment method
- Support and update for 1 year
BTCPay integration into your online store
Accept Bitcoin and Lightning payment with payment processing through a BTCPay server.
We integrate Bitcoin and Lightning payments into your online store and connect the online store to a BTCPay server for payment processing.
Installation Bitcoin payment in online store
The corresponding Bitcoin plugin or software is installed in the online store.
Setting up a BTCPay Store on the BTCPay Server
We set up a BTCPay store on the BTCPay server of your choice. You can use Coincharge’s BTCPay server at no extra cost or use your own BTCPay server.
If you do not have your own BTCPay server, you can add the product “BTCPay Server Setup“.
Configuration of the BTCPay Store
A BTCPay store is set up on the BTCPay server and adjusted based on the individual requirements of the online store.
Deposit Bitcoin address (xPub key) of the store owner
In the BTCPay store on the BTCPay server the Bitcoin address of the store owner is stored as xPub key. Thus, all incoming Bitcoin are credited directly to the store owner’s own Bitcoin wallet.
Creation Bitcoin payment page in store design
The payment page for the customer is customized in the design of the online store.
Connecting the online store with the BTCPay Store
The online store is connected to the BTCPay store on the BTCPay server so that the systems can interact with each other.
Activation Bitcoin as a payment method
Activation and enabling of the Bitcoin and Lightning payment method in the online store.
Support and Update
Including support for 1 year and update of the corresponding extension / plugin / module
For the use of the BTCPayServer, corresponding store modules are available for the following store software:, Shopify, Drupal, Magento, PrestaShop, ShopWare, API connection