API de soumission des transactions : payload et modèle de données

Soumettez des transactions à Didit via l’API Créer une transaction. Chaque transaction comprend des données structurées sur les parties, le paiement et le contexte, que le moteur de règles évalue en temps réel.

Lorsque la transaction provient de l’appareil d’un utilisateur final – par exemple un retrait de cryptomonnaie ou un paiement dans l’application –, envisagez la soumission de transaction via le SDK : un token limité remplace la clé API, les données de l’appareil sont collectées automatiquement, et les actions requises de l’utilisateur (preuve de propriété du portefeuille, vérification renforcée) se lancent immédiatement.

Catégories de transactions

Chaque transaction possède un transaction_category qui détermine la manière dont les règles et les analyses la traitent :

Catégorie	Description
`finance`	Transaction financière standard (dépôt, retrait, virement)
`kyc`	Événement lié à la vérification d’identité
`travel_rule`	Transfert d’actifs virtuels soumis à la conformité Travel Rule
`user_event`	Événement personnalisé de la plateforme (connexion, modification de profil, etc.)
`gambling_bet`	Mise ou pari de jeu
`gambling_limit_change`	Modification de la limite de dépôt, de perte ou de mise d’un joueur
`gambling_bonus_change`	Attribution, utilisation ou perte d’un bonus
`audit_trail_event`	Événement d’audit système ou de conformité

Détails de la transaction

L’objet transaction_details contient les données financières :

Champ	Type	Description
`direction`	chaîne	`inbound` ou `outbound`
`amount`	chaîne	Valeur de la transaction sous forme de chaîne décimale (par exemple `"1500.50"`)
`currency`	chaîne	Code de devise ISO (par exemple `USD`, `EUR`, `BTC`)
`currency_kind`	chaîne	`fiat` ou `crypto` (alias `currencyType`) ; détermine si le filtrage crypto se déclenche
`action_type`	chaîne	Libellé d’action défini par le fournisseur (par exemple `deposit`, `withdrawal`, `purchase`)
`payment_details`	chaîne	Description libre du paiement (par exemple `"Bank transfer from ABC Corp"`)
`payment_reference_id`	chaîne	Identifiant de référence externe du paiement. Pour le filtrage crypto après transfert, utilisez le hash de la transaction blockchain.

Sujet et contrepartie

Chaque transaction a un sujet (obligatoire) et une contrepartie (facultative). Les deux utilisent le même modèle de partie :

Champ	Type	Description
`entity_type`	chaîne	`person` ou `company`
`vendor_data`	chaîne	Votre identifiant pour cette partie : il relie la transaction à un utilisateur ou à un profil d’entreprise
`full_name`	chaîne	Nom complet de la partie
`first_name`	chaîne	Prénom
`last_name`	chaîne	Nom de famille
`date_of_birth`	chaîne	Date ISO (par exemple `1990-01-15`)
`country_code`	chaîne	Code pays ISO 3166-1 alpha-2
`address`	objet ou chaîne	Adresse structurée avec `street`, `city`, `state`, `country`, `postal_code`. Accepte aussi une simple chaîne, comme une adresse pour une contrepartie crypto : Didit la conserve telle quelle dans les données de la partie.

Didit déduit le country_code de la partie à partir de address.country lorsque address est un objet. Lorsque address est une chaîne, country_code est renvoyé null pour cette partie. Lorsque vendor_data correspond à un utilisateur existant ou à une entreprise existante, Didit relie automatiquement la transaction au profil de cette entité, ce qui permet l’évaluation des règles entre sessions et les contrôles de vélocité. Dans la réponse, les deux parties sont renvoyées dans le tableau parties, avec les rôles APPLICANT et COUNTERPARTY.

Moyens de paiement

Associez un payment_method à chaque partie pour décrire l’instrument de ce côté :

Champ	Type	Description
`method_type`	chaîne	`bank_card`, `bank_account`, `e_wallet`, `crypto_wallet`, `unhosted_wallet` ou `other` (alias `type`) ; `ewallet`, `card` et `crypto` sont acceptés comme alias, et une valeur non reconnue est enregistrée comme `other`
`account_id`	chaîne	Numéro de compte, adresse ou token de carte
`issuing_country`	chaîne	Pays ayant émis l’instrument de paiement

Sur les transactions travelRule, un moyen de paiement de contrepartie avec method_type: "unhosted_wallet" (alias type) déclare le portefeuille de la contrepartie comme auto-hébergé. Lorsque Travel Rule est activée et que le montant, exprimé dans la devise par défaut de votre application, n’est pas inférieur à threshold_amount, le transfert passe directement à UNCONFIRMED_OWNERSHIP et au flux de preuve de propriété – voir Portefeuilles auto-hébergés déclarés. Pour les transactions crypto, incluez les adresses de portefeuille dans account_id et définissez currency_kind sur crypto afin que le filtrage blockchain puisse s’exécuter automatiquement. Le sens de la transaction détermine le portefeuille filtré : le filtrage entrant avant transfert utilise le portefeuille de l’expéditeur dans counterparty.payment_method.account_id ; le filtrage sortant utilise le portefeuille de destination dans counterparty.payment_method.account_id. Si vous envoyez un hash blockchain dans transaction_details.payment_reference_id, le filtrage de transaction entrante exige l’adresse de dépôt de votre service dans subject.payment_method.account_id, tandis que le filtrage de transaction sortante exige le portefeuille de destination dans counterparty.payment_method.account_id.

Remplacement du filtrage crypto

Utilisez include_crypto_screening au niveau racine de la requête pour remplacer la valeur par défaut configurée dans Transactions > Paramètres de la Console :

Valeur	Description
`true`	Force le filtrage crypto pour cette transaction
`false`	Ignore le filtrage crypto pour cette transaction
omis ou `null`	Utilise la valeur par défaut au niveau de l’application

Contexte de l’appareil

Incluez les informations sur l’appareil pour la partie sujet (et, facultativement, pour la contrepartie) afin d’alimenter les règles d’intelligence sur l’appareil. Le champ de requête est device_context sur chaque partie. L’alias en camelCase device est également accepté et c’est celui qu’utilise le format filaire du SDK. La réponse le renvoie sous la forme device sur chaque partie, dans le tableau parties.

Champ	Type	Description
`device_context.fingerprint`	string	Empreinte unique de l’appareil
`device_context.persistent_device_id`	string	Identifiant d’appareil stable entre les sessions (schéma d’empreinte v2)
`device_context.user_agent`	string	Chaîne user agent du navigateur ou de l’application
`device_context.browser_family`	string	Famille du navigateur (par exemple `Chrome`, `Firefox`, `Safari`). Doit être envoyé explicitement : il n’est pas déduit de `user_agent`. Alimente des règles comme `subject_browser_family`.
`device_context.browser_version`	string	Version du navigateur (par exemple `131.0`). Doit être envoyé explicitement.
`device_context.platform`	string	Identifiant de la plateforme (`web`, `ios`, `android`, `macos`, `windows`, `linux`). Doit être envoyé explicitement : il n’est pas déduit de `user_agent`. Alimente des règles comme `subject_platform`.
`device_context.os_family`	string	Famille du système d’exploitation (par exemple `iOS`, `Android`, `Windows`)
`device_context.os_version`	string	Version du système d’exploitation
`device_context.accept_language`	string	Valeur de l’en-tête Accept-Language (par exemple `en-US,en;q=0.9`). Dans le parcours du SDK, elle est collectée automatiquement.
`device_context.session_id`	string	Identifiant de la session en cours de l’utilisateur. Stocké dans les métadonnées. Alias en CamelCase : `sessionId`.
`device_context.session_age_ms`	number	Âge de la session de l’utilisateur, en millisecondes, au moment de la transaction. Alimente des règles comme `subject_session_age_ms`.
`device_context.network_context.ip_address`	string	Adresse IP du client
`device_context.network_context.ip_country_code`	string	Pays de l’IP déterminé par géolocalisation (ISO 3166-1 alpha-3)
`device_context.network_context.latitude`	number	Latitude géographique de l’IP
`device_context.network_context.longitude`	number	Longitude géographique de l’IP

browser_family et platform ne sont pas déduits de user_agent. Ils doivent être envoyés comme clés de premier niveau explicites dans device_context pour que les règles d’intelligence sur l’appareil se déclenchent. Si vous utilisez le SDK Didit, ces champs sont collectés automatiquement.

Les alias en CamelCase sont acceptés pour chaque champ : userAgent, browserFamily, browserVersion, osFamily, osVersion, acceptLang, sessionId, sessionAgeMs. L’objet network_context accepte les alias ip, countryCode3, lat et lon, et un bloc ipInfo de premier niveau est également intégré à network_context. Le contexte de l’appareil permet d’appliquer des règles comme la détection de multicomptes (même empreinte pour des sujets différents), la détection de la combinaison d’un nouveau navigateur et d’une nouvelle IP, le transfert à forte valeur avec un âge de session faible et la notation de risque fondée sur la localisation.

Propriétés personnalisées

Ajoutez toutes les paires clé-valeur supplémentaires dans l’objet custom_properties. Les règles peuvent référencer ces champs dans leurs conditions. C’est utile pour transmettre un contexte propre à votre activité, comme la catégorie de produit, l’identifiant du marchand ou le canal.

"custom_properties": {
  "product_category": "electronics",
  "merchant_id": "MER456",
  "channel": "mobile_app"
}

Dans les conditions de règle, référencez chaque clé avec le chemin de champ custom_values.<key>. Par exemple, le payload ci-dessus correspond à custom_values.product_category eq "electronics". Dans le constructeur de règles de la Console, les clés vues sur les transactions ingérées récemment apparaissent dans le sélecteur de champs de condition sous Propriétés personnalisées. Dans le même groupe, Saisir une propriété personnalisée vous permet de saisir manuellement n’importe quelle clé (sensible à la casse). Voir Règles et notation pour plus de détails.

Exemple de requête

curl -X POST https://verification.didit.me/v3/transactions/ \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "transaction_id": "TXN-20260410-001",
    "transaction_at": "2026-04-10T15:30:00Z",
    "transaction_category": "finance",
    "transaction_details": {
      "direction": "outbound",
      "amount": "1500.50",
      "currency": "EUR",
      "currency_kind": "fiat",
      "action_type": "withdrawal"
    },
    "subject": {
      "entity_type": "person",
      "vendor_data": "user-123",
      "full_name": "John Doe",
      "country_code": "US",
      "payment_method": {
        "method_type": "bank_account",
        "account_id": "DE89370400440532013000",
        "issuing_country": "DE"
      }
    },
    "counterparty": {
      "entity_type": "company",
      "full_name": "John Doe",
      "country_code": "GB"
    },
    "custom_properties": {
      "order_id": "ORD-7891"
    }
  }'

Réponse

L’API renvoie la transaction créée avec ses résultats d’évaluation initiaux :

Champ	Type	Description
`uuid`	string	Identifiant unique de la transaction chez Didit
`txn_id`	string	Identifiant de transaction que vous avez fourni
`status`	string	`APPROVED`, `IN_REVIEW`, `DECLINED` ou `AWAITING_USER`
`score`	number	Score de risque cumulé de toutes les règles déclenchées
`severity`	string	Gravité la plus élevée parmi les règles déclenchées (`LOW`, `MEDIUM`, `HIGH`, `CRITICAL`)
`decision_reason_code`	string	Motif de la décision de statut, lisible par une machine
`decision_reason_label`	string	Description de la décision, lisible par un humain

Consultez la Référence de l’API pour le schéma complet de la requête et de la réponse, et la référence du schéma de réponse pour un exemple de charge utile annoté, pas à pas.

Assigner une transaction à un réviseur

Assignez une transaction en attente à un membre de votre application, ou retirez-lui son assignation, avec une clé API disposant du privilège write:transactions. Chaque modification est enregistrée dans l’historique de la transaction sous la forme TRANSACTION_ASSIGNED.

Appel	Usage
`POST /v3/transactions/{transaction_uuid}/assign/`	Assigner une transaction.
`POST /v3/transactions/assign/`	Assigner jusqu’à 500 transactions à un même membre.

Les deux appels prennent assignee_email, l’adresse e-mail d’un membre de l’application qui s’est connecté à Didit. Envoyez null ou une chaîne vide pour retirer l’assignation. L’appel groupé prend aussi transaction_ids, une liste de 1 à 500 UUID de transactions.

curl -X POST "https://verification.didit.me/v3/transactions/assign/" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"transaction_ids": ["<transaction-uuid>"], "assignee_email": "analyst@example.com"}'

L’appel unique renvoie uuid, transaction_number, assignee et changed (false lorsque la transaction était déjà assignée à ce membre), ou 404 lorsque la transaction n’existe pas dans l’application. L’appel groupé renvoie transactions (une entrée au format ci-dessus), updated_count et not_found_transaction_ids. Filtrez la liste des transactions avec assignee, une liste séparée par des virgules dont une valeur peut correspondre : me, unassigned, rules (décidée uniquement par les règles, sans intervention d’un réviseur) ou une adresse e-mail de membre.

Idempotence

txn_id (le transaction_id que vous envoyez) est unique par application. Soumettre à nouveau un transaction_id déjà existant renvoie un 400 avec A transaction with this transaction_id already exists. sur le champ transaction_id, et deux requêtes identiques envoyées en parallèle donnent un 409 à la seconde. Aucune de ces réponses ne renvoie la transaction existante. Pour réessayer en toute sécurité, traitez un 400 ou un 409 pour un transaction_id en double comme « déjà créée » et recherchez la transaction existante au lieu de la soumettre à nouveau : 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. Générez toujours le txn_id de votre côté (par exemple l’identifiant de votre base de données de transactions, un UUID ou un hash déterministe).

Reprise historique

Transmettez un txn_date antérieur pour ingérer des transactions historiques. Les règles sont tout de même évaluées par défaut. Utilisez l’import CSV depuis la console avec le mode d’ingestion à blanc (dry-ingest) si vous souhaitez ignorer l’évaluation des règles lors de chargements historiques en masse. Voir le guide d’intégration.

Étapes suivantes

Règles et notation

Comment les transactions soumises sont évaluées par rapport aux règles.

Schéma de la réponse

Payload de réponse complet et annoté.

Filtrage crypto

Filtrage automatique des portefeuilles et des transactions pour les transactions crypto.

Travel Rule

Joignez les données de conformité Travel Rule aux transferts d’actifs virtuels.

Enrichissement IP

Contexte dérivé de l’IP disponible pour les règles.

Référence de l'API

Schéma complet de la requête pour l’endpoint de création de transaction.

Prise en main

Fonctionnalités

Référence

Console

API de soumission des transactions : payload et modèle de données

Catégories de transactions

Détails de la transaction

Sujet et contrepartie

Moyens de paiement

Remplacement du filtrage crypto

Contexte de l’appareil

Propriétés personnalisées

Exemple de requête

Réponse

Assigner une transaction à un réviseur

Idempotence

Reprise historique

Étapes suivantes

Règles et notation

Schéma de la réponse

Filtrage crypto

Travel Rule

Enrichissement IP

Référence de l'API

​Catégories de transactions

​Détails de la transaction

​Sujet et contrepartie

​Moyens de paiement

​Remplacement du filtrage crypto

​Contexte de l’appareil

​Propriétés personnalisées

​Exemple de requête

​Réponse

​Assigner une transaction à un réviseur

​Idempotence

​Reprise historique

​Étapes suivantes

Règles et notation

Schéma de la réponse

Filtrage crypto

Travel Rule

Enrichissement IP

Référence de l'API

Catégories de transactions

Détails de la transaction

Sujet et contrepartie

Moyens de paiement

Remplacement du filtrage crypto

Contexte de l’appareil

Propriétés personnalisées

Exemple de requête

Réponse

Assigner une transaction à un réviseur

Idempotence

Reprise historique

Étapes suivantes