Connecting your Shopify Store to your own BTCPay Server for BTC Commerce

Connecting your Shopify Store to your own BTCPay Server for BTC Commerce


Every Shopify merchant knows the drill: payment processors that hold your money hostage, demand tax IDs, and charge fees on top of fees. Want to accept Bitcoin? Most integrations just recreate the same custodial nightmare with a crypto coat of paint. BTCPay Server is different. It's open-source software you run yourself — meaning payments go straight to your wallet, nobody asks for your documents, and the only fee is the Bitcoin network itself. This step-by-step guide shows you how to spin up BTCPay on AWS and integrate it with Shopify in an afternoon.

To connect your Shopify store to a self-hosted BTCPay Server (running on AWS) for processing Bitcoin payments at checkout, you’ll need to integrate them using BTCPay’s Shopify v2 plugin.

This setup allows customers to select Bitcoin as a payment option, complete the order in Shopify, and then pay via a BTCPay invoice on the “Thank you” page.

The process is the same whether you’re running BTCPay via Docker locally (for testing) or on AWS (e.g., EC2 for production), but ensure your BTCPay instance is publicly accessible over HTTPS with a domain name—Shopify must communicate with it.

BTCPay Server’s official Docker deployment works seamlessly on AWS (e.g., install Docker on an EC2 instance and follow BTCPay’s setup).

You’ll need root SSH admin access to your BTCPay server.

Prerequisites

  • A Shopify account with an active store (at least a Basic plan).
  • A free Shopify Partner account (register at partners.shopify.com).
  • A BTCPay store created with a wallet set up (e.g., for Bitcoin or Lightning Network).
  • If using AWS, configure security groups for ports 80/443, set up a domain (e.g., via Route 53), and enable HTTPS
    • BTCPay handles SSL with Let’s Encrypt automatically if configured.

Recipe to Brew your BTC Commerce

Have a Shopify Store

  • Of course, have at least a Basic Plan Shopify Store:

Register as a Shopify App Dev Partner

  • Set Up a Shopify Partner:

  • Visit Shopify Partner dashboard (partners.shopify.com).
  • Register a new Partner Account
    • You can use your Store Account identity
  • Provide your business location details

Create the new Shopify App for the BTCPay Server

  • Go to “App distribution” and then to “View Dev Dashboard”.

  • Click “Create app” and then “Start from Dev Dashboard”

  • Click Create app and then give your Shopify App a name (e.g., “BTCPay Server”)

  • Note the Client ID and Client Secret from the app settings.
    • These are credentials that protect your finances. Guard them privately

  • Click back to the "dev dashboard", select your app under “Apps”
  • Click Version to be able to modify the Configuration
  • Under Scopes select "Request Access", scroll down that page.

  • Under “API access requests”, grant “Allow network access in checkout and account UI extensions”.
    • If you get an error about “checkout ui extension scope”, update your partner profile with your first and last name.

  • At the bottom, click “Settings”, scroll down, click “CLI Token”, and click “Manage tokens”.
  • Generate a new token (keep defaults)
  • Copy it to your secure credentials vault (LastPass, whatever)
    • It is only visible once

Deploy a BTCPay Server to a Public Host

We use easy AWS EC2 for this. You can choose whatever hosting fits your skill and budget.

BTCPay Server on AWS EC2 (t3.medium)

Go to the AWS EC2 AMI Console and choose a Ubuntu 24.04 image.

The t3.medium (4 GB RAM, 2 vCPUs) is a solid choice for BTCPay Server—enough headroom for Bitcoin + Lightning if you want it.

Step 1: Launch EC2 Instance

Note that it is vital that you do not expose Port 443 until you have created an account for your user as your administrator. If you install with Port 443 open, bots will likely detect your new BTCPay Server before you realize it is public and will create a new account, knowing that the first account created becomes the Administrator account and can deny you administrator access. (Really!)

  1. EC2 Console → Launch Instance
  2. Configure:
    • Name: btcpay-server
    • AMI: Ubuntu 24.04 LTS
    • Instance type: t3.medium
    • Storage: 150 GB gp3 (comfortable for pruned node + Lightning)
    • Security Group - allow inbound:
      Port Source Purpose
      22 Your IP only SSH
      80 0.0.0.0/0 HTTP (LetsEncrypt, redirects to HTTPS)
      443 Your IP only HTTPS
      9735 Your IP only Lightning (if using LND)
  3. Create/select a key pair and launch
  4. Elastic IP: Go to EC2 → Elastic IPs → Allocate → Associate with your instance

Step 2: Configure DNS (Route 53)

  1. Route 53 → Hosted zones → select your domain
  2. Create record:
    • Record name: btcpay (creates btcpay.yourdomain.com)
    • Record type: A
    • Value: your Elastic IP
    • TTL: 300
  3. Click Create records

Install Docker and BTCPay Server into the EC2 Server

  • SSH into your server

ssh -i ~/.ssh/SomeAwsKeypair2026.pem ubuntu@btcpay.yourdomain.com

# now is also a great time to install fail2ban for ssh protection
# and to configure some swap space for this OS.
# practice wise cybersecurity

sudo su -
  
export BTCPAY_HOST="btcpay.yourdomain.com"
export NBITCOIN_NETWORK="mainnet"
export BTCPAYGEN_CRYPTO1="btc"
export BTCPAYGEN_LIGHTNING="lnd"
export BTCPAYGEN_ADDITIONAL_FRAGMENTS="opt-save-storage"
export BTCPAYGEN_ADDITIONAL_FRAGMENTS="$BTCPAYGEN_ADDITIONAL_FRAGMENTS;opt-add-shopify"
export BTCPAYGEN_REVERSEPROXY="nginx"
   
cd /root
git clone https://github.com/btcpayserver/btcpayserver-docker
cd btcpayserver-docker

. ./btcpay-setup.sh -i

Make it convenient to access from your Ubuntu user

mv /root/btcpayserver-docker /opt/btcpayserver-docker
chown -R ubuntu:ubuntu /opt/btcpayserver-docker
ln -s /opt/btcpayserver-docker /root/btcpayserver-docker
  
usermod -aG docker ubuntu
exit

Verify the initial BTCPay Docker Deployment

  • SSH into your server

ssh -i ~/.ssh/SomeAwsKeypair2026.pem ubuntu@btcpay.yourdomain.com

  • Verify with:
docker ps | grep shopify

(You should see a Shopify-related container running.)

Create your BTCPay Server Admin user

  • Open your web browser to https://btcpay.yourdomain.com
  • Provide a user name and password, confirm the password

  • Your account is now the administrator account (see the FAQ on ways to confirm this and to deny other visitors from creating an account)

  • Now enable HTTPS for all IPs in the EC2 Network Security Group.

Configure and Synchronize your BTCPay Server as a Node

Your BTCPay Server is a peer node on the global Bitcoin and Lightning networks. It will take it several days to synchronize for the latest, evolving blockchain. Until it has synchronized, it will not be able to look for transactions for payments from your Shopify store. The next week will be a good time to study some literature and online guides on how the Lightning Network works and the role that your BTCPay Server will play.

For more thorough advice on getting started with BTCPay Server, see:

Create a new BTCPay Server Store

Your Shopify Store will collaborate with a BTCPay Server Store to conduct BTC commerce. You have a Shopify Store, now create the BTCPay Server Store for that.

  • Give it a name that is similar to your Shopify Store name
  • Accept USD as the currency
  • Keep the recommended Kraken price source
  • Click Create Store

Install the BTCPay Server Shopify Plugin v2

With the new BTCPay Server Store created, now you can add the BTCPay Server Shopify Plugin (v2)

Login and return to the BTCPay Server Store you just created.

  • In your BTCPay dashboard, go to “Manage Plugins”.
  • Install “BTCPay Server Shopify plugin v2” (by btcpayserver).

  • Restart BTCPay when prompted.

Configure the Shopify v2 Plugin in BTCPay Server

  • Select your BTCPay store.
  • Go to “Shopify v2” in the sidebar.

  • Enter the Client ID and Client Secret from the Shopify Partner Site, then save.

  • In “Deploy the app”, enter the App name and CLI Token from the Shopify Partner site.

Click “Deploy App” and wait for confirmation in the console output.

Install the App on Your Shopify Store

  • In Shopify Partner portal, select your app, “Choose Distribution”, and “Custom distribution”

  • Enter your store URL (e.g., your-store.myshopify.com)

  • Generate the install link, copy it, and open in a browser.

  • Log in to Shopify if needed, then click “Install”.

  • Confirm success (green checkmark in BTCPay plugin settings).

Customize Shopify’s “Thank You” Page

  • In Shopify Admin: click Settings, then Checkout, and there, Customize.
  • Switch to the “Thank you” page view in the Theme page
  • Click an Add Block icon
  • Click the Apps icon (left sidebar).
  • Add “BTCPay Checkout” by clicking (+) and selecting it (place it near the “Order details section”).
  • Save.

Add a Custom Payment Method in Shopify

  1. From the Shopify Admin: click Settings, then Payments, and then “Manual payment methods”.
  2. Click “+” > “Create custom payment method”.
  3. Name it something like “Pay with Bitcoin (BTCPay Server)”
    (it must include “bitcoin”, “btcpayserver”, “btcpay server”, or “btc”).
  4. Optionally, add details: “The ‘Complete payment’ button for Bitcoin will appear on the Thank You page.”
  5. Click Activate.

How It Works for Customers

  • At checkout, they select the custom Bitcoin option and complete the order.
  • On the “Thank you” page, they click “Complete payment” to open the BTCPay invoice.

  • Payment confirms in BTCPay, updating the Shopify order status automatically.

Troubleshooting Tips

  • Ensure your BTCPay URL is HTTPS-secured and publicly reachable (test with curl or browser).
  • For AWS: Use an Elastic IP for static addressing; configure the inbound rules for HTTP, HTTPS, SSH, and Lightning.
  • Avoid using the old Shopify v1 integration
  • If payments don’t process, check BTCPay logs (docker logs) and ensure API permissions.
  • For updates, run ./btcpay-update.sh on your server, generate a new CLI token, and redeploy the app.

This integration of Shopify and BTCPay Server is based on non-custodial Bitcoin ownership and exchange - there are no fees or middlemen beyond network transaction costs. There is also no guardian to right wrongs. Test your integration and your purchases with small amounts first.

Return to Collection