> ## 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.

# Интеграция мониторинга транзакций: KYT API

> Didit KYT: архитектура и лучшие практики мониторинга транзакций. 1,000 в месяц включено, затем $0.001 за каждый.

Это руководство охватывает весь интерфейс интеграции «Мониторинга транзакций». [Быстрый старт](https://docs.didit.me/ru/transaction-monitoring/quickstart.md) поможет запустить интеграцию, а эта страница описывает всё необходимое для выхода в продакшн.

## Архитектура

```mermaid theme={null}
sequenceDiagram
    participant You as Your platform
    participant Didit as Didit API
    participant Rules as Rule engine
    participant AML as AML providers
    participant Webhook as Your webhook

    You->>Didit: POST /v3/transactions/ (txn_id, parties, amount)
    Didit->>Didit: IP enrichment (inline)
    Didit->>AML: Screen wallet or transaction hash + address
    AML-->>Didit: Hits / clean
    Didit->>Rules: Evaluate all active rules
    Rules-->>Didit: Score + matched rules + actions
    Didit-->>You: Transaction record with status
    Didit->>Webhook: transaction.created
    Didit->>Webhook: transaction.status.updated (if async rules)
```

## Аутентификация

Используется стандартный заголовок `x-api-key`. Те же ключи применяются для сессий и сущностей. См. [аутентификация API](https://docs.didit.me/ru/getting-started/api-authentication.md).

## Отправка транзакции

Единственный endpoint: `POST /v3/transactions/`. Полную схему см. в разделе [отправка транзакций](https://docs.didit.me/ru/transaction-monitoring/transactions.md).

**Минимальный payload:**

```json theme={null}
{
  "transaction_id": "tx-0001",
  "transaction_category": "finance",
  "transaction_details": {
    "direction": "outbound",
    "amount": "500.00",
    "currency": "EUR"
  },
  "subject": { "entity_type": "person", "vendor_data": "user-42", "full_name": "John Doe" },
  "counterparty": { "entity_type": "company", "full_name": "Acme Corp" }
}
```

**Расширенный payload с методами оплаты, контекстом устройства и пользовательскими свойствами:**

```json theme={null}
{
  "transaction_id": "tx-0002",
  "transaction_at": "2026-04-16T10:00:00Z",
  "transaction_category": "finance",
  "transaction_details": {
    "direction": "outbound",
    "amount": "12500.00",
    "currency": "USD",
    "action_type": "withdrawal"
  },
  "subject": {
    "entity_type": "person",
    "vendor_data": "user-42",
    "full_name": "John Doe",
    "country_code": "US",
    "device_context": {
      "fingerprint": "fp-9f2c...",
      "user_agent": "Mozilla/5.0 ...",
      "browser_family": "Chrome",
      "platform": "web",
      "network_context": { "ip_address": "203.0.113.5" }
    },
    "payment_method": {
      "method_type": "bank_account",
      "account_id": "US12345678901234567890",
      "issuing_country": "US"
    }
  },
  "counterparty": {
    "entity_type": "company",
    "vendor_data": "biz-acme",
    "full_name": "Acme Corp",
    "country_code": "US",
    "payment_method": {
      "method_type": "bank_account",
      "account_id": "US09876543210987654321",
      "issuing_country": "US"
    }
  },
  "custom_properties": {
    "invoice_id": "INV-2026-00042",
    "category": "b2b_goods"
  }
}
```

Для каждого поля верхнего уровня принимаются псевдонимы в camelCase (`txnId`, `txnDate`, `type`, `info`, `applicant`, `props`, `travelRule`, `includeCryptoScreening`). Формат передачи данных SDK и формат snake\_case попадают в одно и то же место.

## Моделирование сторон

У каждой транзакции есть обязательное поле `subject` (ваш клиент, которого вы отслеживаете) и необязательное поле `counterparty` (другая сторона). У каждой из них свой `payment_method` и необязательный контекст `device`.

В ответе они приходят в массиве `parties` с ролями `APPLICANT` и `COUNTERPARTY`. Сторона без `vendor_data` сохраняется как внешний снимок (`kind: EXTERNAL`) без связанной сущности.

Поля сторон см. в разделе [payload транзакций](https://docs.didit.me/ru/transaction-monitoring/transactions.md).

## Идемпотентность

`txn_id` (то есть `transaction_id`, который вы отправляете) уникален в рамках приложения.
Повторная отправка существующего `transaction_id` возвращает `400` с сообщением `A transaction with this transaction_id already exists.` в поле `transaction_id`. Если два одинаковых запроса выполняются одновременно, второй получает `409`.
Ни один из этих ответов не возвращает существующую транзакцию.
При ответе `400` или `409` для дублирующегося `transaction_id` не отправляйте запрос повторно, а найдите существующую транзакцию. Прочитайте её через [`GET /v3/transactions/{uuid}/`](https://docs.didit.me/ru/management-api/transactions/get), используя `uuid` из первого ответа, или используйте `transaction_id` (uuid Didit), который событие `transaction.created` передаёт рядом с вашим `txn_id`.

**Всегда генерируйте `txn_id` на своей стороне** до отправки. Не полагайтесь на ID, который генерирует Didit, для идемпотентности. Используйте собственный ID из базы данных, UUID или хеш полей транзакции.

## Реальное время и пакетная обработка

* **Реальное время**: рекомендуется для большинства сценариев. Отправляйте транзакцию в момент её появления в вашей системе. Правила выполняются синхронно и возвращают решение.
* **Пакетная обработка и загрузка истории**: для импорта исторических данных передавайте `txn_date` в прошлом. Правила всё равно выполняются и могут запускать webhook. Чтобы не запускать правила при загрузке истории, используйте импорт CSV в консоли с флагом "dry ingest".

## Импорт исторических данных

Если вы переходите с другой системы мониторинга транзакций:

1. Экспортируйте исторические транзакции в CSV.
2. Используйте *Transactions → Import history* в консоли (или отправляйте данные через API в цикле) с `txn_date` в прошлом.
3. Включайте правила только после завершения импорта или используйте dry ingest, чтобы пропустить выполнение правил.

> [!WARNING]
>
> Продумайте выполнение правил на исторических данных. Прогон данных за шесть месяцев через правило "20 переводов за 30 дней" создаст тысячи оповещений сразу.

## Webhook

Подпишитесь на:

* `transaction.created`: каждая отправленная транзакция.
* `transaction.status.updated`: изменения статуса (например, когда аналитик переводит транзакцию из `IN_REVIEW` в `APPROVED` или когда асинхронная проверка AML обновляет оценку).

Подробнее: [webhook TM](https://docs.didit.me/ru/transaction-monitoring/webhooks.md).

```typescript theme={null}
app.post('/webhooks/didit-tm', (req, res) => {
  if (!verifySignature(req)) return res.status(401).end();

  const { webhook_type, status, txn_id } = req.body;
  if (webhook_type === 'transaction.status.updated' && status === 'DECLINED') {
    suspendTransaction(txn_id);
  }
  res.status(200).end();
});
```

## Обработка статусов

| Статус | Что делать |
| - | - |
| `APPROVED` | Обрабатывайте транзакцию как обычно. |
| `IN_REVIEW` | Задержите транзакцию до завершения проверки аналитиком или автоматической повторной проверки. |
| `DECLINED` | Отклоните транзакцию. Покажите пользователю общее сообщение об ошибке. |
| `AWAITING_USER` | Пользователь должен выполнить действие, прежде чем транзакцию можно будет провести. Прочитайте блок `action_required` и передайте его `url` пользователю (SDK могут [обрабатывать это автоматически](https://docs.didit.me/ru/transaction-monitoring/sdk-transaction-submission.md#требуемые-действия-пользователя)). |

См. [статусы TM](https://docs.didit.me/ru/transaction-monitoring/statuses.md).

## Связывание транзакций с сущностями

Передавайте `vendor_data` для каждого участника. Это даёт следующие преимущества:

* Каждая транзакция агрегируется в профиль пользователя или компании.
* Правила по скорости и поведению имеют полную историю для оценки.
* Блокировка сущности автоматически распространяется на будущие транзакции.

Отсутствие `vendor_data` не является жёсткой ошибкой: транзакция сохраняется как внешний снимок. Однако вы теряете агрегацию на уровне сущностей.

## Сессии устранения

Когда действие правила переводит транзакцию в статус `AWAITING_USER`, Didit автоматически создаёт **сессию устранения**: стандартную размещённую сессию верификации для того же `vendor_data`.
Пользовательские правила всегда указывают сценарий прямо в самом действии. Для встроенных правил из библиотеки сценарий берётся из [сценария устранения в настройках транзакций](https://docs.didit.me/ru/transaction-monitoring/settings.md#сценарий-устранения), затем из сценария **Биометрическая аутентификация** вашего приложения (если у субъекта есть сохранённое эталонное лицо), затем из сценария по умолчанию вашего приложения.
Транзакции Travel Rule исключены из этого автоматического выбора: их ожидающее действие - подтверждение владения кошельком.
Транзакция (ответ, каждое последующее чтение и каждый webhook) содержит его в каноническом блоке `action_required`:

```json theme={null}
{
  "status": "AWAITING_USER",
  "action_required": {
    "type": "verification_session",
    "url": "https://verify.didit.me/session/...",
    "session_id": "11111111-2222-3333-4444-555555555555",
    "session_token": "SESSION_TOKEN",
    "status": "Not Started"
  },
  "remediation": {
    "session_id": "11111111-2222-3333-4444-555555555555",
    "session_token": "SESSION_TOKEN",
    "url": "https://verify.didit.me/session/...",
    "status": "Not Started"
  }
}
```

`remediation` сохранён для обратной совместимости; `action_required` является каноническим блоком (он также содержит действия `wallet_ownership` для переводов по [Travel Rule](https://docs.didit.me/ru/transaction-monitoring/travel-rule.md)).
Действие `wallet_ownership` само по себе не меняет статус транзакции: транзакция сохраняет тот статус, который ей присваивают ваши правила, часто `APPROVED`, поэтому проверяйте `action_required` в каждом ответе, а не только при `AWAITING_USER`.

Пользователь проходит верификацию. Для сценария **Биометрическая аутентификация** это селфи с проверкой живости, сопоставленное с лицом, полученным при его исходном онбординге KYC, и это самый строгий дополнительный шаг для [транзакций высокой стоимости](https://docs.didit.me/ru/transaction-monitoring/sdk-transaction-submission.md#пример-повторная-биометрическая-проверка-для-крупного-вывода-средств).
Как только сессия получает решение, транзакция следует ему автоматически: `APPROVED` (`decision_reason_code: user_action_approved`), `DECLINED` (`user_action_declined`) или `IN_REVIEW` (`user_action_in_review`), и срабатывает webhook `transaction.status.updated`.

> [!NOTE]
>
> Можно выбрать любой тип сценария, кроме KYB.
> Сценарии Биометрическая аутентификация (а также сценарии, где сравнение лиц выполняется до верификации личности) требуют, чтобы у субъекта уже было сохранённое эталонное лицо из одобренной верификации. Пользователи без него направляются в сценарий по умолчанию вашего приложения, а в транзакции фиксируется примечание о такой замене.

## Лучшие практики

| Практика | Почему |
| - | - |
| Всегда передавайте `vendor_data` | Обеспечивает агрегацию. |
| Используйте собственный `txn_id` | Идемпотентность. |
| Подпишитесь и на `transaction.created`, и на `transaction.status.updated` | Фиксируйте асинхронные изменения статуса (например, результаты проверки аналитиком). |
| Задавайте пороги правил осознанно | Низкие пороги = больше оповещений; высокие = больше пропущенных рисков. См. [скоринг рисков](https://docs.didit.me/ru/transaction-monitoring/risk-scoring.md). |
| Следите за количеством срабатываний правил в консоли | Обнаруживайте правила, которые никогда не срабатывают (настроены неверно), или срабатывают на всё (слишком мягкие). |
| Тестируйте правила в режиме TEST перед запуском в продакшн | См. [правила](https://docs.didit.me/ru/transaction-monitoring/rules.md). |

## Лимиты запросов

См. [ограничение частоты запросов](https://docs.didit.me/ru/integration/rate-limiting.md). Создание транзакции - один из самых высоконагруженных endpoint’ов; типичные лимиты составляют сотни запросов в секунду. Соблюдайте осторожность при отправке всплесков запросов.

## Следующие шаги

> [card] [Транзакции](https://docs.didit.me/ru/transaction-monitoring/transactions.md)
>
> Полный справочник по payload.

> [card] [Правила](https://docs.didit.me/ru/transaction-monitoring/rules.md)
>
> Как оцениваются правила.

> [card] [Webhook](https://docs.didit.me/ru/transaction-monitoring/webhooks.md)
>
> Каталог событий.

> [card] [Устранение неполадок](https://docs.didit.me/ru/transaction-monitoring/troubleshooting.md)
>
> Частые проблемы интеграции.


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