BitPay: crypto payments
Set up the free BitPay plugin: POS API token, test mode, checkout display, how crypto payments are confirmed, refunds and troubleshooting.
The BitPay plugin adds BitPay as a payment method at checkout, so your customers can pay invoices in cryptocurrency on a BitPay invoice page. FluxBilling creates a BitPay invoice for the amount due, sends the customer to it, and marks the FluxBilling invoice paid once BitPay reports the payment as confirmed. The plugin is free and is listed in the plugin marketplace of every FluxBilling panel.
This guide covers plugin version 2.7. It walks through the setup in the order you do it, then explains what your customers see, how payments are confirmed, what to do about refunds, and what to check when something does not work.
Who supports this integration. The plugin is built and maintained by FluxBilling. If something does not work, contact FluxBilling support at contact@fluxbilling.app or through fluxbilling.app/contact. Questions about your BitPay account, the coins it accepts, fees, settlement or payouts go to BitPay support.
What you need before you start
- A BitPay merchant account. Sign up at bitpay.com. For testing, BitPay runs a separate test environment at test.bitpay.com with its own sign-up, where BitPay prefills test settlement and bank details. BitPay describes both on its Getting Access and Setup and Testing pages.
- A BitPay API token for the POS facade. In the BitPay dashboard, open the API Tokens page and add a new token with Require Authentication unticked. That gives a standard POS token, the kind BitPay recommends for invoice-based e-commerce integrations. A token that requires authentication (pairing with a client key) does not work with this plugin. A test account and a live account each have their own token. See BitPay's Request an API Token page.
- Your settlement and coin choices, made in BitPay. Which cryptocurrencies BitPay offers on the invoice page, and whether you are paid out in fiat or crypto, are settings of your BitPay account. The plugin has no setting for either.
- A FluxBilling panel that BitPay can reach over the internet, on HTTPS. BitPay notifies your panel when a payment changes state, and asks for an HTTPS notification address. A panel that only runs on a private network can create BitPay invoices, but does not hear about payments straight away (see Troubleshooting).
You do not need to set up notifications in the BitPay dashboard. FluxBilling sends its own notification address to BitPay with every invoice it creates, which is how BitPay's instant payment notifications work.
Step 1: Install the plugin
- In the FluxBilling admin panel, open Settings (the gear icon in the top bar).
- Under Integrations, open Marketplace. Stay on the Browse tab.
- Open the BitPay card and click Get for Free.

FluxBilling confirms with Plugin "BitPay" installed and ready to use. The plugin is switched on straight away and appears under Settings → Integrations → Plugins, marked Active. Customers do not see BitPay at checkout until you enter an API token in the next step.
Step 2: Enter your API token
- Open Settings → Integrations → Plugins.
- On the BitPay card, click Configure.
- On the Settings tab, make sure Enabled is ticked.
- Leave Test Mode ticked if your token comes from test.bitpay.com. Untick it for a token from your live bitpay.com account.
- Paste the token into BitPay API Token.
- Click Save Configuration. FluxBilling shows Configuration saved successfully.

| Field | Required | What it does |
|---|---|---|
| Enabled | No | Offers BitPay at checkout. Untick it to hide BitPay from customers without removing your token. |
| Test Mode (Enable) | No | Ticked: FluxBilling talks to BitPay's test environment, test.bitpay.com, and expects a token from your test account. Unticked: it talks to bitpay.com and takes real payments. The box is ticked when you install the plugin, until you untick it and save. |
| BitPay API Token | Yes | Your BitPay POS token, created with Require Authentication unticked. It is stored encrypted and is shown as dots. |
The token must match the mode: a test token only works with Test Mode ticked, and a live token only with it unticked.
The dialog also shows a Webhook configuration required box with your panel's notification address. For BitPay you do not need to copy it anywhere: FluxBilling hands it to BitPay with each invoice. Once BitPay has sent a notification, the box shows that deliveries are being received instead of No deliveries received yet.
The dialog has no connection test. To check the token, pay a test invoice in test mode (see step 4).
Step 3: Choose how BitPay appears at checkout
Switch to the Checkout Display tab of the same dialog to set what customers see in the list of payment methods:
| Field | What it does |
|---|---|
| Display Name (required) | The name of the payment option at checkout, for example Bitcoin and crypto (BitPay). |
| Description | The line under the name. |
| Icon | Choose a Preset icon, or Custom URL to use your own image. |
A preview at the bottom of the tab shows the result. Click Save Configuration to keep the changes.
The same gateway is listed under Settings → Financial → Payment Gateways, with a switch that turns the BitPay plugin on or off. See Payment Gateways.

Step 4: Test in test mode
With Test Mode ticked and a token from test.bitpay.com, BitPay creates test invoices that no real money can pay. BitPay's Setup and Testing page explains two ways to pay one: the Simulate Payment option on the test invoice page, or a real payment with testnet coins from a testnet wallet.
- Log in to the client area with a test client account that has an unpaid invoice of at least 1.00 in your currency.
- Open the invoice, choose BitPay (or the display name you set) and click Checkout.
- Pay the test invoice on BitPay's page.
- Back in FluxBilling, check that the invoice is marked paid once BitPay reports the payment as confirmed. Then let a test invoice expire without paying and check that the FluxBilling invoice stays unpaid.
When everything works, untick Test Mode, replace the token with one from your live bitpay.com account, and save.
What your customers see
Paying an invoice
BitPay appears in the list of payment methods on the checkout page of every invoice, under the name and icon you set:

- The customer chooses BitPay, accepts your terms if you require it, and clicks Checkout.
- FluxBilling creates a BitPay invoice for the amount still due, with the FluxBilling invoice number in its description, and sends the customer to BitPay's invoice page. There the customer picks a coin and wallet and pays.
- After paying, BitPay sends the customer back to the invoices page in the client area. If the customer closes BitPay's page instead, they return to the checkout page of the invoice.
- As soon as BitPay reports the payment as confirmed, FluxBilling marks the invoice paid and runs what follows from it, such as activating the ordered service. With the default email templates, the customer receives a Payment Received email.
A crypto payment is not final the moment the customer sends it. BitPay first reports it as paid and then as confirmed once the blockchain has confirmed it; how long that takes depends on the coin and on the transaction speed set in your BitPay account (see BitPay's invoice states). FluxBilling keeps the invoice unpaid while the payment is only paid, and marks it paid when BitPay reports it confirmed or complete.
A BitPay invoice gives the customer a limited time to pay (15 minutes by BitPay's documentation). If it expires, or BitPay marks the payment invalid or declined, the FluxBilling invoice stays unpaid and the customer can start a new BitPay payment from the checkout page. FluxBilling sends no email for an expired or failed BitPay payment.
If the customer starts a second BitPay payment for the same invoice within 30 minutes of the first, while the first is still open, FluxBilling answers A payment for this invoice is already in progress with this gateway. Please complete the existing payment window or wait a few minutes before trying again.
Paying too little or too much
BitPay handles wrong amounts on its side. By BitPay's documentation, a partial payment does not complete the BitPay invoice and is refunded to the customer by BitPay, and the excess of an overpayment is refunded by BitPay too. FluxBilling only marks the invoice paid when the BitPay invoice is confirmed for the amount FluxBilling asked for.
Currencies
FluxBilling prices the BitPay invoice in the FluxBilling invoice's own currency when that currency is EUR, USD or your base currency. An invoice in any other currency is converted to your base currency for the payment. The customer then pays the equivalent in the coin they choose on BitPay's page.
Renewals and saved payment methods
BitPay cannot store a payment method: the customer sends funds from their own wallet each time, and nothing can be charged later. So BitPay is never used for automatic payment of renewals, and customers cannot save it under their payment methods. Each renewal invoice is paid by the customer through checkout like any other invoice.
Refunds
The plugin does not refund through BitPay. If you choose Via Gateway in the Refund dialog of a BitPay-paid invoice, FluxBilling answers This gateway does not support refunds.
- Refund the payment in your BitPay account. See BitPay's Refunding Payments page.
- Then open the invoice in the FluxBilling admin panel, click Refund, and choose Manual (Mark as refunded without gateway call) to record it. To keep the money as account credit instead of sending it back, choose To balance and skip the refund at BitPay.
A refund made at BitPay does not change anything in FluxBilling by itself, so always record it there.
Updating the plugin
Open Settings → Integrations → Marketplace, switch to Installed and click Check for Updates. When a new version is available, click Update to v…. Your API token and the other values on the Settings tab are kept. After an update, open the plugin's Checkout Display tab and check that the display name, description and icon are still the ones you want customers to see.
Troubleshooting
When BitPay refuses to create an invoice, the customer sees BitPay's own error message at checkout. When BitPay gives no message, the plugin's own message below is shown instead.
| Message or symptom | What to check |
|---|---|
| BitPay does not appear at checkout | The BitPay API Token is empty, Enabled is not ticked in the dialog, or the plugin is switched off under Settings → Financial → Payment Gateways. |
| Failed to create BitPay invoice, or a BitPay message about the token | The token is wrong or was removed in BitPay, it was created with Require Authentication ticked, or it belongs to the other environment: a test.bitpay.com token needs Test Mode ticked, a bitpay.com token needs it unticked. |
| The customer paid, but the invoice stays unpaid | BitPay may still be waiting for blockchain confirmations; check the invoice in your BitPay account. If BitPay shows it confirmed, BitPay could not reach your panel, for example because the panel is not on the internet over HTTPS. FluxBilling also checks open payments with BitPay by itself: first about half an hour after the payment starts, then every few hours, so a confirmed payment is picked up even if the notification never arrives. A payment still not confirmed 24 hours after it started is closed as expired. If BitPay confirms it later, FluxBilling still marks the invoice paid when BitPay's notification arrives. Only if the invoice stays unpaid (for example because BitPay cannot reach your panel) record the payment on the invoice by hand. |
| Minimum payment amount is 1 EUR (or another currency) | The amount left to pay is below 1.00, the smallest amount the plugin sends to BitPay. |
| A payment for this invoice is already in progress with this gateway… | The customer already opened a BitPay invoice for this invoice less than 30 minutes ago. They can finish that one, or try again later. |
| This gateway does not support refunds | You chose Via Gateway in the refund dialog. Refund at BitPay and record it with Manual; see Refunds above. |
Limits
- Customers always pay on BitPay's invoice page. There is no payment form inside your checkout, and you cannot preselect a coin from FluxBilling.
- No refunds through BitPay from FluxBilling, and refunds made at BitPay are not picked up automatically.
- No saved payment methods and no automatic payment of renewals.
- Coins, settlement currency and payouts are managed in your BitPay account, not in FluxBilling.
- Each FluxBilling panel connects to one BitPay account in one environment at a time: test or live.
BitPay is a trademark of BitPay, Inc. FluxBilling is not affiliated with BitPay, Inc.
