Description
This plugin adds BTCPay Server as a payment gateway inside FluentCart. At checkout the customer
is redirected to your BTCPay Server’s hosted invoice page, pays with Bitcoin on-chain or over
Lightning, and is redirected back to your store. BTCPay notifies your store through a webhook
and the FluentCart order is marked paid.
You run the payment infrastructure yourself. There is no account to open with us, no middleman
holding your funds, and no percentage fee – the plugin talks only to the BTCPay Server instance
whose address you enter in the settings.
Features
- One-time payments only (BTCPay has no native recurring crypto billing, so subscriptions are out of scope)
- Redirect checkout – BTCPay’s hosted page handles on-chain vs. Lightning and currency selection
- Webhook-based payment confirmation, verified with HMAC-SHA256 (
BTCPay-Sig) - No external dependencies – talks to the BTCPay Greenfield REST API directly
Requirements
- FluentCart 1.2.5 or higher
- A BTCPay Server instance you control (self-hosted or on a third-party host), reachable over HTTPS
- PHP 7.4 or higher
External services
This plugin connects to one external service: the BTCPay Server instance that you configure
yourself in the plugin settings. No connection is made until you enter a host, Store ID and API
key. The plugin does not contact BTCPay Server’s own servers, our servers, or any other
third-party service.
What is sent, and when
- When a customer places an order with the Bitcoin payment method, the plugin sends the order
amount, the currency code, the order ID and reference, and the return/redirect URLs of your
store to your BTCPay Server, in order to create an invoice. Your API key is sent as an
authorization header on this request. - When your store loads the payment settings screen or verifies an invoice, the plugin requests
invoice and store details from your BTCPay Server. - Your BTCPay Server sends webhook notifications back to your store when an invoice is settled,
expires, or becomes invalid.
No customer personal data (name, email, address) is sent to BTCPay Server by this plugin, and no
data is sent anywhere else.
Because the BTCPay Server instance is one you choose and operate, the applicable terms and
privacy policy are those of that instance and its host. BTCPay Server is free and open-source
software; its project terms and documentation are available at:
- Website: https://btcpayserver.org/
- Documentation: https://docs.btcpayserver.org/
- Source: https://github.com/btcpayserver/btcpayserver
Screenshots
Installation
- Install and activate FluentCart (1.2.5 or higher).
- Upload/activate this plugin.
- In BTCPay Server, create a Greenfield API key: Account -> Manage Account -> API Keys ->
Generate Key, with at least the “Create an invoice” (
btcpay.store.cancreateinvoice) and “View invoices” (btcpay.store.canviewinvoices) permissions for your store. - In WordPress go to FluentCart -> Settings -> Payment Methods -> BTCPay Server and fill in:
- BTCPay Server Host – e.g.
https://btcpay.example.com - Store ID – from BTCPay Store Settings -> General
- API Key – the key created in step 3
- BTCPay Server Host – e.g.
- Set up the webhook (see below), then enable the payment method.
Webhook setup (required)
FluentCart is only told about completed payments through a BTCPay webhook. Without it, orders will stay pending even after the customer pays.
- In BTCPay Server open your Store -> Settings -> Webhooks and click Create Webhook.
Set the Payload URL to:
https://YOUR-SITE.com/?fluent-cart=fct_payment_listener_ipn&method=btcpay
(The exact URL for your site is shown on the plugin’s settings screen.)
- Reveal and copy the webhook Secret before saving.
- Leave “Send me everything” enabled (the plugin ignores event types it doesn’t need), save the webhook.
- Paste the secret into the Webhook Secret field in the FluentCart BTCPay settings and save.
The plugin acts on InvoiceSettled (order marked paid) and InvoiceExpired / InvoiceInvalid
(transaction marked failed if it wasn’t already paid). All other events are acknowledged and ignored.
FAQ
-
Do I need an account with you to use this?
-
No. The plugin connects only to the BTCPay Server instance you configure. There is no
registration, no API of ours involved, and no fee taken from your payments. -
Do I need to run my own BTCPay Server?
-
You need a BTCPay Server instance you control. That can be one you self-host or one on a
third-party BTCPay host. The plugin does not provide one. -
Does this support subscriptions?
-
No. BTCPay Server does not support recurring crypto billing, so subscriptions are permanently
out of scope for this gateway. -
Does this support refunds from the FluentCart admin?
-
Not yet. Note that BTCPay refunds work differently from card processors: they generate a claim
link the customer uses to pull the funds, rather than pushing money back automatically. You can
issue refunds manually from the BTCPay Server invoice screen. -
Is there a test mode?
-
No built-in sandbox toggle – test against a separate shop/BTCPay store (e.g. one on testnet or
regtest) instead. -
Why must the BTCPay host be https?
-
Your Greenfield API key is sent as an authorization header on every request. Over plain http it
would travel in the clear, so the settings screen rejects non-https hosts. -
My orders stay pending after the customer pays. What’s wrong?
-
Almost always a webhook problem. Check that the webhook exists in BTCPay, that its Payload URL
matches the one shown on the plugin settings screen, and that the Webhook Secret saved in
WordPress matches the one BTCPay generated. BTCPay’s webhook screen shows recent delivery
attempts and their responses.
Reviews
There are no reviews for this plugin.
Contributors & Developers
“Bitcoin and Lightning Payments for FluentCart” is open source software. The following people have contributed to this plugin.
Contributors
Translate “Bitcoin and Lightning Payments for FluentCart” into your language.
Interested in development?
Browse the code, check out the SVN repository, or subscribe to the development log by RSS.
Changelog
0.1.0
- First submitted version after approval.
- Added the full GPLv2 license text and copyright notice.