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

Connecter votre boutique Shopify à votre propre BTCPay Server pour le commerce en BTC

Tout commerçant Shopify connaît la chanson : des processeurs de paiement qui retiennent votre argent en otage, exigent des numéros fiscaux et empilent les frais. Vous voulez accepter le Bitcoin ? La plupart des intégrations ne font que recréer le même cauchemar de garde des fonds, avec une couche de peinture crypto. BTCPay Server est différent. C'est un logiciel libre que vous faites tourner vous-même : les paiements vont droit dans votre portefeuille, personne ne vous demande vos papiers, et les seuls frais sont ceux du réseau Bitcoin. Ce guide pas à pas vous montre comment lancer BTCPay sur AWS et l'intégrer à Shopify en un après-midi.

Pour connecter votre boutique Shopify à un BTCPay Server auto-hébergé (sur AWS) afin de traiter les paiements en Bitcoin au moment du paiement, il faut les intégrer avec le plugin Shopify v2 de BTCPay.

Cette configuration permet aux clients de choisir le Bitcoin comme moyen de paiement, de finaliser la commande dans Shopify, puis de payer une facture BTCPay sur la page « Merci ».

La procédure est la même que vous fassiez tourner BTCPay en local avec Docker (pour tester) ou sur AWS (par exemple EC2 en production), mais votre instance BTCPay doit être accessible publiquement en HTTPS avec un nom de domaine : Shopify doit pouvoir communiquer avec elle.

Le déploiement Docker officiel de BTCPay Server fonctionne parfaitement sur AWS (par exemple, installez Docker sur une instance EC2 et suivez la procédure de BTCPay).

Il vous faut un accès administrateur SSH root à votre serveur BTCPay.

Prérequis

  • Un compte Shopify avec une boutique active (au moins le forfait Basic).
  • Un compte Shopify Partner gratuit (inscription sur partners.shopify.com).
  • Une boutique BTCPay créée avec un portefeuille configuré (par exemple pour Bitcoin ou le réseau Lightning).
  • Sur AWS, configurez les groupes de sécurité pour les ports 80/443, un domaine (par exemple via Route 53), et activez HTTPS
    • BTCPay gère automatiquement le SSL avec Let's Encrypt s'il est configuré.

La recette de votre commerce en BTC

Avoir une boutique Shopify

  • Bien sûr, ayez au moins une boutique Shopify au forfait Basic :

S'inscrire comme partenaire développeur d'applications Shopify

  • Créer un compte Shopify Partner :

  • Rendez-vous sur le tableau de bord Shopify Partner (partners.shopify.com).
  • Créez un nouveau compte partenaire
    • Vous pouvez utiliser l'identité de votre compte boutique
  • Indiquez la localisation de votre entreprise

Créer la nouvelle application Shopify pour le BTCPay Server

  • Allez dans « App distribution » puis « View Dev Dashboard ».

  • Cliquez sur « Create app » puis « Start from Dev Dashboard »

  • Cliquez sur Create app et donnez un nom à votre application Shopify (par exemple « BTCPay Server »)

  • Notez le Client ID et le Client Secret dans les paramètres de l'application.
    • Ces identifiants protègent vos finances. Gardez-les secrets.
  • Revenez au « dev dashboard » et sélectionnez votre application sous « Apps »
  • Cliquez sur Version pour pouvoir modifier la configuration
  • Sous Scopes, choisissez « Request Access » et faites défiler la page.

  • Sous « API access requests », accordez « Allow network access in checkout and account UI extensions ».
    • Si vous obtenez une erreur concernant le « checkout ui extension scope », complétez votre profil partenaire avec vos prénom et nom.

  • En bas, cliquez sur « Settings », faites défiler, cliquez sur « CLI Token » puis « Manage tokens ».
  • Générez un nouveau jeton (gardez les valeurs par défaut)
  • Copiez-le dans votre coffre d'identifiants sécurisé (LastPass ou autre)
    • Il n'est visible qu'une seule fois

Déployer un BTCPay Server sur un hébergeur public

Nous utilisons pour cela le très simple AWS EC2. Vous pouvez choisir l'hébergement qui convient à vos compétences et à votre budget.

BTCPay Server sur AWS EC2 (t3.medium)

Allez dans la console des AMI d'AWS EC2 et choisissez une image Ubuntu 24.04.

Le t3.medium (4 Go de RAM, 2 vCPU) est un bon choix pour BTCPay Server : assez de marge pour Bitcoin et Lightning si vous le souhaitez.

Étape 1 : lancer l'instance EC2

Il est vital de ne pas exposer le port 443 avant d'avoir créé votre compte d'utilisateur administrateur. Si vous installez avec le port 443 ouvert, des robots détecteront probablement votre nouveau BTCPay Server avant que vous ne réalisiez qu'il est public et créeront un compte, sachant que le premier compte créé devient l'administrateur et peut vous refuser l'accès administrateur. (Si, si !)

  1. Console EC2 → Launch Instance
  2. Configurez :
    • Name : btcpay-server
    • AMI : Ubuntu 24.04 LTS
    • Instance type : t3.medium
    • Stockage : 150 Go gp3 (confortable pour un nœud élagué + Lightning)
    • Security Group : autorisez en entrée :
      Port Source Usage
      22 Votre IP uniquement SSH
      80 0.0.0.0/0 HTTP (Let's Encrypt, redirige vers HTTPS)
      443 Votre IP uniquement HTTPS
      9735 Votre IP uniquement Lightning (si vous utilisez LND)
  3. Créez ou choisissez une paire de clés et lancez
  4. Elastic IP : allez dans EC2 → Elastic IPs → Allocate → Associate avec votre instance

Étape 2 : configurer le DNS (Route 53)

  1. Route 53 → Hosted zones → sélectionnez votre domaine
  2. Create record :
    • Record name : btcpay (crée btcpay.yourdomain.com)
    • Record type : A
    • Value : votre Elastic IP
    • TTL : 300
  3. Cliquez sur Create records

Installer Docker et BTCPay Server sur le serveur EC2

  • Connectez-vous en SSH à votre serveur

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

# c'est aussi le bon moment pour installer fail2ban (protection SSH)
# et configurer un peu d'espace d'échange pour ce système.
# pratiquez une cybersécurité avisée

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

Rendre l'accès pratique depuis votre utilisateur Ubuntu

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

Vérifier le déploiement Docker initial de BTCPay

  • Connectez-vous en SSH à votre serveur

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

  • Vérifiez avec :
docker ps | grep shopify

(Vous devriez voir tourner un conteneur lié à Shopify.)

Créer l'utilisateur administrateur de votre BTCPay Server

  • Ouvrez votre navigateur sur https://btcpay.yourdomain.com
  • Saisissez un nom d'utilisateur et un mot de passe, puis confirmez le mot de passe

  • Votre compte est désormais le compte administrateur (voir la FAQ pour le vérifier et pour empêcher d'autres visiteurs de créer un compte)
  • Ouvrez maintenant le HTTPS à toutes les IP dans le groupe de sécurité réseau EC2.

Configurer et synchroniser votre BTCPay Server comme nœud

Votre BTCPay Server est un nœud pair des réseaux mondiaux Bitcoin et Lightning. Il lui faudra plusieurs jours pour se synchroniser sur la blockchain, qui évolue sans cesse. Tant qu'il n'est pas synchronisé, il ne pourra pas rechercher les transactions correspondant aux paiements de votre boutique Shopify. La semaine qui vient sera un bon moment pour étudier un peu de littérature et des guides en ligne sur le fonctionnement du réseau Lightning et le rôle que jouera votre BTCPay Server.

Pour des conseils plus complets sur les débuts avec BTCPay Server (en anglais), voir :

Créer une nouvelle boutique BTCPay Server

Votre boutique Shopify collaborera avec une boutique BTCPay Server pour mener le commerce en BTC. Vous avez une boutique Shopify : créez maintenant la boutique BTCPay Server correspondante.

  • Donnez-lui un nom proche de celui de votre boutique Shopify
  • Acceptez l'USD comme devise
  • Gardez la source de prix recommandée, Kraken
  • Cliquez sur Create Store

Installer le plugin Shopify v2 de BTCPay Server

La nouvelle boutique BTCPay Server créée, vous pouvez ajouter le plugin Shopify (v2) de BTCPay Server.

Connectez-vous et revenez à la boutique BTCPay Server que vous venez de créer.

  • Dans votre tableau de bord BTCPay, allez dans « Manage Plugins ».
  • Installez « BTCPay Server Shopify plugin v2 » (par btcpayserver).

  • Redémarrez BTCPay quand on vous le demande.

Configurer le plugin Shopify v2 dans BTCPay Server

  • Sélectionnez votre boutique BTCPay.
  • Allez dans « Shopify v2 » dans la barre latérale.

  • Saisissez le Client ID et le Client Secret du site Shopify Partner, puis enregistrez.

  • Dans « Deploy the app », saisissez le nom de l'application et le CLI Token du site Shopify Partner.

Cliquez sur « Deploy App » et attendez la confirmation dans la sortie de la console.

Installer l'application sur votre boutique Shopify

  • Dans le portail Shopify Partner, sélectionnez votre application, « Choose Distribution », puis « Custom distribution »

  • Saisissez l'URL de votre boutique (par exemple your-store.myshopify.com)

  • Générez le lien d'installation, copiez-le et ouvrez-le dans un navigateur.

  • Connectez-vous à Shopify si besoin, puis cliquez sur « Install ».

  • Vérifiez la réussite (coche verte dans les paramètres du plugin BTCPay).

Personnaliser la page « Merci » de Shopify

  • Dans l'administration Shopify : cliquez sur Paramètres, puis Paiement, et là, Personnaliser.
  • Passez à la vue de la page « Merci » dans la page du thème
  • Cliquez sur une icône d'ajout de bloc
  • Cliquez sur l'icône Applications (barre latérale gauche).
  • Ajoutez « BTCPay Checkout » en cliquant sur (+) et en le sélectionnant (placez-le près de la section « Détails de la commande »).
  • Enregistrez.

Ajouter un moyen de paiement personnalisé dans Shopify

  1. Depuis l'administration Shopify : cliquez sur Paramètres, puis Paiements, puis « Moyens de paiement manuels ».
  2. Cliquez sur « + » > « Créer un moyen de paiement personnalisé ».
  3. Nommez-le par exemple « Pay with Bitcoin (BTCPay Server) »
    (le nom doit contenir « bitcoin », « btcpayserver », « btcpay server » ou « btc »).
  4. Ajoutez éventuellement des détails : « Le bouton ‘Finaliser le paiement’ pour le Bitcoin apparaîtra sur la page Merci. »
  5. Cliquez sur Activer.

Comment cela se passe pour les clients

  • Au paiement, ils choisissent l'option Bitcoin personnalisée et finalisent la commande.
  • Sur la page « Merci », ils cliquent sur « Finaliser le paiement » pour ouvrir la facture BTCPay.

  • Le paiement est confirmé dans BTCPay, ce qui met automatiquement à jour le statut de la commande Shopify.

Conseils de dépannage

  • Assurez-vous que l'URL de votre BTCPay est sécurisée en HTTPS et joignable publiquement (testez avec curl ou un navigateur).
  • Sur AWS : utilisez une Elastic IP pour une adresse fixe ; configurez les règles d'entrée pour HTTP, HTTPS, SSH et Lightning.
  • Évitez l'ancienne intégration Shopify v1
  • Si les paiements ne passent pas, consultez les journaux de BTCPay (docker logs) et vérifiez les permissions de l'API.
  • Pour les mises à jour, lancez ./btcpay-update.sh sur votre serveur, générez un nouveau CLI Token et redéployez l'application.

Cette intégration de Shopify et de BTCPay Server repose sur la possession et l'échange de bitcoin sans dépositaire : pas de frais ni d'intermédiaires au-delà du coût des transactions sur le réseau. Il n'y a pas non plus de tuteur pour réparer les erreurs. Testez d'abord votre intégration et vos achats avec de petits montants.

Retour au blog