Gérer les webhooks de paiement de manière sûre
Mis à jour le 2026-09-21
Une intégration de paiement est asynchrone : le client peut quitter l’écran de paiement alors que le rail externe traite encore l’opération, et un événement peut être livré de nouveau après une panne temporaire. Une intégration sûre considère un événement signé et l’état de paiement confirmé côté serveur comme des entrées métier—et non un retour navigateur comme preuve de réception de valeur.
Commencez par une référence de commande que vous contrôlez
Créez chaque paiement avec la référence de commande ou de facture de votre propre système. Conservez cette référence avec la commande pendant la livraison, le support et le rapprochement financier. Elle relie de façon stable le parcours client aux enregistrements que vous maintenez déjà.
La référence est utile, mais elle ne prouve pas à elle seule le paiement. Votre application doit toujours appliquer sa propre politique de paiement confirmé avant de livrer un bien, un accès ou une valeur. Cette politique tient compte de l’état affiché dans les surfaces authentifiées et les événements signés.
Ne prenez pas le retour navigateur pour une preuve de règlement
Le retour navigateur améliore l’expérience du payeur, mais ce n’est pas l’événement comptable. Les rails externes peuvent rester en attente après le retour du client, et le client peut fermer le navigateur avant que le paiement atteigne son état terminal. Affichez plutôt une expérience adaptée d’attente ou de réception que de livrer la commande sur le seul retour.
Pour une décision automatisée, utilisez l’état de paiement confirmé selon votre politique marchand. Vous séparez ainsi la navigation visible par le client de la décision qui modifie votre commande, droit d’accès ou enregistrement financier.
Vérifiez une livraison avant de l’appliquer
ZyndPay livre des webhooks signés. Suivez la documentation développeur pour valider la signature sur le corps brut documenté avant de faire confiance à un événement. Gardez cette vérification sur votre serveur et n’exposez ni identifiants ni éléments de vérification dans le code navigateur.
Si une livraison ne peut pas être vérifiée, elle ne doit pas modifier l’état métier. Conservez le contexte opérationnel nécessaire à une investigation sûre, en utilisant l’historique des livraisons et le parcours de support disponibles pour votre compte plutôt que de recopier des éléments sensibles dans des logs ou tickets.
Rendez le traitement des événements idempotent
Une livraison peut être relancée et un parcours de récupération peut revisiter une mise à jour déjà traitée. Concevez le consommateur pour que l’application du même résultat confirmé ne crée ni seconde livraison, ni second droit, remboursement ou mouvement comptable. Enregistrez la décision prise pour le paiement et la commande concernés avant de déclencher le travail en aval.
L’idempotence est aussi utile si votre service expire à mi-traitement. Lors de la récupération, retrouvez la décision précédente et rapprochez l’état de paiement faisant autorité au lieu de supposer qu’une tentative inconnue a échoué. C’est plus sûr qu’un flux dépendant d’une livraison unique de chaque événement.
Testez le cycle complet avant de demander l’accès live
Utilisez l’environnement de test exposé à votre compte pour exercer création de paiement, gestion des états et webhooks signés. Incluez une finalisation ordinaire, une livraison répétée, un endpoint indisponible et un client qui quitte l’écran de paiement avant de connaître le résultat.
Les résultats de test ne constituent pas un règlement réel et les capacités production restent soumises à la vérification de l’entreprise, à l’approbation du compte et aux fonctionnalités activées pour le marchand. Avant le live, vérifiez le contrat d’événement actuellement documenté et les méthodes de paiement disponibles pour ce compte au lieu de vous appuyer sur une hypothèse générique.
FAQ
- Le retour du client sur mon site prouve-t-il que le paiement est terminé ?
- Non. Le retour navigateur peut guider le client mais n’est pas une preuve de règlement faisant autorité. Appliquez votre politique de livraison à l’état de paiement confirmé côté serveur et aux événements signés.
- Que doit faire mon système s’il reçoit plusieurs fois le même webhook ?
- Traitez les livraisons de façon idempotente : une répétition d’un résultat confirmé déjà appliqué ne doit pas créer un second mouvement métier ou monétaire dans votre système.
- Puis-je utiliser les webhooks avant que l’accès live soit activé ?
- Utilisez l’environnement de test exposé à votre compte pour valider les flux de paiement et d’événement pris en charge. L’accès live reste soumis à l’approbation du compte et aux capacités activées.