Configurer les webhooks OxaPay : guide pratique

Lorsqu'un client effectue un paiement en cryptomonnaie, le processus ne fait que commencer. Votre site ou application doit encore confirmer le résultat, mettre à jour la bonne commande, informer le client et déterminer si son exécution peut débuter. Les webhooks OxaPay le permettent en envoyant directement à votre serveur les mises à jour du statut du paiement.

Une intégration fiable des webhooks ne se limite pas à recevoir une notification. Elle vérifie l'authenticité du rappel, l'associe au bon paiement, gère sans risque les livraisons répétées et interroge le statut lorsque les informations sont retardées ou incertaines. Ce guide décrit l'ensemble du processus de manière concrète pour les dirigeants, les équipes produit et les développeurs.

À quoi sert un webhook OxaPay ?

Un webhook est un message de serveur à serveur déclenché par un événement. Au lieu que votre système demande sans cesse si un paiement a changé, OxaPay envoie un rappel JSON à l'URL HTTPS que vous avez fournie dès que de nouvelles informations de paiement sont disponibles.

Votre application peut utiliser cette mise à jour vérifiée pour modifier le statut d'une commande, activer un service, envoyer une confirmation ou créer une écriture de  rapprochement. C'est particulièrement utile, car un paiement en cryptomonnaie peut passer par plusieurs états avant d'aboutir à un résultat commercial définitif.

La page de retour du navigateur ne doit pas être considérée comme une preuve de paiement. Un client peut fermer la page, perdre sa connexion ou accéder à l'URL de retour sans que le paiement ait atteint l'état requis. La décision d'exécuter une commande doit reposer sur des informations de paiement vérifiées côté serveur.

Quand votre entreprise a-t-elle besoin d'un webhook de paiement ?

Un webhook personnalisé est surtout utile lorsque le résultat d'un paiement doit déclencher automatiquement une autre action. Par exemple :

• faire passer une commande e-commerce de « en attente » à « prête à être exécutée » ;
• activer un compte SaaS ou prolonger un abonnement ;
• envoyer une confirmation de paiement par e-mail, SMS ou message dans l'application ;
• mettre à jour les stocks, le CRM, la comptabilité ou les outils de reporting interne ;
• alerter l'équipe opérationnelle lorsqu'un paiement est  insuffisant ou expiré, ou nécessite une vérification pour une autre raison.

Si vous utilisez un module de paiementcompatible, l'intégration prend peut-être déjà en charge une grande partie de cette logique. Si vous créez seulement quelques  Payment Links and review them manually, you may not need a custom endpoint. intégrations API directes and custom platforms usually benefit the most.

Comment fonctionne le flux des webhooks OxaPay ?

1. Your system creates or identifies a payment and stores OxaPay’s track_id with your own order or customer reference.
2. Le client envoie le paiement et son statut évolue pendant le traitement par OxaPay.
3. OxaPay envoie un rappel JSON signé à l'URL de rappel configurée.
4. Votre serveur vérifie la signature avant de faire confiance au message.
5. Votre serveur rattache le rappel au bon enregistrement et valide les informations essentielles du paiement.
6. Votre application enregistre l'événement, n'exécute qu'une seule fois chaque action métier autorisée et renvoie une réponse HTTP indiquant la réussite.

Cette séparation est importante. Le webhook transmet une mise à jour du paiement, mais votre application reste chargée de déterminer ses conséquences pour la commande, le compte, l'expédition ou l'écriture comptable.

Avant de commencer

Préparez les éléments suivants avant de connecter le rappel :

• un point de terminaison HTTPS publiquement accessible, acceptant les requêtes HTTP POST ;
• un accès côté serveur aux identifiants marchands OxaPay concernés, conservés de manière sécurisée et jamais exposés dans le code du navigateur ;
• un enregistrement en base de données associant l'identifiant OxaPay  track_id with your own order, invoice, or user ID;
• des règles précises indiquant quels statuts de paiement autorisent l'exécution, l'accès, les remboursements, les notifications ou un examen manuel ;
• une journalisation et une surveillance permettant de repérer les échecs de livraison, les erreurs de validation et les changements de statut inattendus.

Si vous préparez une intégration plus large, utilisez la  liste de contrôle d'intégration des paiements en cryptomonnaie to review keys, payment methods, callbacks, testing, and go-live controls together.

Comment configurer les webhooks OxaPay

Définir les règles relatives aux statuts de paiement

Avant d'écrire le gestionnaire, décidez de l'action à entreprendre pour chaque  statut de paiement before writing the handler. A notification that a payment has started is not the same as a completed payment. Underpaid, expired, refunded, or other exception states may require a different action or a manual review.

N'autorisez que les transitions de statut documentées et attendues. Par exemple, une commande déjà exécutée ne doit pas l'être à nouveau simplement parce que le même rappel a été livré deux fois.

Créer un point de terminaison de rappel sécurisé

Créez une route HTTPS dédiée dans votre backend, par exemple  https://example.com/webhooks/oxapay. Elle doit accepter les requêtes POST, conserver l'accès au corps brut de la requête pour vérifier la signature et rejeter les méthodes non prises en charge ou les requêtes mal formées.

Gardez ce gestionnaire concentré sur l'essentiel. Sa première tâche consiste à vérifier le rappel et à l'enregistrer durablement. Les opérations lentes, comme l'envoi d'e-mails, la mise à jour de plusieurs systèmes externes ou la production de rapports, peuvent être placées dans une file de traitement en arrière-plan après l'acceptation de l'événement.

Fournir l'URL de rappel à OxaPay

Ajoutez l'URL de rappel au flux de paiement OxaPay concerné. Selon le produit ou le mode d'intégration, elle peut être transmise dans la demande de paiement ou définie dans la configuration marchande correspondante. Consultez la  documentation actuelle des webhooks OxaPay for the exact field and behavior of the service you are implementing.

Utilisez systématiquement la même URL dans chaque environnement. Séparez les points de terminaison de test et de production afin qu'un événement de test ne puisse pas modifier une commande réelle.

Vérifier la signature avant d'accepter le rappel

OxaPay documente une signature HMAC-SHA512 calculée à partir des données POST brutes, avec la clé API marchande comme secret partagé. Votre serveur doit calculer la signature attendue à partir du corps brut inchangé et la comparer à celle fournie avec le rappel.

Rejetez la requête si la vérification échoue. Utilisez une comparaison en temps constant lorsque votre framework le permet et ne journalisez jamais la clé API marchande ni aucun autre secret. Analyser le JSON puis le sérialiser à nouveau avant de calculer le HMAC peut modifier les espaces ou l'ordre des champs et faire échouer une vérification pourtant valide. La  référence sur la vérification des rappels explains the broader security model.

Associer et valider le paiement

Une signature valide confirme l'origine du message, mais votre application doit tout de même valider les données métier. Associez l'identifiant  track_id to a known payment record, confirm the relevant order or customer reference, compare the expected amount and currency where applicable, and check that the new state is allowed from the current state.

Ne laissez pas un paiement inconnu, un montant inattendu ou une transition de statut invalide déclencher automatiquement l'exécution d'une commande. Enregistrez l'événement pour enquête et confirmez les informations actuelles du paiement via l'API.

Traiter chaque événement de manière idempotente

Un webhook peut être livré plusieurs fois. Votre gestionnaire doit produire le même résultat final lorsqu'il reçoit plusieurs fois la même mise à jour de paiement. Enregistrez une clé stable d'événement ou de statut et vérifiez-la avant d'envoyer un e-mail, d'accorder un accès, de modifier les stocks ou de créer une écriture comptable.

L'idempotence transforme une livraison en double en une nouvelle tentative sans conséquence, plutôt qu'en une expédition en double, une prolongation répétée d'abonnement ou une double écriture comptable.

Enregistrer l'événement et répondre rapidement

Une fois la requête vérifiée, enregistrez le rappel et le résultat de sa validation avant de renvoyer HTTP  200 with the expected ok response. If downstream work may take time, place it in a queue and respond after durable receipt rather than making the sender wait for the entire business workflow.

Si votre serveur ne peut pas enregistrer l'événement de manière sûre, renvoyez une erreur et examinez la cause. N'accusez pas réception d'un rappel pour ensuite l'écarter silencieusement.

Tester l'ensemble du cycle de vie du paiement

Ne testez pas seulement un rappel réussi. Couvrez les états et exceptions possibles : paiements retardés, insuffisants ou expirés, livraisons répétées, signatures invalides, valeurs inconnues de  track_id values, temporary database failure, and recovery after downtime.

Vérifiez le résultat technique autant que le résultat métier. Le point de terminaison peut renvoyer  200 OK while the wrong order is updated or the customer receives two confirmations. A complete test follows the event from OxaPay through your database, queue, customer message, fulfillment logic, and audit trail.

Utiliser conjointement les webhooks et les vérifications de statut

Les webhooks et les requêtes de statut via API répondent à deux aspects d'un même problème. Le webhook fournit un signal rapide. La requête de statut offre une voie de reprise faisant autorité lorsqu'un rappel est retardé, manqué, traité dans le désordre ou reste incertain après une panne locale.

For important payment flows, schedule reconciliation for records that remain pending too long or have not received an expected update. OxaPay’s Payment Information API can be used to retrieve the current payment details by the documented identifier.

Cas d'usage pratiques des webhooks

Commandes e-commerce

Laissez la commande en attente tant que le paiement est en cours. Après vérification d'un état de paiement terminé, réservez ou libérez les stocks selon vos règles métier, transmettez une seule fois la commande à l'exécution et envoyez une confirmation au client.

SaaS et accès numérique

Activez le compte ou prolongez l'accès uniquement après vérification du paiement. Enregistrez la période payée ou le changement de droits afin qu'un rappel répété n'accorde pas deux fois le même avantage.

Finance et rapprochement

Ajoutez les événements de paiement à une piste d'audit et reliez-les à la facture interne. Les états exceptionnels peuvent entrer dans une file de vérification, tandis que les contrôles de statut programmés rapprochent les paiements non résolus.

Communication client

Envoyez les messages à partir du résultat de votre processus métier idempotent, et non directement à chaque rappel reçu. Vous éviterez ainsi les e-mails en double ou les messages contradictoires lorsqu'un paiement passe par plusieurs états.

Erreurs fréquentes avec les webhooks

• Faire confiance à la page de retour : use verified server-side payment information instead of a browser redirect.
• Vérifier un JSON reformaté : calculate the HMAC from the original raw request body.
• Exposer la clé marchande : keep signing credentials in protected server-side storage.
• Supposer chaque rappel unique : make every business action idempotent.
• Trop traiter avant de répondre : durably record the event, queue slow work, and respond promptly.
• Accepter toute transition de statut : enforce a controlled payment state model.
• Dépendre uniquement de la livraison : use payment information requests for recovery and reconciliation.
• Journaliser des données sensibles : retain useful identifiers and validation results without storing secrets unnecessarily.

Dépannage des webhooks OxaPay

Liste de contrôle avant la mise en production des webhooks OxaPay

• Le rappel de production utilise HTTPS et reste accessible depuis Internet.
• Le corps brut de la requête est conservé jusqu'à la fin de la vérification HMAC-SHA512.
• La clé API marchande est stockée de manière sécurisée et n'apparaît jamais dans le code client ni les journaux.
• Chaque rappel est associé à un paiement connu et validé par rapport aux données métier attendues.
• Les transitions de statut autorisées sont documentées et appliquées.
• Les rappels répétés ne peuvent pas répéter l'exécution, l'octroi d'accès, les notifications ou les écritures comptables.
• Les événements et résultats de validation sont journalisés sans données sensibles inutiles.
• Les paiements retardés ou incertains peuvent être rapprochés via l'Payment Information API.
• La surveillance alerte l'équipe en cas d'échec de signature, d'erreur de traitement ou d'accumulation dans les files.
• L'ensemble du processus a été testé avant que les paiements réels des clients en dépendent.

Et ensuite ?

Commencez par définir l'action métier autorisée pour chaque statut de paiement. Créez ensuite un point de terminaison sécurisé qui vérifie, enregistre et déduplique les rappels avant de déclencher le traitement en aval. Enfin, ajoutez une voie de vérification des statuts et de rapprochement pour qu'un problème temporaire de livraison ou de système ne laisse pas une commande indéfiniment sans résolution.

Pour approfondir les statuts de paiement, la livraison et l'architecture de reprise, lisez  Surveillance en temps réel dans les systèmes de paiement blockchain. Les développeurs doivent considérer la  documentation actuelle des webhooks OxaPay as the implementation source of truth.