What This Plugin Does and Does Not Do
What it does do:
Records customer payments as deposits in Quickbooks
Separates revenue from sales tax, and records revenue separately from sales tax
Optionally emails very simple text receipts to the customer. If you want a fancy receipt, you should send from your merchant software or CMS instead.
What it does not do:
Automatically calculate sales tax. There are hundreds of different sales tax jurisdictions in the USA alone, each with its own rates and definitions. BTCPay is not sales tax software. It simply takes the revenue/sales tax breakdown from your e-commerce solution and accepts it as correct. If you need a software solution that automatically tracks rates for all of the US jursdictions, you need to integrate a solution like TaxJar or Avalara into your e-commerce site. If Avalara or TaxJar are calculating your sales tax on your e-commerce site, you can then pass the revenue/sales tax breakdown to this plugin and it will work correctly.
Integrate the Quickbooks Sales Tax Module. This plugin records all revenue to an Income account on your P&L called "BTCPay Sales." It records all sales tax collected into a Liability account on your balance sheet called "Sales Tax from BTCPay." When you pay your sales tax each month, you'd post a regular check to "Sales Tax from BTCPay." This is a very straightforward solution. You would not record sales tax in Quickbooks through the sales tax module, because as referenced above BTCPay does not store jurisdiction information and therefore cannot integrate native Quickbooks sales tax. If you need direct integration into the Quickbooks Sales Tax module, you should skip using this plugin and instead integrate your e-commerce solution directly into the Quickbooks API.
If you collect sales tax, you must make use of the new
taxIncluded invoice field within BTCPay. You may need to update BTCPay if you're using an older version.
price is inclusive of tax. So if you're creating an invoice for $100 in a jursidiction with 7% sales tax, you would pass BTCPay a
price of $107 (not $100) and
taxIncluded of $7.
All payments made through BTCPay will be recorded in QBO in an "Other Current Asset" account called "BTCPay-Bitcoin." They are recorded at USD value as of the date the invoice was paid. This is not a bug; it is intentional behavior. The USD value on the payment date is the amount of taxable income recognized as well as the tax basis for a future sale of BTC under US Tax law, so the BTC is recorded in QBO accordingly. The information herein is educational only and is not tax advice; consult your tax professional.
Payments will not record in QBO until the invoice status in BTCPay is "confirmed." Payments are considered "confirmed" based on your BTCPay settings. The default is one on-chain confirmation.
You MUST set the notificationUrl on all invoices you create to
btcpay.example.com with the domain where your BTCPay is hosted) in order for this plugin to record payments. If you need the IPN to be forwarded from the plugin to another merchant solution, during the plugin setup you can select a forwarding URL.
Instructions assume that you are using the Dockerized BTCPay Server, which would be the case if you originally used the one-click install through LunaNode.
You only need to activate the plugin once, as going forward after activation the plugin should update automatically when you update BTCPay.
To activate, log into your LunaNode or other VPS via SSH (click here if you forgot how) and run the commands below. Don't forget the trailing hyphen in the first command, as it's important.
# Log in as root and load environment variables of BTCPayServer sudo su - # go into the BTCPay-Docker directory cd btcpayserver-docker # Add this plugin docker fragment export BTCPAYGEN_ADDITIONAL_FRAGMENTS="$BTCPAYGEN_ADDITIONAL_FRAGMENTS;opt-add-btcqbo" # Save . btcpay-setup.sh -i
After activation, you can access the plugin directly from within BTCPay under Server Settings/Services, or alternatively at
https://btcpay.example.com/btcqbo, replacing btcpay.example.com with the domain where your BTCPay instance is hosted. On the plugin welcome screen, there will be buttons for:
- Entering Intuit API Keys
- Syncing the plugin to QBO
- Syncing the plugin to BTCPay
Entering Intuit API Keys
You need API keys from Intuit to sync to Quickbooks Online.
Head to https://developer.intuit.com and log in using the same login you normally use for Quickbooks Online. Your account will then be granted developer privileges.
After logging in, click on "My Apps" and create a new app. Call the app "BTCQBO". Whenever Intuit asks, you need access to the Accounting API (not the Payments API).
On the Intuit Developer site, underneath your Intuit "production" keys, add
https://btcpay.example.com/btcqbo/qbologgedas a redirect URI, replacing
btcpay.example.comwith the domain where your BTCPay instance is hosted. Ensure you're doing this in the "production" (not sandbox) area of the page.
From the plugin welcome screen, click the button to enter your Intuit API Keys. Enter your Quickbooks Client ID and Quickbooks Client Secret obtained from the Intuit Developer site above. Be sure to use the "Production" rather than "Sandbox" keys (unless you are in fact running on a sandbox test company).
After entering your Intuit API keys into the plugin, you'll be automatically redirected to sync the plugin to QBO. (If you need to resync later without updating your API keys, from the plugin welcome screen, you can hit the button to sync QBO.) Follow the on-screen instructions to sync to Inuit; you'll need your QBO username and password. You can repeat this step at any time in the future if you become unsynced from Intuit for any reason.
On this screen you can also set a forwarding URL for IPN payment notifications. All IPNs must come to the plugin first, so be sure to set the
notificationUrl on all invoices to
btcpay.example.com with the domain where your BTCPay is hosted). The URL you enter on this screen will receive IPNs after the BTC-QBO plugin records the payments in Quickbooks.
From the plugin welcome screen, hit the button to sync BTCPay. Click on the link provided to obtain a pairing code from your BTCPay Server instance. Then enter the pairing code in the plugin, and submit.
Versions 0.3.30 and higher of the plugin allow automatic emailing of customer receipts. To set this up, click the email setup button on the plugin welcome screen. You'll need to enter your SMTP server settings. If you enter a test email recipient, it will test the connection and send a test email.
If you don't know what an SMTP server is, that's OK! Your email provider almost definitely provides SMTP access for free. If it doesn't, you can always sign up for a free account with a provider that does (Gmail, Yahoo, Outlook.com, etc).
Googling your email provider and "SMTP" will likely show you the settings. For example G-Suite (and Gmail) use smtp.gmail.com as host, and use port 587. With Google (and most providers), your email is your username. Your password is your normal password, unless you use Two Factor Authentication. If you use 2FA, you'll need to generate an application-specific password (example instructions for Google are here).
Your "send from" address is the address you want receipts to be sent from, and may be the same as your username. "Business Name" is your business name as you want it to appear on receipts. You may also choose a custom message to display at the bottom of each receipt.
For invoices created via API, receipts only work if
fullNotifications is set to
Troubleshooting (only for technical users!)
If you are a more technical user, there are some advanced troubleshooting and testing tools explained in the