Dépannage surveillance des transactions : solutions

A reference of common Transaction Monitoring issues, with symptom, cause, and fix. Référence des problèmes courants liés à la Surveillance des transactions, avec leurs symptômes, causes et solutions.

​

Erreur txn_id en double

Symptôme. L’envoi d’une transaction renvoie 400 avec A transaction with this transaction_id already exists. sur le champ transaction_id, ou 409 lorsque deux requêtes identiques sont envoyées en même temps. Cause. txn_id (le transaction_id que vous envoyez) est unique par application. Didit rejette une seconde transaction portant le même transaction_id et ne renvoie pas l’enregistrement existant. Solution.

• Générez txn_id de manière déterministe de votre côté (par exemple en utilisant l’identifiant de votre propre base de données de transactions).
• En cas de 400 ou de 409 pour un transaction_id en double lors d’une nouvelle tentative, recherchez la transaction existante au lieu de la renvoyer : lisez-la avec GET /v3/transactions/{uuid}/ en utilisant le uuid de la première réponse, ou utilisez le transaction_id (l’uuid Didit) que le webhook transaction.created transmet à côté de votre txn_id.
• Si la requête n’est pas une nouvelle tentative, donnez à la nouvelle transaction son propre transaction_id.

​

Règle qui ne se déclenche pas

Symptôme. Vous avez créé une règle qui devrait correspondre, mais aucune transaction n’apparaît dans rule_runs[] avec matched: true. Causes et solutions.

• L’application est en mode sandbox : une application sandbox ignore l’évaluation des règles, le filtrage AML, la facturation ainsi que les webhooks transaction.created et transaction.status.updated. Les échanges Travel Rule continuent de s’exécuter lorsqu’ils sont activés, avec le Didit Test VASP, et envoient des webhooks travel_rule.status.updated marqués environment: sandbox. rule_runs est renvoyé vide et le score reste à 0, quel que soit le mode de vos règles, et la transaction reste APPROVED, sauf si un transfert Travel Rule arrivé à expiration applique votre timeout_outcome. Vérifiez environment dans la réponse de la transaction : "sandbox" signifie qu’elle n’a jamais été évaluée. Consultez Surveillance des transactions en sandbox pour savoir comment valider une règle avant sa mise en production.
• Le mode de la règle est DISABLED ou TEST : vérifiez Rules → [rule] → Mode. Seules les règles ACTIVE contribuent au score ; les règles TEST évaluent les transactions mais n’affectent pas le statut.
• Le filtre de périmètre exclut la transaction : par exemple, un périmètre défini sur transaction_type = finance ne correspondra pas aux transactions travelRule.
• La fenêtre d’agrégation est trop courte : une règle « 20 transactions en 30 jours » ne se déclenchera pas après seulement 15 transactions.
• Le champ de condition est null : par exemple, votre règle vérifie counterparty.country_code, mais vous n’avez pas envoyé de contrepartie.
• Conversion de devise : la règle applique ses seuils à amount_in_default_currency. Si la devise par défaut de votre application diffère de la devise de la transaction, le montant converti peut être inférieur au seuil.

Utilisez la fonctionnalité Rules → [rule] → Backtest pour rejouer une transaction passée et voir pourquoi la règle s’est déclenchée ou non.

​

Règle qui se déclenche sur tout

Symptôme. Une règle se déclenche sur 90%+ des transactions : votre file d’attente d’examen est saturée. Cause. Les conditions sont trop larges, ou les seuils trop bas. Solution.

• Ajoutez des filtres scope pour réduire le champ d’application (par exemple uniquement les transactions sortantes, ou uniquement certains types de transactions).
• Relevez les seuils (montants, nombre d’opérations sur une période).
• Passez la règle en mode TEST pendant une semaine : analysez les rule_runs pour mesurer le taux de correspondance, puis resserrez les conditions avant de réactiver la règle.

​

Délai d’attente dépassé pour le filtrage crypto

Symptôme. La transaction est terminée avec status: APPROVED, mais le tableau provider_results[] affiche status: FAILED pour un portefeuille, un hash de transaction ou un fournisseur de filtrage crypto. Causes.

• L’API du fournisseur était brièvement indisponible.
• La requête a dépassé le délai d’attente (généralement environ 10 s).

Solution.

• Les transactions n’échouent jamais à cause de problèmes chez les fournisseurs : l’enrichissement est effectué au mieux.
• Si un fournisseur précis échoue de façon répétée, consultez sa page d’état ou ouvrez un ticket de support.
• Envisagez de configurer les préférences de fournisseurs dans Settings → Transaction Monitoring → Providers pour acheminer les requêtes vers d’autres fournisseurs.

​

Enrichissement IP manquant

Symptôme. L’élément applicant.ip_enrichment d’une transaction est absent ou incomplet. Causes.

• Aucun applicant.device.ip dans l’envoi.
• L’adresse IP est privée ou réservée (non routable).
• Tous les fournisseurs d’enrichissement étaient temporairement indisponibles.

Solution.

• Capturez l’adresse IP de l’utilisateur côté client ou serveur et transmettez-la pour chaque transaction.
• Utilisez uniquement des adresses IP routables : Didit ignore silencieusement les plages privées.
• Vérifiez l’état des fournisseurs dans Settings → Status de la console.

​

Signature de webhook non concordante

Symptôme. Votre endpoint rejette les événements car la signature ne correspond pas. Causes.

• Le corps brut a été modifié (JSON resérialisé avec des espaces différents).
• Mauvais secret.
• Plusieurs destinations avec la même URL : les signatures diffèrent selon la destination.

Solution.

• Signez le corps brut de la requête, et non le JSON analysé. De nombreux frameworks proposent un middleware de corps brut.
• Renouvelez le secret en cas de compromission : Webhook destinations → [destination] → Rotate secret.
• Gardez une seule destination par URL pour éviter toute confusion de secrets.

​

Webhook non reçu

Symptôme. Des transactions sont créées, mais les webhooks n’arrivent jamais. Causes.

• enabled de la destination vaut false.
• L’URL n’est pas accessible publiquement.
• La destination a été désactivée automatiquement après des échecs répétés.
• L’événement ne figure pas dans subscribed_events.

Solution.

• Envoyez un événement de test : Webhook destinations → [destination] → Send test.
• Consultez les livraisons récentes : Webhooks → [destination] → Deliveries. Vous y voyez les réponses 4xx/5xx avec le corps et les en-têtes.
• Réactivez les destinations désactivées.

​

La conversion de devise semble incorrecte

Symptôme. amount_in_default_currency ne correspond pas au taux attendu. Causes.

• Le taux de change est le taux médian du marché à txn_date.
• Les transactions antidatées utilisent le taux historique à cette date.
• Certaines devises (devises exotiques) ont des intervalles de mise à jour plus longs.

Solution.

• Utilisez amount et currency (devise d’origine) pour l’affichage.
• Utilisez amount_in_default_currency uniquement pour l’application de seuils dans les règles internes.
• Pour l’audit, l’enregistrement de la transaction fige le taux de conversion utilisé au moment de l’évaluation.

​

Contrepartie ne correspondant pas à ma liste de blocage

Symptôme. Vous avez ajouté une entreprise à votre liste de blocage par vendor_data, mais une transaction avec cette contrepartie a tout de même été exécutée. Causes.

• La contrepartie dans le payload de la transaction n’a pas de vendor_data : elle est enregistrée comme instantané externe.
• La casse de vendor_data diffère.

Solution.

• Transmettez toujours counterparty.vendor_data lorsque la contrepartie est une entité de votre plateforme.
• Utilisez la même casse partout : vendor_data est sensible à la casse.

​

Transactions AWAITING_USER bloquées

Symptôme. Les transactions restent bloquées en AWAITING_USER parce que l’utilisateur ne termine jamais la session de remédiation. Causes.

• L’utilisateur n’a pas ouvert l’URL de la session de remédiation.
• La session de remédiation a expiré.
• La transaction est un transfert Travel Rule qu’une règle de la bibliothèque, telle que travel-rule-pending-action, a fait passer en AWAITING_USER : Didit ne crée pas sa session de remédiation par défaut pour une transaction Travel Rule. Sauf si la règle désigne son propre workflow de remédiation, aucun lien ne peut donc être transmis.

Solution.

• Le remediation_session_url de la réponse de la transaction est le lien à transmettre. Renvoyez-le à l’utilisateur.
• Pour une transaction Travel Rule, traitez le transfert depuis l’onglet Travel rule, puis modifiez vous-même le statut de la transaction, car résoudre le transfert ne fait pas sortir la transaction de AWAITING_USER.
• Les sessions de remédiation suivent le même schéma que le démarrage rapide KYC : abonnez-vous aux webhooks de fin de session.
• Définissez un délai d’expiration dans votre propre système pour expirer les transactions obsolètes si la remédiation n’aboutit jamais.

​

Limite de débit à la création

Symptôme. Erreur 429 Too Many Requests lors de pics de trafic importants. Solution.

• Respectez l’en-tête Retry-After.
• Limitez le débit côté client pour les pics de trafic.
• Contactez le support pour obtenir des limites plus élevées sur un volume de production avéré.

Voir limitation de débit.

​

Étapes suivantes