Skip to main content
Mercy Pay envoie un événement à votre serveur à chaque changement de statut d’un paiement ou d’un retrait. Fiez-vous à cet événement pour confirmer un encaissement, pas à la redirection du navigateur.
1

Déclarez l'endpoint

Dans l’onglet Webhooks de la console Développeurs, ajoutez une URL HTTPS publique et cochez les événements voulus. Mercy Pay affiche alors le secret de signature (whsec_…). Copiez-le dans vos secrets. Vous pourrez le réafficher plus tard depuis la console, après avoir confirmé votre mot de passe.
2

Vérifiez la signature

Chaque requête porte l’en-tête MercyPay-Signature, de la forme t=1791022800,v1=5257a869…. t est l’heure d’envoi, v1 le HMAC-SHA256 en hexadécimal de {t}.{corps brut}, calculé avec votre secret. Refusez une signature de plus de 5 minutes : elle protège contre le rejeu d’une ancienne requête. Voir Sécurité des webhooks.
Vérifiez le corps tel qu’il est reçu, avant tout JSON.parse.
3

Répondez vite, traitez après

Répondez 2xx dès que la signature est validée, avant de lancer un traitement lourd. Mercy Pay n’attend que 10 secondes. Passé ce délai, ou sur une réponse qui n’est pas 2xx, la livraison est considérée en échec et reprise plus tard.Si votre serveur n’a accepté aucun événement pendant ces 3 jours, l’endpoint est désactivé et les développeurs de votre boutique reçoivent un e-mail. Corrigez le serveur, réactivez l’endpoint, puis cliquez sur Relancer les échecs dans la console. Les événements restent consultables avec GET /api/v1/events.
4

Dédupliquez par identifiant

Une même livraison peut arriver deux fois, par exemple si le réseau coupe juste après votre 2xx. Chaque événement porte un id (evt_…), répété dans l’en-tête MercyPay-Event-Id : enregistrez ceux que vous avez déjà traités et ignorez les doublons.

Exemple d’événement