Webhooks
Les webhooks fournissent des notifications en temps réel, basées sur les événements, pour les mises à jour critiques du cycle de vie des paiements.
Les webhooks de Cardflo permettent à vos systèmes de réagir instantanément aux statuts de paiement, aux litiges et à d'autres événements clés. Automatisez les flux de travail et maintenez la synchronisation entre votre plateforme et Cardflo sans interroger constamment.
- Catégorie
- Développeur
- Capacités
- 10
- Disponible sur
- Tous les plans
L'aperçu
Les webhooks fonctionnent comme des rappels HTTP asynchrones qui facilitent la communication en temps réel entre une passerelle de paiement et un serveur marchand.
Contrairement aux méthodes d'interrogation traditionnelles où un serveur effectue des requêtes répétitives pour vérifier les mises à jour de statut, les webhooks poussent les données vers une URL prédéfinie au moment où un événement spécifique se produit dans le cycle de vie du paiement.
Ce mécanisme est essentiel pour gérer les événements non synchrones tels que les résultats d'authentification 3-D Secure, les complétions asynchrones de méthodes de paiement alternatives (APM) ou la réception d'une rétrofacturation.
Au sein de la pile de paiements, les webhooks agissent comme le tissu conjonctif entre l'acquéreur ou le PSP et le système interne de gestion des commandes (OMS) ou la plateforme de gestion des revenus du commerçant.
Ils garantissent que la logique subséquente, telle que le verrouillage des stocks ou le droit numérique, reste précise sans introduire de latence ou de surcharge API inutile.
Une implémentation correcte nécessite une gestion robuste des codes de statut HTTP et de l'idempotence pour gérer les nouvelles tentatives potentielles du serveur d'envoi, garantissant que chaque événement est traité une seule et unique fois.
Comment ça marche
Définir le point de terminaison et les événements
Un commerçant spécifie une URL de destination dans son environnement pour recevoir les requêtes POST. Il sélectionne des déclencheurs d'événements spécifiques du cycle de vie du paiement, tels que le succès de l'autorisation, l'initiation du remboursement ou la création de litige.
Cela garantit que son système ne traite que les paquets de données pertinents, réduisant la charge inutile du serveur et gardant les points d'intégration ciblés et gérables.
Déclencheur d'événement et charge utile
Lorsqu'un changement de statut se produit, par exemple un client terminant un défi SCA, le système génère une charge utile JSON. Cette charge utile contient des données structurées, y compris l'ID de transaction, l'ID du commerçant (MID), le montant et le type d'événement spécifique.
La passerelle tente ensuite de livrer ces données au point de terminaison enregistré.
Sécurité et vérification de la signature
Pour empêcher l'injection de données non autorisées, la charge utile est généralement signée avec une clé secrète. Le serveur marchand reconstitue la signature en utilisant le corps de la requête brute et la compare à l'en-tête.
Cette vérification garantit que les données proviennent de la source fiable et n'ont pas été altérées pendant le transit.
Accuser réception et traiter
Le serveur marchand doit renvoyer un code de statut 200 OK rapidement pour accuser réception. La logique interne s'exécute ensuite, comme la mise à jour d'un enregistrement de base de données ou le déclenchement d'un e-mail automatisé.
Si le serveur est hors ligne ou renvoie une erreur, le système de livraison suit un calendrier de nouvelle tentative programmé pour assurer la cohérence des données.
Pourquoi c'est important
Efficacité opérationnelle et automatisation
S'appuyer sur des vérifications de statut manuelles ou une interrogation API périodique introduit une latence qui peut dégrader l'expérience utilisateur et retarder l'exécution. Les webhooks automatisent la transition entre l'autorisation de paiement et la livraison du service.
En recevant une notification immédiate des captures ou des règlements réussis, les entreprises peuvent automatiser les flux de travail d'expédition, la génération de licences ou la provision de comptes, réduisant le besoin d'intervention manuelle et minimisant le risque d'erreur humaine dans la gestion des transactions.
Atténuation des risques et des litiges
Les notifications pour les demandes de récupération ou les rétrofacturations permettent aux commerçants de répondre dans les délais imposés par le système. Les alertes immédiates concernant les refus doux ou les échecs SCA permettent un engagement client proactif.
En réagissant à ces événements au fur et à mesure qu'ils se produisent,
les commerçants peuvent améliorer leurs taux de réussite de représentation et réduire les coûts opérationnels associés aux échecs de paiement non traités ou aux litiges qui autrement seraient passés inaperçus jusqu'à un audit manuel périodique.
Cas d'usage
Cycle de vie des abonnements et SaaS
Lorsqu'un paiement récurrent échoue ou qu'une carte expire, un webhook déclenche une séquence de relance automatisée ou suspend l'accès de l'utilisateur, maintenant des cycles de facturation précis sans surveillance manuelle.
Exécution des commandes e-commerce
Un détaillant en ligne utilise des webhooks pour libérer les marchandises pour l'expédition uniquement après avoir reçu un événement 'capture. succeeded', empêchant l'expédition d'articles pour lesquels le paiement n'a pas été entièrement autorisé.
Coordination des paiements de la place de marché
Les plateformes recevant des fonds peuvent déclencher des décaissements aux sous-commerçants uniquement après que la transaction client initiale ait atteint un statut réglé, garantissant la liquidité et réduisant le risque d'annulation des paiements.
Finalisation des méthodes de paiement alternatives
Pour les méthodes comme les virements bancaires ou les systèmes locaux qui ne fournissent pas de confirmation instantanée, les webhooks notifient le système des heures ou des jours plus tard lorsque les fonds sont confirmés.
En chiffres
Délai typique de l'industrie entre l'enregistrement d'un événement dans la plateforme d'acquisition et l'envoi du webhook au point de terminaison du commerçant.
Référence de fiabilité standard pour les services de webhook lorsqu'ils incluent une logique de nouvelle tentative automatisée et une infrastructure de livraison redondante.
Observation de l'industrie de l'amélioration de la vitesse d'exécution lors du passage du traitement par lots périodique aux architectures de webhook basées sur les événements.
Termes associés
Talk to our team about a live rollout on your acquiring stack.
Ce que vous obtenez avec Webhooks
- Livraison asynchrone des changements de statut de transaction pour une performance système améliorée.
- Prise en charge de plusieurs types d'événements, y compris l'autorisation, la capture, le remboursement et le litige.
- En-têtes de signature HMAC-SHA256 pour une vérification robuste de l'intégrité des données entrantes.
- Logique de nouvelle tentative automatisée suivant des calendriers de recul exponentiel pour les tentatives de livraison échouées.
- Gestion des versions de la charge utile pour assurer la compatibilité à mesure que les structures de données évoluent.
- Capacités de liste blanche IP pour restreindre le trafic entrant aux sources de passerelle connues.
- Inclusion de la clé d'idempotence pour éviter le traitement en double du même événement de paiement.
- Journaux d'événements détaillés pour le débogage et l'audit des performances de livraison des webhooks dans le tableau de bord.
- Sélection granulaire des événements pour minimiser l'utilisation de la bande passante et les exigences de traitement côté serveur.
- Fonctionnalité de mode test pour valider le comportement des points de terminaison avec des scénarios de paiement simulés.
A short scoping call, then a written plan for your MIDs.
Questions à propos de Webhooks
Comment notre serveur doit-il gérer les notifications de webhook en double ?
Il est d'usage que les passerelles de paiement emploient un mécanisme de nouvelle tentative si un point de terminaison ne renvoie pas une réponse 200 OK dans un délai spécifique. Par conséquent, votre serveur peut recevoir le même événement plusieurs fois.
Pour maintenir l'intégrité des données, vous devez implémenter une logique d'idempotence. Cela implique généralement de suivre l'ID d'événement unique fourni dans la charge utile et de vérifier s'il a déjà été traité avant d'exécuter toute logique métier.
Si l'ID existe dans votre base de données, votre serveur doit ignorer l'événement mais renvoyer un 200 OK pour arrêter d'autres tentatives.
Quelle est la différence entre l'interrogation d'une API et l'utilisation de webhooks ?
L'interrogation exige que votre serveur initie des requêtes fréquentes à la passerelle pour vérifier les mises à jour de statut, ce qui est inefficace et peut entraîner des problèmes de limitation de débit ou des informations retardées.
Les webhooks inversent ce flux, où la passerelle initie une requête à votre serveur uniquement lorsqu'un événement se produit.
Ce modèle 'push' est plus efficace, réduisant la charge du serveur et garantissant que les statuts sont mis à jour en temps quasi réel sur votre infrastructure,
ce qui est particulièrement important pour les actions sensibles au temps comme la livraison de contenu numérique ou la prévention de la fraude.
Pourquoi la vérification de la signature est-elle nécessaire pour chaque requête de webhook ?
Étant donné que les points de terminaison de webhook sont des URL publiques, ils sont théoriquement accessibles par toute entité sur Internet.
Sans vérification, un attaquant pourrait envoyer une charge utile JSON falsifiée à votre serveur, indiquant faussement qu'un paiement de grande valeur a été réussi.
En utilisant un secret partagé pour vérifier la signature HMAC fournie dans l'en-tête de la requête, votre système peut prouver mathématiquement que le message a été envoyé par votre PSP et que le contenu n'a pas été altéré,
garantissant la sécurité de votre processus d'exécution des commandes.
Comment les webhooks gèrent-ils les exigences 3-D Secure et SCA ?
Lors d'un flux 3-DS, la transaction passe souvent à un état en attente pendant que l'utilisateur est redirigé vers son émetteur pour authentification. Le résultat final de cette authentification peut ne pas être connu immédiatement.
Les webhooks sont utilisés pour notifier votre système lorsque le défi 3-DS est terminé et que la transaction est ensuite autorisée ou refusée.
Cela empêche votre processus de paiement de rester bloqué et permet à votre backend de réagir à l'état d'autorisation final une fois que le client revient de la page de redirection de la banque.
Les webhooks peuvent-ils être utilisés pour gérer les délais de rétrofacturation et de litige ?
Oui, les webhooks sont un outil principal pour gérer le cycle de vie des litiges. Lorsqu'un titulaire de carte initie une demande de récupération ou une rétrofacturation formelle auprès de son émetteur, la passerelle reçoit cette notification via les systèmes de cartes.
Un webhook est ensuite envoyé à votre système spécifiant le code de motif, le montant et la date limite de réponse.
En utilisant ces données en temps réel, vous pouvez automatiser la suspension du compte pertinent et notifier votre équipe de risque pour qu'elle commence immédiatement le processus de représentation, augmentant la probabilité d'une annulation réussie du litige.
Que se passe-t-il si notre serveur est en panne lors d'un événement de webhook critique ?
Les systèmes de webhook fiables fonctionnent avec une politique de nouvelle tentative. Si votre point de terminaison renvoie une erreur 4xx ou 5xx, ou ne répond pas dans les quelques secondes, la passerelle mettra le message en file d'attente pour une nouvelle livraison.
Ces nouvelles tentatives suivent généralement un modèle de recul exponentiel, tentant la livraison plusieurs fois sur des minutes ou des heures.
Pour assurer une cohérence à long terme, vous devriez également avoir un mécanisme de secours, tel qu'un script de réconciliation quotidien qui appelle l'API pour trouver tout changement de statut manqué, offrant un filet de sécurité pour les pannes prolongées.
Fonctions liées.
Prêt à accélérer ?
Parlez-nous de votre activité. Nous vous mettrons en relation avec les bons partenaires acquéreurs et la bonne route, généralement en moins d'une semaine.