Inscriptions
Le webhook d’acquisition Monobank: vérification ECDSA et pourquoi le corps de demande brute importe
Monobank signe des sangles avec ECDSA plutôt qu’un secret partagé HMAC. Voici comment la vérification fonctionne, comment mettre en cache la clé publique, et les deux erreurs qui laissent la vérification «travailler» tout en ne protégeant rien.
La plupart des passerelles de paiement ukrainiennes signent leurs callbacks avec un secret partagé : prenez votre mot de passe marchand, assemblez une chaîne par une formule documentée, hachez-la, comparez. Monobank le fait différemment, et la différence est facile à rater avec les conséquences.
Monobank signe le webhook asymétriquement: il signe avec une clé privée et vous vérifiez avec la clé PUBLIQUE, que vous allez chercher dans une demande séparée. Il n’y a pas de secret partagé du tout. C’est une sécurité strictement meilleure — même une violation complète de votre base de données n’accorde aucune possibilité de créer un événement — mais il exige deux choses un système HMAC ne : la manipulation correcte du corps de la demande brute, et la mise en cache de la clé publique.
Le contrat
- Signature
- L’en-tête x-sign — ECDSA au-dessus de SHA-256, encodé de base64
- Clé de vérification
- La clé publique marchande, GET /api/merchant/pubkey (qui requiert votre X-Token)
- Ce qui est signé
- Les octets exacts de l’organisme de demande — pas le résultat de l’analyse et de la ré-sérialisation
- Où elle arrive
- L’adresse que vous avez passée dans webHookUrl lors de la création de la facture. Le API officiel ne décrit pas de webhook marchand mondial.
- Correspondance des commandes
- marchandPaymInfo.reference — où votre magasin met son propre identifiant de commande
- Montants
- En unités mineures, pas en unités monétaires entières
- Monnaie
- Code numérique ISO-4217: 980 hryvnia, 840 dollars, 978 euros
- Le statut expiré
- NON livré par webhook — qui a créé la facture suit que
Erreur une: analyse du JSON avant vérification de la signature
La signature couvre une séquence spécifique d’octets. Si votre framework analyse automatiquement le corps dans un objet et que vous le sérialisez ensuite pour le vérifier, vous vérifiez différents octets. Ordre des clés, espace blanc, représentation des nombres, absence d’ASCII : n’importe lequel d’entre eux peut différer, et ils le font.
Le pire résultat ici n’est pas "rien ne marche" mais "travaille sur des données de test et échoue sur des données réelles" : une simple charge utile survit au voyage aller-retour, alors qu’un porteur de caractères ukrainiens au nom de l’acheteur ou un montant fractionnel ne le fait pas.
Il y a une règle : lire le corps comme un texte brut, vérifier la signature contre cela, et seulement puis parse. Dans un Next.js Route Handler qui signifie `await request.text()` avant n’importe quel `request.json()` — le deuxième appel est indisponible sur la même demande de toute façon, donc la commande ici n’est pas une question de style.
Erreur deux : récupérer la clé publique sur chaque webhook
La clé publique marchande change rarement, tout en la ramassant coûte un aller-retour à Monobank et consomme votre limite de tarif. Le faire par paiement est un moyen fiable de faire échouer sous charge exactement quand les paiements sont abondants.
Mais le mettre en cache pour toujours est faux aussi : la clé peut être rééditée, puis un cache dur signifie que vous arrêtez d’accepter les paiements jusqu’au prochain déploiement.
Le schéma de travail est cache plus rafraîchissement sur échec: prendre la clé du cache et vérifier; si la vérification échoue, relire la clé une fois et vérifier à nouveau; si elle échoue encore, rejeter. La rotation de la clé se guérit alors, tandis qu’un attaquant avec une mauvaise signature vous coûte au plus une demande supplémentaire.
Une chose évidente mérite d’être déclarée parce qu’elle est souvent mal faite : la clé publique n’est PAS un secret. Ne le chiffrez pas au repos. Il n’existe que pour vérifier les signatures, et savoir qu’il n’accorde rien. Ce qui appartient crypté est le X-Token que vous utilisez pour le récupérer.
Vérification qui protège réellement
- La vérification a échoué — rejeter la demande. Ne pas l’enregistrer et continuer "juste au cas où": un webhook sans signature valide n’est pas un événement, c’est un étranger vous disant que vous avez été payé.
- La clé n’a pas pu être récupérée, ou le X-Token n’a pas pu être déchiffré — rejeter aussi. Échec fermé : l’indisponibilité d’un chèque n’est pas une raison de faire confiance au non-coché.
- Comparez aussi l’identifiant marchand avec la configuration de l’adaptateur — alors un événement sur le compte d’un autre ne peut pas atterrir dans votre espace de travail même avec une signature valide.
- Faire le paiement écrire idempotent sur l’identifiant de facture: la banque a le droit de livrer le même événement deux fois, et c’est un comportement normal plutôt qu’un défaut.
- Ne conservez pas le numéro de carte ou CVV. Le montant, la monnaie, le statut et l’identité de la facture sont suffisants pour se rapprocher — et ce qui n’est pas dans votre base de données ne peut pas fuir.
Où mettre un paiement qui n’a trouvé aucun ordre
La signature vérifie, le montant est là, et la référence ne correspond à rien. La réaction la plus courante est de rejeter l’événement : retourner 200, n’écrire rien. C’est le pire choix disponible, car l’argent est déjà arrivé et ne laisse aucune trace dans votre système.
La pratique qui mérite d’être construite dès le début: stocker un tel paiement comme son propre dossier sans aucune commande jointe et le montrer dans un journal de paiement marqué non lié. Un gestionnaire l’ouvre, voit le montant et l’acheteur, et l’attache à une commande existante ou en crée une nouvelle. C’est dix minutes de modélisation de données qui supprime toute une classe de billets "nous avons payé et vous ne pouvez pas le voir".
Un callback signé s’authentifie
La tentation d’exiger "passer d’abord une connexion test, puis accepter les paiements" est compréhensible mais redondante ici: une signature ECDSA correcte plus un id marchand correspondant authentifie déjà complètement l’événement. Un test de connexion est utile en tant que diagnostic — à quel compte appartient ce jeton? — mais en en faire une condition préalable aux paiements réels fait obstacle à un client et à son argent.
Foire aux questions
En quoi la signature de Monobank diffère-t-elle de LiqPay et WayForPay?
LiqPay et WayForPay utilisent un secret partagé — SHA-1 et HMAC-MD5 respectivement, sur une chaîne documentée assemblée. Monobank utilise une ECDSA asymétrique: il n’y a pas de secret partagé et vous vérifiez avec une clé publique. Ainsi, le schéma d’un fournisseur ne doit jamais être copié sur un autre; chaque contrat provient de sa propre documentation officielle.
Un webhook peut-il être configuré pour l’ensemble du compte marchand ?
Le API officiel ne décrit pas une telle chose. L’adresse est passée dans le champ webHookUrl de chaque demande de création de facture, donc c’est le travail de votre magasin de l’inclure.
Pourquoi le statut expiré n’arrive-t-il jamais?
Monobank ne le livre pas par webhook. Si vous avez besoin de connaître des factures qui n’ont jamais été payées, qui a créé ces factures doit suivre leur état.
Est-ce que les quantités arrivent en hryvnia entière?
Non, en unités mineures. 149.90 arrive à 14990. La devise est fournie sous forme de code ISO-4217 numérique, et non de la chaîne "UAH".
Le CRM peut-il émettre un remboursement grâce à cette intégration?
Dans notre mise en œuvre, non, délibérément. L’adaptateur accepte les statuts de paiement, créant et annulant les factures, les remboursements et les éventuels frais restent avec Monobank et le magasin. Une intégration qui peut déplacer l’argent nécessite un niveau de confiance différent et un audit différent.
Une intégration prête au lieu de la vôtre
Obriym CRM accepte les webhooks signés de Monobank, LiqPay, WayForPay et Hutko dans un seul journal de paiement — avec idempotency, recoupement de commande et une notification à votre équipe.
Essayez-le gratuitement.