# Accept Bitcoin in Shopify with BTCPay Server

Introducing BTCPay Server for Shopify open-source payment gateway that enables you accept bitcoin payments directly on your website or stores from customers with no fee.

Our integration with Shopify allows you connect your self-hosted BTCPay Server with your Shopify store (opens new window), enabling you accept Bitcoin payments swiftly and securely.

# What BTCPay offers:

Zero fees: Enjoy a payment gateway with no fees. Yes, You saw that right. Zero fees!
Direct payment, No middlemen or KYC: Say goodbye to intermediaries and tedious paperwork, and get your money directly in your wallet
Fully automated system: BTCPay takes care of payments, invoice management and refunds automatically.
Display Bitcoin QR code at checkout: Enhance customer experience with an easy and secure payment option.
Self-hosted infrastructure: Maintain full control over your payment gateway.
Lightning Network integrated: Instant, fast and low cost payments and payouts
Easy CSV exports
Versatile plugin system: Extend functionality according to your needs
Point-of-sale integration Accept payments in your physical shops
Multilingual ready: Serve a global audience right out of the box.
Community-driven support: Get responsive assistance from our dedicated community (Mattermost (opens new window) or Telegram (opens new window)).

# Prerequisites:

Before diving into the setup process, ensure you have the following:

Shopify account
BTCPay Server - self-hosted or run by a third-party host v2.0.0 or later.
Created BTCPay Server store with wallet set up

WARNING

Shopify might give false flags on deprecated API calls. The most likely answer we could find, due to a change by Shopify to specific fields of the Order resource and is assumed to get used in BTCPay Server. Find more details here (opens new window)

# Setting up BTCPay Server with Shopify

# Create an app and get API credentials from Shopify

In Shopify, click on Apps > in the left sidebar
On the modal popped up, click on App and sales channel settings
From the page displayed, click on Develop apps button
If prompted, click on Allow custom app development
Create an app and name it, e.g. BTCPay Server, click on Create App
On the app page, in Overview tab, click on the Configure Admin API scopes
In the filter admin access scopes type in Orders
In Orders enable read_orders and write_orders and then click Save
Click on the "API credentials" tab, and then click on the Install App in the top right corner and when pop-up window appears click Install
Reveal Admin API access token and copy it (and note it down somewhere safe)
Also copy the API key and API Secret and note it down somewhere safe
Shopify app setup is now complete

# Set up a custom payment method in Shopify

Back to Shopify, on the home page, click on Settings >> Payments in the left sidebar, scroll down to "Manual payment methods", click on (+) Manual payment method and select Create custom payment method on the dropdown.
In Custom payment method name fill in Bitcoin with BTCPay Server (also see TIP box below), optionally you can fill in other fields, but it's not required. However you would need to inform your customers that payment with Bitcoin comes on the next screen after checkout on the "Thank you" page. Ideally you would inform your customers in the Additional details field. The payment option can have a delay between 2 - 10 seconds on the "Thank you" page, before it is displayed so this also needs to be communicated with the customers. Suggested text: Please note that the Bitcoin payment option will be displayed on the "Thank you" page after a few seconds. If it does not show up after 5-10 seconds please contact our support.
Hit Activate and you've set up Shopify and BTCPay Server payment method successfully.

TIP

"Custom Payment method name" must contain at least one of the following words (case-insensitive): bitcoin, btcpayserver, btcpay server or btc to work.

# Install BTCPay Server Shopify plugin

In your BTCPay Server, go to your plugins, find and install Shopify plugin. Once done, on the left sidebar click on Shopify
In the first field, Shopify Store URL enter the subdomain of your Shopify store e.g. SOME_ID.myshopify.com then enter SOME_ID
In the second field, API key paste the API key from Shopify - see steps above.
Do the same for the third field, paste the API Secret from Shopify and paste in the API Secret field.
In the last field, Admin API access token paste the Admin API access token
You can decide to edit the payment method description text. This basically defines the text that the user sees when the invoice loads on shopify.
Click Save on BTCPay Shopify settings page
BTCPay then validates the credentials, and once validated, creates an create order webhook, and finally saves the credentials.

# Install BTCPay-Shopify application on Shopify

The second piece of this installation guide is setting up the BTCPay-Shopify app. You can choose to self-host your own BTCPay-Shopify app or use the app we submitted to the Shopify App Store.

# Using BTCPay-Shopify from Shopify App Store

WARNING

As of now, the BTCPay-Shopify app is not yet available on the Shopify App Store. We are working on getting it published.

Now we need to install the BTCPay-Shopify app. Visit the Shopify app store (opens new window) search for "BTCPay" and install the BTCPay-Shopify app.
App Setup: Step 1
Once installed, you can go to your dashboard, click on Apps > in the left sidebar, then you would see the list of installed apps, including the just installed BTCPay-Shopify app.
Select the BTCPay-Shopify app, and in settings, input your BTCPay Server URL (e.g https://btcpay.example.com) and the storeId to which your Shopify plugin is connected on your BTCPay Server instance.
In your shopify dashboard, click on Settings, which is located on the bottom of the left nav panel, select Checkout and then Customize.
In the editor change the selected page to the "Thank you" page.
Click on the Apps icon on the left panel
Click on the (+) sign on the listed "BTCPay Checkout" app and then on the "Thank you" page listed.
You will now see the extension got added to your "Thank you" page. Click save in the top right corner.
To double check all is working, click on the left arrow < next to "BTCPay Checkout" and verify it is listed in the "Order details section".

Congrats! You have successfully installed the BTCPay-Shopify app and set up the payment method on your Shopify store. You are ready to go. See also the demo checkout flow below to make sure everything works.

# Self-hosting the BTCPay-shopify app

If you are a developer or would love to have total control, you would need to create and deploy your own application.

# Requirements:

A Linux VPS instance to deploy your shopify app to
The VPS should have Docker Engine installed (opens new window)
A domain/subdomain with an DNS A-record to the IP of your VPS instance, in our example below we use the placeholder "YOUR_HOSTED_APP_URL.COM", e.g. btcpaypp.example.com
Shopify plugin installed in your BTCPay Server instance
A shopify partner account (opens new window)

# Installation instructions:

# Create a Shopify app on partner account

On Shopify Partner dashboard (opens new window), click on Apps > All Apps > Create App > Create app manually. Enter the name you want to call the app (e.g. BTCPay Server APPNAME) and click Create.
Once created displays your "Client ID" and "Client secret", which we need in a minute.
On the left sidebar click on Configuration
In the App URL field, enter the URL of your hosted app, e.g. https://YOUR_HOSTED_APP_URL.COM
In the Allowed redirection URL(s) field, enter:

https://YOUR_HOSTED_APP_URL.COM/auth/callback
https://YOUR_HOSTED_APP_URL.COM/auth/shopify/callback
https://YOUR_HOSTED_APP_URL.COM/api/auth/callback

In the fields in the "Compliance webhooks" section, enter the following: Customer data request endpoint => https://YOUR_HOSTED_APP_URL.COM/webhooks/customers/data_request Customer data erasure endpoint => https://YOUR_HOSTED_APP_URL.COM/webhooks/customers/redact Shop data erasure endpoint => https://YOUR_HOSTED_APP_URL.COM/webhooks/shop/redact Shopify-App: configuration.png
Click on Save to save the changes
On the left sidebar click on API Access
Scroll down to "Allow network access in checkout and account UI extensions" and click on Request access

TIP

When you get an error "Could not grant checkout ui extension scope 'read_checkout_external_data' when you try to enable network access, then go to your partner profile and fill out the first and last name and it will work.

# Deploy the BTCPay-Shopify app

Next on your VPS switch to root user and clone or download this repository (opens new window) and go into that directory
```
git clone https://github.com/btcpayserver/shopify-app.git shopify-app 
cd shopify-app
```
Copy .env.example to .env file, it contains the following environment variables:

DATABASE_URL => Your database connection string, keep it as is if you are using the default sqlite database
SHOPIFY_API_KEY => Represents the "Client ID" associated with the shopify app created (step 2 above)
SHOPIFY_API_SECRET => Represents the "Client Secret" associated with the shopify app (step 2 above)
SHOPIFY_APP_URL => Internal URL to reach your app, e.g. http://localhost:3000
DOMAIN => Your app domain, e.g. YOUR_HOSTED_APP_URL.COM
LETSENCRYPT_EMAIL => Your email address for Let's Encrypt

DATABASE_URL=file:/app/data/database.sqlite
SHOPIFY_APP_URL=http://localhost:3000
SHOPIFY_API_KEY=your_client_id
SHOPIFY_API_SECRET=your_client_secret
DOMAIN=YOUR_HOSTED_APP_URL.COM
LETSENCRYPT_EMAIL=johndoe@example.com

Replace the values of SHOPIFY_API_KEY, SHOPIFY_API_SECRET, DOMAIN and LETSENCRYPT_EMAIL with your values. Don't change the value of DATABASE_URL and SHOPIFY_APP_URL.

Next, rename shopify.app.toml.example to shopify.app.toml and change the following values: Change the value of client_id to your apps Client ID. (Same value as SHOPIFY_API_KEY) Change name to the name of your app (created in step 1. above) e.g. name = "BTCPay Server APPNAME" Change handle to the handle of your app (created in step 1. above, you can see it in e.g. handle = "btcpay-server-appname" Change application_url to your deployed URL. E.g. application_url = "https://YOUR_HOSTED_APP_URL.COM" Change the value of dev_store_url to your shopify store url. E.g. dev_store_url = "https://yourdevstore.myshopify.com" In the redirect_urls array, replace YOUR_HOSTED_APP_URL.COM with your deployed URL and keep the paths. E.g. https://YOUR_HOSTED_APP_URL.COM/auth/callback
Next we need to edit the file located in extensions/btcpaycheckout/src/Checkout.jsx and replace the value of the constant shopifyApplicaitonUrl which is https://YOUR_HOSTED_APP_URL.COM with your deployed URL.
Now you can run docker compose up -d and it will spin up a nodeJS, Nginx and Let's encrypt container making sure the app is reachable over SSL. It will also install all the dependencies needed for the app to run.
Once done you need to go into the container and deploy a release. docker exec -it shopify-app sh
Now run npm run deploy. It will ask you to hit a key and it will show an authentication URL.
Copy the URL into the browser and login to your partner account.
Confirm and login.
You should see a success message in the browser and the terminal should continue.
On terminal it will ask you if you want to release a new version, hit 'enter' to confirm. It will deploy and show you a success message.
Once deployed let's double-check a few things. Go back to your shopify partner app dashboard and on left sidebar click on Versions, you should see a new version with the same timestamp as to when you deployed. In your browser visit https://YOUR_HOSTED_APP_URL.COM and you should see a screen similar to this:

Congrats! You have successfully deployed the BTCPay-Shopify app, only a few steps left.

Now it is time to deploy your application to the Shopify store that you are linking to BTCPay server. On your partner account app overview, click on Choose distribution and select Custom distribution. Confirm the selection.

TIP

Please note that selecting custom distribution would mean that you can only use the application on only one Shopify store. This is irreversible. You can deploy multiple apps though if you have more than one store.

App deploy: select custom distribution App deploy: confirm custom distribution

On the next screen enter the Shopify store URL that you want to link the application to. This is typically the internal store url you see on configuring the store, e.g. something-random.myshopify.com.
Click on Generate link and you will see a link generated.
Open the link generated on a new tab. Select the store to install the app on (ensure it matches with the store you just set in the URL field).
You will see your app listed and you can now install it by clicking on Install.
Once installed, you will see the app settings page.

Go back to Using BTCPay-Shopify from Shopify App Store section above and continue from step 3.

# Demo Checkout flow after everything is set up

Feel free to join our support channel over at Mattermost (opens new window) or Telegram (opens new window) if you need help or have any further questions.

← Shopify Shopware →