Intégration d'une passerelle de paiement : ce qu'il faut réussir
L'intégration des paiements paraît simple dans un tutoriel et se révèle impitoyable en production, car chaque cas d'échec implique soit un client qui a payé et n'a rien reçu, soit un client qui a reçu quelque chose sans payer.
Ce guide couvre le fonctionnement du parcours, la décision de conception qui évite l'essentiel des problèmes, et les cas à tester délibérément avant le lancement.
Comment le parcours fonctionne réellement#
Quel que soit le prestataire, la forme est la même : votre serveur crée une intention de paiement, le client s'authentifie auprès du prestataire, et le prestataire vous communique le résultat — deux fois, par deux voies différentes.
- Votre serveur crée une intention de paiement avec un montant, une devise et une référence à votre commande.
- Le client saisit ses informations de carte dans un champ ou une page hébergés, de sorte que les données ne touchent jamais votre serveur.
- Une authentification forte peut être requise, ajoutant une étape que le client doit accomplir.
- Le prestataire renvoie le client vers votre site avec un résultat.
- Séparément, le prestataire envoie un webhook de serveur à serveur avec le résultat faisant foi.
- Votre système met à jour la commande — à partir du webhook, pas de la redirection.
- L'expédition n'est déclenchée qu'après confirmation du paiement.
Les étapes 4 et 5 constituent toute la conception. La redirection est une indication de ce qui s'est passé ; le webhook est le fait.
Pourquoi les webhooks doivent faire foi#
Le navigateur du client est un narrateur peu fiable. Il peut se fermer pendant la redirection, perdre la connexion, ou être manipulé. Si l'état de votre commande dépend du retour du client sur votre page de confirmation, vous aurez des commandes payées jamais enregistrées.
- Ne mettez à jour l'état de la commande qu'à partir de webhooks vérifiés ; traitez la redirection comme un simple message à l'utilisateur.
- Vérifiez les signatures des webhooks. Un point d'entrée non authentifié qui marque des commandes comme payées est exactement aussi grave que cela en a l'air.
- Rendez le traitement des webhooks idempotent : les prestataires réessaient, et des doublons arriveront.
- Répondez vite et traitez de façon asynchrone ; les points d'entrée lents sont réessayés puis finalement désactivés.
- Journalisez chaque charge utile de webhook. Les litiges de paiement se règlent avec des journaux.
- Gérez les événements dans le désordre, car ils peuvent arriver ainsi et ils le feront.
Les cas d'échec à tester#
Chacun de ceux-ci se produit en production. Testez-les délibérément, avec les cartes de test du prestataire, avant le lancement.
| Cas | Ce qui doit se passer |
|---|---|
| Le client ferme l'onglet après avoir payé | Le webhook termine tout de même la commande ; l'e-mail de confirmation part |
| Carte refusée | Message clair, panier conservé, nouvelle tentative possible |
| Authentification forte échouée | Commande non confirmée ; on dit au client quoi faire ensuite |
| Webhook en double | Commande mise à jour une fois, pas deux ; pas de seconde expédition |
| Le webhook arrive avant la redirection | La page de confirmation reflète la commande déjà terminée |
| Remboursement partiel | Les totaux de commande et tout export comptable restent cohérents |
| Rupture de stock entre le paiement et l'expédition | Processus défini : remboursement, réassort ou substitution |
| Arrondi de devise | Le montant débité correspond exactement au total affiché |
Périmètre, conformité et argent#
Quelques décisions déterminent la charge réglementaire que vous assumez et la part de la transaction que vous gardez.
- Ne stockez jamais de numéros de carte. Utilisez des champs ou une page hébergés pour que les données de carte n'atteignent jamais votre serveur ; le périmètre PCI reste ainsi minimal.
- Comprenez la structure des frais. Pourcentage plus frais fixes, plus conversion de devise, plus frais d'impayés. Le pourcentage affiché n'est pas le coût.
- Vérifiez le délai de versement. Le nombre de jours avant règlement affecte la trésorerie plus qu'un petit écart de taux.
- Confirmez que le circuit de remboursement fonctionne de bout en bout avant le lancement, remboursements partiels compris.
- Proposez les moyens locaux que votre marché utilise vraiment : la carte n'est pas la norme partout, et manquer le moyen local dominant coûte des conversions.
- Gardez un second prestataire prêt si les paiements sont critiques. Les pannes arrivent et arrêtent totalement le chiffre d'affaires.
Questions fréquentes
Tunnel hébergé ou formulaire intégré ?
Le tunnel hébergé est plus simple, garde le périmètre PCI au minimum et est maintenu par le prestataire : pour la plupart des boutiques c'est le bon choix par défaut. Les champs intégrés gardent le client sur votre domaine et donnent plus de maîtrise de l'expérience, au prix de plus de code et de plus de responsabilité. Les deux tiennent les données de carte hors de votre serveur, ce qui est la partie qui compte.
Que se passe-t-il si mon point d'entrée webhook tombe ?
Les prestataires réessaient avec un délai croissant, typiquement pendant des heures ou des jours, donc une courte panne se rattrape d'elle-même. Une longue panne signifie des commandes non confirmées : supervisez le point d'entrée et alertez en cas d'échec. Construisez aussi un rapprochement quotidien entre les transactions du prestataire et vos commandes : il rattrape tout ce que les réessais ont manqué.
Dois-je gérer l'authentification forte du client ?
Si vous vendez à des clients dans des régions qui l'exigent, oui, et les SDK modernes des prestataires prennent en charge l'essentiel du parcours. Ce que vous devez gérer, c'est le résultat : une commande en attente d'authentification n'est pas payée, et la traiter comme payée signifie expédier des marchandises que vous n'avez jamais encaissées.
Comment tester les paiements en sécurité ?
Chaque prestataire a un mode test avec des cartes qui déclenchent des résultats précis : refus, authentification requise, fraude. Parcourez la liste complète, cas pénibles du tableau ci-dessus compris. Puis faites une petite transaction réelle en production avant le lancement et remboursez-la, car le mode test ne sollicite ni vos clés réelles ni votre URL de webhook réelle.
intégration passerelle de paiementpaiements e-commercewebhooksconformité pcidéveloppement tunnel de commandepaiements en ligne
