> ## Documentation Index
> Fetch the complete documentation index at: https://docs.didit.me/llms.txt
> Use this file to discover all available pages before exploring further.

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

> Soumettez des transactions avec Didit pour une surveillance en temps réel. 1,000 par mois inclus, puis $0.001 chacun.

Soumettez des transactions à Didit via l'API [Créer une transaction](https://docs.didit.me/fr/management-api/transactions/create.md). 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.

> [!TIP]
>
> 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](https://docs.didit.me/fr/transaction-monitoring/sdk-transaction-submission.md) : 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](https://docs.didit.me/fr/management-api/users/list.md) ou à un [profil d'entreprise](https://docs.didit.me/fr/business-verification/business-profiles.md) |
| `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](https://docs.didit.me/fr/transaction-monitoring/travel-rule.md#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 |

> [!NOTE]
>
> `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.

```json theme={null}
"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](https://docs.didit.me/fr/transaction-monitoring/rules.md#référencer-les-propriétés-personnalisées) pour plus de détails.

## Exemple de requête

```bash theme={null}
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](https://docs.didit.me/fr/management-api/transactions/create.md) 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](https://docs.didit.me/fr/transaction-monitoring/response-schema.md) 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.

```bash theme={null}
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](https://docs.didit.me/fr/management-api/transactions/list.md) 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}/`](https://docs.didit.me/fr/management-api/transactions/get) 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](https://docs.didit.me/fr/transaction-monitoring/integration-guide.md#ingestion-de-l’historique).

## Étapes suivantes

> [card] [Règles et notation](https://docs.didit.me/fr/transaction-monitoring/rules.md)
>
> Comment les transactions soumises sont évaluées par rapport aux règles.

> [card] [Schéma de la réponse](https://docs.didit.me/fr/transaction-monitoring/response-schema.md)
>
> Payload de réponse complet et annoté.

> [card] [Filtrage crypto](https://docs.didit.me/fr/transaction-monitoring/aml-screening.md)
>
> Filtrage automatique des portefeuilles et des transactions pour les transactions crypto.

> [card] [Travel Rule](https://docs.didit.me/fr/transaction-monitoring/travel-rule.md)
>
> Joignez les données de conformité Travel Rule aux transferts d'actifs virtuels.

> [card] [Enrichissement IP](https://docs.didit.me/fr/transaction-monitoring/ip-enrichment.md)
>
> Contexte dérivé de l'IP disponible pour les règles.

> [card] [Référence de l'API](https://docs.didit.me/fr/management-api/transactions/create.md)
>
> Schéma complet de la requête pour l'endpoint de création de transaction.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.