Configurer un webhook chez Mangopay
Lorsque vous utilisez des système-tiers pour déléguer certains traitements, comme la gestion des paiements, il est nécessaire de maintenir un synchronisation entre les données de votre plateforme Kreezalid, et celles stockées chez le système tiers.
Dans le cadre d'un paiement-vendeur (PayOut), nous envoyons plusieurs instructions à Mangopay, contenant le montant à virer au vendeur, son compte bancaire, le montant des commissions de la plateforme... Ces instructions créent une demande de virement, que les opérateurs doivent confirmer manuellement dans les 24h ouvrés.
Une fois le virement réussi (ou échoué), le statut du PayOut est mis à jour. Il est donc nécessaire de récupérer le nouveau statut de cette opération.
Il y a deux grandes méthodes de récupérer ses informations: en utilisant une tâche cron ou les webhooks.
Une tâche cron est un script que vous hébergez et qui va s'exécuter à intervalle régulier. Par exemple, vous pourriez faire un appel API toutes les minutes, toutes les heures ou bien toutes les 24h à Mangopay, pour récupérer le statut de toutes vos opérations en attente chez Mangopay.
C'est une manière très simple et très efficace de récupère les derniers statuts. Cependant, vous aurez toujours un certain délai de retard entre la mise à jour du statut chez Mangopay, et la mise à jour de votre côté. Pour limiter ce retard, vous pouvez exécuter cette tâche toutes les minutes ou toutes les deux minutes, mais au dela du gaspillage de ressource serveur que cela constitue (la plupart de vos requêtes risquent de ne rien retourner), cela peut également avoir un impact sur votre accès à votre service tiers: on vous impose souvent des limites dans le nombre de requêtes par minute, par heure ou par journée. Ce serait dommage qu'un acheteur ne puisse pas finaliser un paiement car votre crédit de requête API est épuisé.
Afin d'économiser des ressources serveurs, l'idéal serait que ce soit le service tiers qui nous informe d'un changement de statut. De plus, cela serait parfait si le service tiers pouvait nous prévenir en temps réel. Ainsi, nous pourrions limiter le décalage entre les informations stockées chez Mangopay, et celles stockées sur votre plateforme.
Mangopay propose justement un système de notification automatisé (appelé plus communèment hook ou webhook) qui va permettre de récupèrer des informations mises à jour de leur côté.
Les webhooks ne sont pas des notifications destinées aux utilisateurs (ou administrateurs) du compte. Si vous voulez être notifié d'un événement par e-mail, vous pouvez néanmoins écouter les notifications que Mangopay envoie par rapport à cet événement, mais vous devrez vous même écrire le script qui vous enverra l'email avec les informations récupérées du webhook.
Les webhooks sont donc des notifications destinées exclusivement à un script, qui va déclencher tout un tas d'action, que vous aurez au préalable programmé. Par exemple, vous pouvez demander à recevoir un e-mail à chaque fois qu'un document KYC est refusé, afin de pouvoir recontacter l'utilisateur pour lui demander de soumettre à nouveau un document. Ou bien, dans le cadre de nos PayOuts, vous pouvez mettre à jour une commande, lorsque vous avez la confirmation que le virement a bien été effectué par les équipes de MangoPay.
Rendez-vous dans votre Hub Mangopay, puis cliquer sur le bouton "Accès dashboard". Une fois sur votre dashboard, chercher dans le menu de gauche le lien "Webhooks".
Vous devriez voir une liste de notifications disponibles. Mangopay vous permet ainsi de choisir quel type d'événement vous souhaitez écouter: Payin Created, Payin Succeeded, Payout Created, Payout Failed, Kyc Validation Asked, Kyc Failed, etc.
Vous pouvez par exemple écouter les événements Payout Failed et Payout Succeeded afin de mettre à jour la commande si le paiement vendeur a réussi ou échoué.
Cliquez sur le bouton à côté du type d'événement que vous souhaitez écouter, et sur le bouton "Add a hook" qui devrait apparaître. Renseignez alors l'URL de votre script. Dans notre cas, il s'agit de l'URL https://{{votre_nom_de_domain}}/psp/webhook/mp/endpoint (veillez à bien remplacer {{ votre_nom_de_domain }} par votre vrai nom de domaine).
Et voilà ! A chaque fois qu'un PayOut sera mis à jour par Mangopay, les modifications seront envoyées en temps réel à ce script qui s'occupera d'envoyer un e-mail à l'administrateur en cas d'échec, ou d'envoyer un e-mail au vendeur en cas de succès.
Dans le cadre d'un paiement-vendeur (PayOut), nous envoyons plusieurs instructions à Mangopay, contenant le montant à virer au vendeur, son compte bancaire, le montant des commissions de la plateforme... Ces instructions créent une demande de virement, que les opérateurs doivent confirmer manuellement dans les 24h ouvrés.
Une fois le virement réussi (ou échoué), le statut du PayOut est mis à jour. Il est donc nécessaire de récupérer le nouveau statut de cette opération.
Il y a deux grandes méthodes de récupérer ses informations: en utilisant une tâche cron ou les webhooks.
Les tâches crons
Une tâche cron est un script que vous hébergez et qui va s'exécuter à intervalle régulier. Par exemple, vous pourriez faire un appel API toutes les minutes, toutes les heures ou bien toutes les 24h à Mangopay, pour récupérer le statut de toutes vos opérations en attente chez Mangopay.
C'est une manière très simple et très efficace de récupère les derniers statuts. Cependant, vous aurez toujours un certain délai de retard entre la mise à jour du statut chez Mangopay, et la mise à jour de votre côté. Pour limiter ce retard, vous pouvez exécuter cette tâche toutes les minutes ou toutes les deux minutes, mais au dela du gaspillage de ressource serveur que cela constitue (la plupart de vos requêtes risquent de ne rien retourner), cela peut également avoir un impact sur votre accès à votre service tiers: on vous impose souvent des limites dans le nombre de requêtes par minute, par heure ou par journée. Ce serait dommage qu'un acheteur ne puisse pas finaliser un paiement car votre crédit de requête API est épuisé.
Les webhooks
Afin d'économiser des ressources serveurs, l'idéal serait que ce soit le service tiers qui nous informe d'un changement de statut. De plus, cela serait parfait si le service tiers pouvait nous prévenir en temps réel. Ainsi, nous pourrions limiter le décalage entre les informations stockées chez Mangopay, et celles stockées sur votre plateforme.
Mangopay propose justement un système de notification automatisé (appelé plus communèment hook ou webhook) qui va permettre de récupèrer des informations mises à jour de leur côté.
Les webhooks ne sont pas des notifications destinées aux utilisateurs (ou administrateurs) du compte. Si vous voulez être notifié d'un événement par e-mail, vous pouvez néanmoins écouter les notifications que Mangopay envoie par rapport à cet événement, mais vous devrez vous même écrire le script qui vous enverra l'email avec les informations récupérées du webhook.
Les webhooks sont donc des notifications destinées exclusivement à un script, qui va déclencher tout un tas d'action, que vous aurez au préalable programmé. Par exemple, vous pouvez demander à recevoir un e-mail à chaque fois qu'un document KYC est refusé, afin de pouvoir recontacter l'utilisateur pour lui demander de soumettre à nouveau un document. Ou bien, dans le cadre de nos PayOuts, vous pouvez mettre à jour une commande, lorsque vous avez la confirmation que le virement a bien été effectué par les équipes de MangoPay.
Comment configurer un webhook sur Mangopay
Rendez-vous dans votre Hub Mangopay, puis cliquer sur le bouton "Accès dashboard". Une fois sur votre dashboard, chercher dans le menu de gauche le lien "Webhooks".
Vous devriez voir une liste de notifications disponibles. Mangopay vous permet ainsi de choisir quel type d'événement vous souhaitez écouter: Payin Created, Payin Succeeded, Payout Created, Payout Failed, Kyc Validation Asked, Kyc Failed, etc.
Vous pouvez par exemple écouter les événements Payout Failed et Payout Succeeded afin de mettre à jour la commande si le paiement vendeur a réussi ou échoué.
Cliquez sur le bouton à côté du type d'événement que vous souhaitez écouter, et sur le bouton "Add a hook" qui devrait apparaître. Renseignez alors l'URL de votre script. Dans notre cas, il s'agit de l'URL https://{{votre_nom_de_domain}}/psp/webhook/mp/endpoint (veillez à bien remplacer {{ votre_nom_de_domain }} par votre vrai nom de domaine).
Et voilà ! A chaque fois qu'un PayOut sera mis à jour par Mangopay, les modifications seront envoyées en temps réel à ce script qui s'occupera d'envoyer un e-mail à l'administrateur en cas d'échec, ou d'envoyer un e-mail au vendeur en cas de succès.
Mis à jour le : 20/03/2023
Merci !