Un webhook de paiement reçu deux fois doit produire une seule action de livraison prévue pour la même transaction vérifiée. Pour PayRequest payment.succeeded, vérifiez d'abord la signature du corps brut, puis utilisez l'identifiant data.id dans une clé de traitement durable. Répéter une notification ne doit pas créer une seconde livraison ou un crédit de service.
Cette checklist est un protocole de conception et de recette pour les développeurs d'un système de livraison externe. Une ligne en base ne garantit pas, seule, une action externe exécutée exactement une fois.
Vérifier le contrat réel
La documentation des webhooks PayRequest décrit HTTPS POST, X-PayRequest-Signature et HMAC-SHA256 sur le corps brut. Vérifiez avec un secret serveur et une comparaison à temps constant. Validez format et longueur : certaines fonctions refusent des longueurs différentes. Préservez les octets avant l'analyse JSON.
Pour payment.succeeded, data.id est l'identifiant de transaction. La charge utile publiée ne documente pas d'identifiant d'événement distinct au premier niveau. Ne copiez pas event.id d'un autre prestataire sans vérifier. Gardez les secrets hors du navigateur et évitez de journaliser inutilement toutes les données client.
Identifier le paiement, pas le lien partagé
Exemple de clé : integration-account / payment.succeeded / data.id. Ajoutez le périmètre du compte si le récepteur sert plusieurs marchands. C'est votre conception, pas un champ généré par PayRequest.
Un payment_link_id peut correspondre à plusieurs paiements légitimes. E-mail, montant et description ne sont pas des clés uniques suffisantes : un client peut acheter deux fois. La même data.id signifie répétition ; une nouvelle data.id sur le même lien signifie nouveau paiement.
Associez la transaction à une commande ou un droit réel avec une référence contrôlée de votre intégration. Un succès ne définit pas seul le paquet, la période ou la quantité à fournir. Isolez une référence inconnue pour examen.
Comparez montant et devise avec la commande prévue avant d’autoriser la livraison. Des valeurs inattendues demandent un examen.
Enregistrer durablement avant l'accusé de réception
Utilisez une contrainte d'unicité et une transaction atomique pour le paiement accepté et une tâche de livraison en attente. Une outbox durable sépare réception et travail lent. Confirmez après acceptation durable ; une répétition connue ne crée pas une nouvelle tâche.
PayRequest accepte 2xx. Les docs indiquent cinq tentatives pour les webhooks de caution, mais seulement la politique de queue existante pour les paiements, sans nombre. N'appliquez pas les délais des cautions aux paiements ou à votre conservation des clés.
Une livraison externe peut réussir avant que le worker ne plante sans enregistrer la fin. Utilisez l'idempotence disponible du système cible ou rapprochez le résultat externe avant de recommencer. Le registre local ne garantit pas une exécution unique entre systèmes.
Exécuter cette matrice originale
Utilisez un récepteur isolé et des données fictives signées sans livraison réelle. Signez avec un secret de test ; tout changement du corps demande une nouvelle signature. Il s'agit de tests proposés, pas de tests d'un compte de production.
| Test | Entrée | Résultat attendu |
|---|---|---|
| Répétition | Même transaction deux fois | Un paiement et une tâche |
| Concurrence | Deux copies valides simultanées | Unicité empêche deux tâches |
| Deuxième vente | Même lien, nouvelle transaction | Deux paiements et tâches |
| Falsification | Corps modifié, ancienne signature | Rejet avant livraison |
| Arrêt du worker | Crash après stockage de la tâche | Travail en attente récupérable |
Testez aussi les références inconnues et longueurs de signature invalides. Comptez séparément les lignes durables et les effets externes. HTTP 200 confirme l'accusé de réception, pas la livraison terminée.
Rapprocher paiement et effet
Conservez transaction, compte, état de traitement, tâche et référence du résultat externe. Examinez les transactions payées avec livraison en attente par le même chemin contrôlé, sans seconde livraison manuelle contournant le registre.
Commencez par la documentation API PayRequest. Le rapprochement des paiements fournit le contexte financier ; paiement et livraison restent deux enregistrements distincts.
Note éditoriale : l'IA a aidé à rédiger article et couverture. Contrat vérifié le 4 octobre 2026. Clé, matrice et architecture sont des recommandations originales, pas un test d'intégration en production ni une garantie de livraison.
