Une notification de paiement valide ne doit pas déclencher deux fois la livraison d'une même commande. Les webhooks de paiement en cryptomonnaies nécessitent deux protections distinctes : vérifier qui a envoyé l'événement, puis faire en sorte que la répétition de son effet métier soit sans risque. La signature répond à la première question. L'idempotence répond à la seconde.
Ce guide s'adresse aux développeurs qui relient des achats numériques ponctuels, des licences ou des crédits de compte à Yolfi. Il présente le format natif des webhooks et une architecture applicative recommandée, pas un service d'exécution des commandes prêt à l'emploi. Pour les abonnements, l'accès dépend aussi du cycle de vie de l'abonnement ; ne réutilisez pas une règle de commande ponctuelle pour chaque renouvellement.
Pourquoi un webhook authentique peut tout de même provoquer un doublon
Un récepteur peut enregistrer un événement avec succès alors que sa réponse HTTP se perd. L'émetteur réessaie alors. Votre processus de traitement peut aussi s'arrêter après avoir accordé l'accès, mais avant d'avoir enregistré la fin du traitement. Aucune de ces situations ne signifie que le client a payé une deuxième fois.
La référence des événements webhook de Yolfi décrit une remise au moins une fois et des tentatives indépendantes pour plusieurs points de terminaison. Concevez votre système pour recevoir à nouveau le même événement, éventuellement pendant que le premier envoi est encore en cours de traitement. Ne dépendez pas d'un calendrier de nouvelles tentatives particulier et ne supposez pas que les notifications arrivent toujours dans leur ordre de création.
Distinguez bien ces trois identités :
| Identité | Ce qu'elle identifie | Contrôle recommandé |
|---|---|---|
id de l'événement signé |
Un événement du fournisseur, y compris ses envois répétés | Enregistrement unique de l'événement dans le périmètre du fournisseur, de l'organisation et de l'environnement |
| Référence de facture ou de paiement | Une tentative de paiement | Relation enregistrée avec la commande commerciale concernée |
| Référence de commande commerciale | Ce que le client doit recevoir | Action d'exécution unique pour cette commande |
La déduplication des événements ne suffit pas : deux tentatives de paiement réussies pour une même commande peuvent avoir des identifiants d'événement différents. Une protection au niveau de la commande évite d'accorder une deuxième licence ou un deuxième crédit pendant que l'encaissement supplémentaire fait l'objet d'un examen distinct.
Vérifiez la requête brute avant de vous fier à ses champs
Suivez les instructions actuelles de Yolfi sur les signatures. Les requêtes natives utilisent X-Yolfi-Signature, un HMAC-SHA256 du corps brut de la requête, encodé en Base64 et calculé avec le secret de signature de ce point de terminaison. La clé API de l'organisation n'est pas le secret du webhook.
Capturez le corps d'origine avant qu'un intergiciel JSON ne le modifie. Calculez et comparez la signature avec une fonction de comparaison en temps constant ; rejetez les signatures absentes ou mal formées sans exécuter d'action métier. Conservez les secrets de signature dans un gestionnaire de secrets ou une configuration d'environnement protégée, jamais dans les fichiers sources ni dans les journaux d'assistance.
N'analysez et ne validez le contenu qu'après la vérification. Utilisez l'id du contenu signé pour la déduplication. X-Yolfi-Event-ID est une copie pratique, pas une valeur signée séparément ; si vous l'utilisez, exigez qu'elle corresponde à l'identifiant du contenu. Associez le point de terminaison récepteur à l'organisation attendue et validez orgId lorsqu'il est présent. Les métadonnées fournies par l'utilisateur ne doivent pas déterminer les autorisations entre organisations clientes.
Une signature valide ne transforme pas un ancien envoi en nouvel envoi. Il reste nécessaire de conserver les identifiants des événements traités. La signature documentée de Yolfi ne vérifie pas la fraîcheur à partir d'un horodatage ; n'affirmez donc pas que la vérification HMAC suffit à empêcher le rejeu de requêtes.
Enregistrez d'abord, accusez réception ensuite, puis traitez de façon asynchrone
Utilisez une boîte de réception persistante : une table applicative qui enregistre un événement authentifié et son état de traitement. Insérez l'événement sous une contrainte d'unicité de la base de données, plutôt que de vérifier séparément son existence puis d'effectuer une insertion non protégée. Deux requêtes simultanées peuvent toutes deux passer cette vérification.
Renvoyez rapidement 200 OK après l'acceptation persistante, y compris lorsqu'un doublon authentifié est déjà enregistré. Si la persistance échoue, n'accusez pas réception de l'événement comme s'il avait été accepté. Une réponse rapide suivie d'une tâche en mémoire n'offre aucune persistance : un redémarrage peut faire perdre la seule copie conservée par votre application.
Un processus de traitement peut ensuite charger l'événement enregistré, valider sa relation avec la commande et appliquer la transition métier. Gardez les tâches échouées visibles avec un compteur de tentatives, la prochaine action et une personne responsable des alertes. Ne conservez que les données nécessaires du contenu dans un stockage à accès restreint ; le corps des événements peut contenir des informations sur les clients.
Conditionnez l'exécution à la confirmation et à la bonne commande
Le guide des webhooks de Yolfi désigne payment.confirmed comme le principal déclencheur de l'exécution de la commande. invoice.created signifie qu'une facture a été créée, pas que le client a payé. Une redirection du navigateur ou une capture d'écran ne remplace pas une confirmation vérifiée côté serveur.
Rattachez l'événement à une commande enregistrée côté serveur. Dans le flux natif, les événements autonomes d'API Checkout peuvent inclure checkoutSessionId et merchantOrderId sans paylinkId. Ne rejetez pas un achat autonome valide simplement parce qu'un identifiant Paylink est absent. De même, un identifiant Paylink réutilisable ne suffit pas à identifier de façon unique la commande d'un acheteur.
Vérifiez l'organisation, l'environnement, la tentative de paiement et le contexte du montant commercial attendus avant d'exécuter la commande. Le champ amount documenté correspond au montant net définitif à recevoir par le commerçant dans le jeton de paiement ; il ne représente pas automatiquement le total de votre facture d'origine en monnaie locale. Ne comparez pas ces deux nombres comme s'ils avaient la même unité. Conservez la commande d'origine approuvée par le serveur et son contexte tarifaire.
Pour les achats dynamiques, utilisez le parcours API Checkout afin de conserver la relation entre la commande et la session. Pour les produits fixes, les liens de paiement fournissent un point d'entrée de paiement réutilisable ; votre application reste responsable de la décision d'exécution.
Protégez l'effet produit, pas seulement la table des événements
Pour une commande entièrement exécutée dans votre base de données, enregistrez le résultat de l'événement et la transition de la commande dans une seule transaction. Imposez une action métier unique, par exemple une seule attribution de droits par commande ponctuelle. Un événement en double doit renvoyer le résultat existant, pas accorder un nouveau droit.
Si l'exécution fait appel à un autre service, utilisez une boîte d'envoi persistante : enregistrez l'action prévue avec la transition de la commande, puis laissez un processus de traitement la transmettre. Attribuez à l'action destinée au service en aval une clé d'idempotence stable fondée sur la commande lorsque le destinataire le permet. La boîte d'envoi seule n'empêche pas un doublon distant si le processus s'arrête après la réussite de l'action distante.
Lorsqu'une destination ne propose ni idempotence ni consultation du résultat, laissez le résultat incertain en attente de rapprochement plutôt que de réessayer aveuglément une action irréversible. Une exécution « exactement une fois » n'est pas une promesse qu'un webhook HTTP peut tenir à travers n'importe quelle combinaison de bases de données, de files d'attente et de services externes.
Empêchez les anciens événements de faire régresser une commande terminée. Un événement invoice.overdue concerne une tentative et ne doit pas annuler une commande exécutée. Pour l'accès récurrent, le fournisseur distingue les événements de facture de subscription.overdue et subscription.cancelled ; appliquez séparément la politique d'abonnement documentée.
Testez les scénarios d'échec avant d'accepter des commandes réelles
Utilisez ces cas de recette pour votre récepteur et votre processus de traitement :
- Envoyez le même événement signé deux fois et simultanément : un événement enregistré, un effet métier.
- Interrompez le processus avant et après la transition de la commande : la reprise ne doit pas accorder l'accès deux fois.
- Envoyez deux tentatives confirmées pour une même commande : exécutez-la une seule fois et signalez l'encaissement supplémentaire.
- Envoyez une signature invalide, une organisation qui ne correspond pas et une commande inconnue : aucune exécution.
- Envoyez un ancien événement de facture après la confirmation : aucune annulation de l'exécution terminée.
- Envoyez un événement en mode test au récepteur de production : aucune licence, expédition ni crédit de compte réels.
Les événements de test du tableau de bord de Yolfi utilisent livemode: false et un identifiant evt_test_. Ils permettent de tester l'envoi et le traitement du contenu, mais ne créent aucun enregistrement de paiement réel. Séparez explicitement les effets de test des effets réels ; une notification de test réussie ne prouve pas qu'un achat a été réglé.
Surveillez les événements authentifiés en attente de traitement, les échecs des processus de traitement et les paiements confirmés sans résultat d'exécution. Reliez ces exceptions à la liste de contrôle du rapprochement des paiements. Si le deuxième encaissement est un véritable paiement supplémentaire plutôt qu'une nouvelle tentative d'envoi, suivez la procédure d'examen des remboursements au lieu de supprimer les preuves.
Questions fréquentes
La vérification de signature empêche-t-elle les crédits en double ?
Non. Elle vérifie l'authenticité et l'intégrité. Un événement authentique peut arriver plusieurs fois, et une requête précédemment valide peut être rejouée. Conservez les identifiants d'événement de façon persistante et imposez une contrainte métier au niveau de la commande.
Faut-il renvoyer une réponse de succès avant d'enregistrer l'événement ?
Non. Accusez réception après l'acceptation persistante, puis effectuez les tâches plus lentes de façon asynchrone. Sinon, un arrêt après la réponse peut entraîner la perte silencieuse de l'événement.
Un hachage de transaction suffit-il comme clé de déduplication ?
Pas pour le traitement des webhooks. Utilisez l'identifiant d'événement signé documenté pour les envois d'événements, et votre propre clé de commande pour l'exécution. Les transferts et les commandes ont des identités différentes ; une transaction peut contenir plusieurs transferts.
Puis-je utiliser le même gestionnaire pour les contenus des adaptateurs ?
Pas sans vérifier leur contrat d'interface. Cet article décrit le format natif avec l'adaptateur NONE. Les adaptateurs compatibles avec des fournisseurs peuvent avoir une structure de contenu différente ; validez leurs champs documentés avant de réutiliser les règles natives d'analyse et de corrélation.
Conclusion : confirmer, enregistrer et exécuter une seule fois
Une automatisation fiable des paiements en cryptomonnaies sépare la remise authentifiée de l'événement de son effet métier sur la commande. Vérifiez la signature du corps brut, enregistrez l'événement de façon persistante, retrouvez la commande et sécurisez son exécution face aux nouvelles tentatives. Commencez par les liens de paiement Yolfi pour les produits fixes ou par la session documentée créée côté serveur pour les commandes dynamiques, en laissant à l'application la responsabilité d'accorder chaque achat une seule fois.
