Passer au contenu principal
Cette page détaille le payload complet renvoyé par POST /v3/transactions/ et GET /v3/transactions/{transaction_id}/. Les deux endpoints renvoient le même objet TransactionDetail ; la référence de l’API détaille le schéma champ par champ et cette page le présente en détail.

Structure de premier niveau

Deux identifiants décrivent la même transaction. uuid est l’identifiant stable de Didit et correspond à ce que GET /v3/transactions/{transaction_id}/ attend dans son chemin ; txn_id est le transaction_id que vous avez fourni lors de la création. transaction_number est le numéro séquentiel propre à l’application qu’affiche la console. Le sujet et la contrepartie que vous avez soumis ne sont pas renvoyés sous forme de clés de premier niveau. Il s’agit des entrées du tableau parties, distinguées par role, et vendor_data au premier niveau est une copie pratique du vendor_data du demandeur.

Champs clés

Champs financiers

  • amount / currency — montant de la transaction tel qu’il a été transmis. amount est une chaîne décimale débarrassée de ses zéros finaux ("1500", "0.5"), pouvant comporter jusqu’à 18 décimales.
  • currency_type — fiat ou crypto, tel que soumis dans currency_kind ; null en cas d’omission.
  • amount_in_default_currency / default_currency_code — montant pré-converti que vous avez fourni dans la requête, renvoyé tel quel ; null si vous n’en avez pas transmis.
  • preferred_currency_amount / preferred_currency_code — amount converti dans la devise préférée de votre application. null lorsqu’aucun taux de change n’est disponible pour currency et que vous n’avez pas fourni amount_in_default_currency.
  • payment_details / payment_txn_id — la référence de paiement en texte libre et la référence de paiement externe (par exemple un hash de transaction de blockchain) provenant de la requête.

Champs d’état

  • status — APPROVED, IN_REVIEW, DECLINED, AWAITING_USER. Les transactions sont créées avec le statut APPROVED ; les règles peuvent le faire basculer de manière synchrone.
  • score — score de risque sous forme d’entier cumulé par les règles. Plus il est élevé, plus le risque est grand.
  • severity — UNKNOWN, LOW, MEDIUM, HIGH, CRITICAL, ou null jusqu’à ce qu’une règle ou un fournisseur la définisse.
  • decision_reason_code / decision_reason_label — motif structuré et lisible par un humain justifiant le statut actuel.
  • environment - live ou sandbox, issu de l’application à laquelle appartient la transaction. Une transaction sandbox est enregistrée mais n’est jamais évaluée, de sorte que son tableau rule_runs vide signifie « non évaluée » plutôt que « aucune correspondance ». Voir Surveillance des transactions dans la sandbox.
  • source - LIVE pour les transactions transmises via l’API ou le SDK, IMPORTED pour les transactions chargées par l’import CSV de la console.

Parties

Chaque partie prenante de la transaction constitue une entrée dans parties. L’endpoint de création enregistre le sujet sous APPLICANT et la contrepartie facultative sous COUNTERPARTY ; l’enum role inclut également REMITTER et BENEFICIARY. Toutes les entrées partagent la même structure.
  • role — APPLICANT, COUNTERPARTY, REMITTER, BENEFICIARY. Filtrez sur ce champ pour trouver le sujet.
  • entity_type — individual, company, external, unhostedWallet, tel que soumis.
  • kind — USER ou BUSINESS lorsque la partie est liée à un utilisateur ou à une entreprise Didit via vendor_data ; EXTERNAL dans le cas contraire.
  • country_code / dob — issus des champs address.country et date_of_birth soumis.
  • address / institution_info — les objets tels qu’ils ont été soumis ; {} en cas d’omission.
  • external_party_snapshot — copie figée des données de la partie pour les parties EXTERNAL ; null tant que la partie est liée à un utilisateur ou à une entreprise Didit.

device

device correspond au device_context que vous avez soumis pour cette partie, normalisé en snake_case, auquel s’ajoute l’enrichissement de l’IP côté serveur. Il vaut {} lorsque la requête ne comportait aucun contexte d’appareil : traitez donc toujours chaque clé comme optionnelle. Il n’y a pas d’objet d’enrichissement distinct. Lorsque la partie comportait une adresse network_context.ip_address publique, Didit la résout directement et inscrit les champs enrichis dans ce même objet network_context, en ne renseignant que les clés que vous n’avez pas fournies. Les clés pour lesquelles le résolveur n’a renvoyé aucune valeur sont omises, de sorte qu’un network_context entièrement enrichi contient les quatre clés soumises (ip_address, ip_country_code, latitude, longitude) ainsi que celles résolues parmi ip_country, ip_state, ip_city, isp, organization, is_vpn_or_tor, is_data_center, time_zone, time_zone_offset, asn_number, asn_organization, connection_type, carrier et proxy_type. is_vpn_or_tor et is_data_center sont toujours présents après une résolution réussie. L’enrichissement est ignoré et network_context est renvoyé exactement tel qu’il a été soumis lorsque l’IP est manquante ou non routable, lorsque l’application est en sandbox ou lorsque la résolution a échoué. ip_country_code est un code ISO 3166-1 alpha-2 lorsque Didit l’a résolu, ou la valeur que vous avez fournie dans le cas contraire ; les conditions des règles normalisent les deux formes avant de les comparer.

Moyens de paiement

  • role — SOURCE, DESTINATION, FUNDING, BENEFICIARY. L’endpoint de création attribue SOURCE / DESTINATION d’après direction : sur une transaction sortante, le moyen de paiement du sujet est la SOURCE et celui de la contrepartie est la DESTINATION ; sur une transaction entrante, c’est l’inverse.
  • payment_method_type — bank_card, bank_account, e_wallet, crypto_wallet, unhosted_wallet, other.
  • fingerprint — SHA-256 sur type:account_id:issuing_country, stable d’une transaction à l’autre afin que vous puissiez corréler la réutilisation d’un même instrument. null si aucun account_id n’a été soumis.
  • owner_kind / vendor_data / owner_name — propriétaire de l’instrument, suivant la même convention USER / BUSINESS / EXTERNAL que pour les parties.
  • details — l’objet brut payment_method tel qu’il a été soumis.

Exécutions de règles

  • rule — UUID de la règle qui s’est exécutée ; rule_title, rule_description, rule_category en sont copiés.
  • matched — une exécution n’est enregistrée que lorsque les conditions de la règle ont été satisfaites, de sorte que les évaluations en production comportent toujours matched: true. Les règles évaluées sans correspondance ne laissent aucune entrée. Les données de démonstration peuvent inclure des lignes avec matched: false.
  • is_test / mode — true et TEST lorsque la règle a tourné en mode test ; une exécution de test est enregistrée mais n’a aucun effet sur status, score ou severity.
  • score_delta / status_target / severity — ce que cette exécution a apporté. status_target est défini lorsqu’une action change_status a été exécutée ou lorsque le score ajouté a franchi un seuil.
  • action_summary — résumé textuel des actions exécutées par la règle, séparées par ; (score +30, change_status:IN_REVIEW, add_tag:<name>, add_note, add_to_list, open_case) ; null lorsque la règle n’a exécuté aucune action.
  • metadata — le détail de l’évaluation : scope_match, ainsi que conditions[] et aggregations[]. Les deux listes utilisent des clés de valeurs distinctes :
    • conditions[] — une entrée par condition avec field, operator, expected_value, la current_value lue sur la transaction, matched, group_index et group_logic. field_source vaut toujours null lors des exécutions de règles de transactions ; il n’est classé que pour les événements de surveillance.
    • aggregations[] — une entrée par agrégation de vélocité / comptage / somme avec metric, field, operator, expected_value, la computed_value obtenue par le calcul de l’agrégat, window, filters, matched et sample_references. Les agrégations qui ne pouvaient être calculées que de manière asynchrone portent computed_value: null et deferred: true.

Alertes

alerts est toujours un tableau vide aujourd’hui. Une alerte ouverte est une transaction mise en attente, lisez donc plutôt status (IN_REVIEW ou AWAITING_USER). Voir Alertes.

Activités

Le journal d’activité de la transaction : création, notes, examens manuels et changements de statut.
Les notes d’analyste apparaissent ici sous forme d’entrées TRANSACTION_NOTE_ADDED ; il n’y a pas de tableau notes séparé.

Documents

Fichiers joints à la transaction depuis la console. [] lorsqu’il n’y en a aucun.
file_url est une URL signée à courte durée de vie ; récupérez-la lorsque vous en avez besoin plutôt que de la stocker.

Résultats des fournisseurs

Résultats des fournisseurs externes (filtrage de hash de transaction, filtrage de portefeuille, surveillance fiat, filtrage des sanctions).
result_type : FIAT_MONITORING, WALLET_SCREENING, TRANSACTION_SCREENING, TRAVEL_RULE, NETWORK_GRAPH, CUSTOM. payload.risk_factors est l’explication hiérarchisée de score — ce qui a produit le verdict, les facteurs à haut risque en premier puis par valeur transférée. Un score élevé sans entrée is_high_risk signifie que le fournisseur a noté l’entité selon son propre modèle d’exposition sans signaler de correspondance avec des sanctions ou une entité attribuée ; summary l’indique explicitement. Référence champ par champ : Facteurs de risque. Les résultats filtrés avant que ce champ n’existe omettent la clé. Pour le filtrage de hash de transactions crypto, transaction_flows est alimenté lorsque l’enrichissement on-chain est disponible. Il normalise l’activité de la chaîne afin que la console puisse afficher à la fois la vue d’ensemble de la transaction et le graphe de visualisation à partir du même payload de réponse. Sources d’enrichissement prises en charge :
  • Les chaînes EVM utilisent Blockscout pour normaliser la transaction principale, les appels internes et les transferts de tokens.
  • Bitcoin utilise mempool.space pour normaliser les entrées et sorties de transaction.
  • Solana utilise Helius pour normaliser les transferts natifs de SOL, les transferts de tokens SPL et le contexte d’événements NFT disponible.
Chaque élément de transaction_flows[] comprend des champs normalisés stables (flow_type, from_address, to_address, amount, amount_usd, currency, token_name, token_address, transaction_hash, block_timestamp, index, success) ainsi que des metadata spécifiques au fournisseur. Exemples courants de metadata :
metadata est additif et spécifique au fournisseur. Ne construisez pas d’intégrations critiques qui nécessitent que chaque clé soit présente pour chaque chaîne.

Travel Rule

null lorsque la transaction ne comporte aucun transfert ou contrôle Travel Rule. Il est renseigné lorsque vous transmettez travel_rule_details, ainsi que lorsque Travel Rule est activé pour l’application et que la transaction a été créée avec transaction_category: "travelRule" : Didit initie alors l’échange lui-même, avec ou sans travel_rule_details, et rapporte son status ici. Lisez ce champ plutôt que la requête que vous avez envoyée. Sur un transfert entrant, les champs originator_data et beneficiary_data de la contrepartie restent masqués (data_masked: true) jusqu’à ce que la propriété du portefeuille soit confirmée (voir Données de contrepartie masquées).
direction, rail, counterparty_vasp, delivery, discovery, reason et next_actions ont le même format que sur l’endpoint de transfert. reason et next_actions indiquent pourquoi un transfert COUNTERPARTY_VASP_NOT_FOUND ou COUNTERPARTY_VASP_NOT_REACHABLE est bloqué et ce qui permet de le faire avancer, et valent "" et [] pour tout autre statut : voir Pourquoi un transfert est bloqué. Chaque ligne de GET /v3/transactions/ contient le même bloc. Voir Travel Rule.

Instantané du réseau

Le graphe stocké lui-même, pas une référence vers celui-ci. Il provient de l’une ou l’autre de ces sources :
  • un network_snapshot que vous avez soumis avec la transaction, ou
  • le graphe que Didit construit lorsque le filtrage AML des portefeuilles réussit pour une transaction crypto, même si la requête ne comportait aucun network_snapshot. Un graphe généré par filtrage remplace un graphe soumis, et un nouveau filtrage asynchrone le rafraîchit.
null lorsque ni l’un ni l’autre n’existe :
La page de détails de transaction de la console affiche le même graphe.

Tags, métadonnées, propriétés

  • tags[] — tags attachés (soit par une action de règle, soit par un analyste) : { "uuid", "name", "color", "description", "source" }, où source vaut didit pour un tag prédéfini et custom pour l’un des vôtres.
  • metadata — un instantané des payloads subject et counterparty exactement tels que vous les avez soumis au moment de la création, sous ces deux clés.
  • props — les custom_properties que vous avez fournies au moment de la création. Chaque clé est accessible dans les conditions de règles sous la forme custom_values.<key>.

Remédiation

Lorsqu’une règle déclenche AWAITING_USER, Didit crée la session de vérification associée et la renvoie dans deux champs :
  • remediation — la session associée : { "session_id", "session_token", "url", "status" }. Reste renseignée pendant toute la durée de vie de la transaction, afin que vous puissiez toujours voir comment s’est terminée l’action de l’utilisateur.
  • action_required — l’action que l’utilisateur doit entreprendre dès maintenant, ou null dès que plus rien n’est en attente : { "type": "verification_session", "url", "session_id", "session_token", "status" }. Redirigez l’utilisateur vers url, ou fournissez session_token à un SDK Didit. Les actions de propriété de portefeuille Travel Rule utilisent { "type": "wallet_ownership", "url", "widget_session_id", "expires_at" } et prévalent lorsque les deux pourraient s’appliquer. Lorsqu’une action de propriété de portefeuille est en attente et que la contrepartie du transfert n’a pas pu être trouvée, le même bloc comporte également reason et next_actions (voir découverte de contrepartie).
Ces deux mêmes champs sont présents sur les payloads de webhook transaction.created et transaction.status.updated (action_required) - voir webhooks.

Détail des coûts

null jusqu’à ce qu’une fonctionnalité facturable ait été exécutée pour la transaction. Sinon { "total_price", "items": [ { "usage_type", "price", "details" } ] }, un élément par fonctionnalité décomptée (filtrage, enrichissement, et ainsi de suite).

Conversion de devises

preferred_currency_amount correspond à amount converti dans la devise préférée de votre application aux taux moyens du marché, sauf si vous avez fourni amount_in_default_currency, auquel cas cette valeur pré-convertie est utilisée telle quelle. Les conditions de règles basées sur amount comparent le montant natif ; utilisez preferred_currency_amount dans les conditions lorsque vous avez besoin d’un seuil unique pour toutes les devises.

Prochaines étapes

Soumettre des transactions

Schéma complet de la requête.

Statuts

Signification de chaque statut.

Score de risque

Comment le score est calculé.
Dernière modification le 7 novembre 2026