Checklist de mise en production d’une intégration de paiement Shopify

Une intégration de paiement peut réussir toutes les démonstrations et échouer dès son premier vrai client : un paiement confirmé seulement dans le navigateur, un webhook traité deux fois, un remboursement qui désynchronise Shopify et le prestataire. Cette checklist rassemble les vérifications à faire avant qu’une intégration n’encaisse de l’argent réel. Chaque point doit recevoir un « oui » clair avant la mise en production.

Pour qui. Les marchands qui changent ou ajoutent un prestataire de paiement, et les développeurs ou agences qui livrent l’intégration. Les points marqués (sur mesure) concernent un prestataire connecté par une intégration sur mesure (par exemple lorsqu’il n’est pas disponible dans le checkout Shopify) ; un prestataire installé depuis les paramètres de paiement de Shopify en gère la plupart pour vous.

1. Compte prestataire et circuit de l’argent

• Le compte de production est entièrement vérifié chez le prestataire (identité, documents de l’entreprise), pas seulement créé.
• Le compte bancaire de versement est vérifié, et vous connaissez le calendrier des versements et une éventuelle réserve appliquée par le prestataire.
• Chaque pays, devise, réseau de cartes et moyen de paiement local dont vous avez besoin est activé sur le compte de production, pas seulement dans le bac à sable.
• Le libellé de relevé (le nom affiché sur le relevé bancaire du client) est reconnaissable par vos clients.
• Le coût total est compris : frais du prestataire, conversion de devises, frais de rétrofacturation et, si vous n’utilisez pas Shopify Payments, les frais de transaction supplémentaires que Shopify peut appliquer selon votre forfait.

2. Identifiants et accès

• Les clés d’API de production restent sur un serveur, dans des variables d’environnement ou un gestionnaire de secrets. Jamais dans le thème, dans le JavaScript public ni dans un dépôt de code.
• Les clés de test et de production sont séparées par environnement : la boutique en production ne peut pas tourner avec des clés de test, ni l’inverse.
• Chaque clé a les permissions minimales dont elle a besoin, y compris les autorisations d’un éventuel accès à l’API Admin de Shopify.
• Les secrets de signature des webhooks sont stockés côté serveur, avec une procédure écrite pour les renouveler.
• Les tableaux de bord du prestataire et de Shopify sont protégés par une authentification en deux étapes, et l’accès est réservé aux personnes qui en ont besoin.
• Les données de carte ne passent jamais par vos serveurs : le client les saisit sur la page de paiement ou les champs hébergés du prestataire. Votre périmètre PCI DSS reste ainsi aussi réduit que possible.

3. Parcours de paiement (sur mesure)

• Le montant et la devise sont calculés sur le serveur à partir de la commande Shopify, jamais repris du navigateur.
• Chaque commande a une référence de paiement unique, enregistrée des deux côtés : l’identifiant de transaction du prestataire sur la commande Shopify, l’identifiant de commande Shopify dans les métadonnées du prestataire.
• La création d’un paiement est idempotente : un double clic ou une requête relancée ne peut pas débiter deux fois la même commande. Utilisez la clé d’idempotence du prestataire lorsqu’il en propose une.
• Le paiement est confirmé de serveur à serveur, par le webhook du prestataire ou une vérification de statut via son API. Jamais par la seule redirection du navigateur : les clients ferment l’onglet avant de revenir, et n’importe qui peut ouvrir une URL de retour.
• Les pages de succès, d’échec et d’annulation mènent chacune à un endroit cohérent, et aucune ne marque à elle seule la commande comme payée.
• L’authentification forte est testée. Dans l’Union européenne et au Royaume-Uni, la plupart des paiements par carte en ligne passent par 3-D Secure : testez une authentification réussie, une échouée et une abandonnée par le client.
• Une session de paiement expirée a une issue définie pour la commande : annulation, relance, ou attente pendant une durée fixée.

4. Webhooks et état de la commande

• La signature de chaque webhook est vérifiée sur le corps brut de la requête avant toute autre lecture. Notre guide Webhook ou API explique pourquoi, et le dépôt open source shopify-webhook-patterns le montre en Node.js et en Python.
• Le point de réception répond 2xx en quelques secondes et fait le travail ensuite, dans une file d’attente. Pour ses propres webhooks, Shopify attend une réponse en moins de cinq secondes.
• Les doublons sont absorbés à deux niveaux : les livraisons répétées sont ignorées grâce à l’identifiant de livraison, et une commande ne peut être marquée payée, expédiée ou facturée qu’une seule fois. Sur Shopify, la mutation orderMarkAsPaid ne s’applique qu’à une commande qui a encore un solde dû et n’est pas déjà payée, ce qui aide, mais votre propre logique doit quand même vérifier avant d’agir.
• Des événements arrivés dans le désordre ne peuvent pas fausser une commande : un événement de remboursement reçu avant l’événement de paiement ne doit pas laisser la commande dans un mauvais état.
• Les abonnements aux webhooks Shopify sont surveillés. Après 8 échecs de livraison consécutifs, un abonnement créé via l’API Admin est supprimé et Shopify prévient par e-mail l’adresse de contact développeur d’urgence de l’application : assurez-vous que quelqu’un lit cette boîte.
• Une réconciliation planifiée compare les transactions du prestataire aux commandes Shopify et alerte en cas d’écart : un paiement sans commande, une commande payée sans transaction, un montant différent. La documentation de Shopify présente elle-même ce type de tâche comme une pratique courante pour récupérer les données qu’un webhook aurait manquées.

5. La commande Shopify

• La commande n’est marquée payée qu’après un paiement confirmé, et son statut financier, ses transactions et le nom du moyen de paiement sont corrects dans l’administration.
• Le comportement du stock est décidé : réservé à la création de la commande ou au paiement, et testé pour un paiement abandonné.
• Les notifications client partent une seule fois, au bon moment : pas d’e-mail « commande confirmée » avant la confirmation du paiement si votre parcours crée la commande d’abord.
• Les remboursements totaux et partiels fonctionnent de bout en bout : l’argent est rendu par le prestataire et le remboursement est enregistré dans Shopify, et l’équipe sait par quel côté commencer.
• Les paiements annulés ou expirés ne laissent aucune commande en attente oubliée : chacune est annulée, relancée ou revue.

6. La matrice de tests

Passez chaque scénario d’abord dans le bac à sable du prestataire, puis terminez par un vrai paiement de faible montant avec votre propre carte, et remboursez-le.

Scénario	Résultat attendu
Paiement réussi	Commande payée une fois, un seul e-mail de confirmation, stock mis à jour
Carte refusée	Commande non payée ; le client peut réessayer ou choisir un autre moyen
3-D Secure : réussi, échoué, abandonné	Payé uniquement dans le premier cas ; un message clair dans les deux autres
Le client paie puis ferme l’onglet avant la redirection	Commande quand même marquée payée, par le webhook ou la vérification de statut
Double clic sur le bouton de paiement	Un seul débit
Même webhook livré deux fois	Traité une seule fois
Point de réception des webhooks indisponible dix minutes	Les relances ou la réconciliation remettent la commande à jour
L’API du prestataire ne répond pas à temps	Message clair au client, aucun double débit en cas de nouvel essai
Remboursement total, puis remboursement partiel sur une autre commande	Le prestataire et Shopify concordent sur les montants et les statuts
Chaque marché et chaque devise où vous vendez	Bonne devise, bon montant, bons moyens de paiement
Navigateurs mobiles (Safari sur iOS, Chrome sur Android)	Redirection et retour fonctionnent, y compris après un passage par l’application bancaire

7. Surveillance et procédure d’incident

• Une ligne de journal par tentative de paiement et par webhook, avec l’identifiant de commande, la référence du prestataire, le statut et un éventuel code d’erreur. Aucune donnée de carte ni aucun secret dans les journaux.
• Des alertes sur les webhooks en échec, sur les écarts de réconciliation et sur une hausse soudaine des refus.
• Une procédure courte : où regarder quand un client dit « j’ai payé mais je n’ai pas de commande », qui contacte le prestataire, et comment désactiver rapidement le moyen de paiement. Notre guide pourquoi des paiements sont refusés sur Shopify couvre les premières étapes du diagnostic.
• Une solution de repli : un autre moyen de paiement peut rester disponible si l’intégration doit être désactivée.

8. Clients et comptabilité

• Les moyens de paiement et logos de cartes affichés au checkout correspondent à ce qui est réellement accepté.
• Les messages d’erreur indiquent au client quoi faire : réessayer, utiliser une autre carte ou vous contacter.
• Les conditions générales de vente et la politique de remboursement sont publiées et faciles à trouver depuis le checkout.
• Les versements, frais et remboursements peuvent être rapprochés des commandes, par exemple en exportant les identifiants de transaction du prestataire, et votre comptable sait où les trouver.

Questions fréquentes

Faut-il tout cela pour un prestataire proposé dans les paramètres de paiement de Shopify ?

Non. Les sections 3 et 4 sont en grande partie gérées par l’application de paiement du prestataire. Gardez les sections 1 et 2 pour les comptes et les accès, les vérifications de remboursement de la section 5, les lignes utiles de la matrice de tests, et les sections 7 et 8. Pour comparer les prestataires d’abord, lisez comment choisir un prestataire de paiement Shopify.

Puis-je marquer une commande payée quand le client arrive sur la page de succès ?

Non. Considérez la page de retour comme un message pour le client. Le paiement n’est confirmé que lorsque votre serveur reçoit le webhook signé du prestataire ou lit le statut du paiement via son API.

Est-ce une checklist juridique ou de conformité PCI ?

Non. Elle couvre les vérifications techniques et opérationnelles. Votre prestataire de paiement et, si nécessaire, un conseil qualifié confirment vos obligations de conformité pour votre pays et votre activité.

Vous lancez un nouveau dispositif de paiement ? Voir nos services d’intégration de paiement, dont notre intégration Shopify × SumUp. Pour les webhooks et la synchronisation avec vos autres outils, voir intégration API et automatisation, ou décrivez votre projet.