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

Это руководство охватывает весь интерфейс интеграции «Мониторинга транзакций». Быстрый старт поможет запустить интеграцию, а эта страница описывает всё необходимое для выхода в продакшн.

Архитектура

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

Используется стандартный заголовок x-api-key. Те же ключи применяются для сессий и сущностей. См. аутентификация API.

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

Единственный endpoint: POST /v3/transactions/. Полную схему см. в разделе отправка транзакций. Минимальный payload:

{
  "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 с методами оплаты, контекстом устройства и пользовательскими свойствами:

{
  "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 транзакций.

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

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}/, используя uuid из первого ответа, или используйте transaction_id (uuid Didit), который событие transaction.created передаёт рядом с вашим txn_id. Всегда генерируйте txn_id на своей стороне до отправки. Не полагайтесь на ID, который генерирует Didit, для идемпотентности. Используйте собственный ID из базы данных, UUID или хеш полей транзакции.

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

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

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

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

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

Продумайте выполнение правил на исторических данных. Прогон данных за шесть месяцев через правило “20 переводов за 30 дней” создаст тысячи оповещений сразу.

Webhook

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

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

Подробнее: webhook TM.

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 могут обрабатывать это автоматически).

См. статусы TM.

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

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

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

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

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

Когда действие правила переводит транзакцию в статус AWAITING_USER, Didit автоматически создаёт сессию устранения: стандартную размещённую сессию верификации для того же vendor_data. Пользовательские правила всегда указывают сценарий прямо в самом действии. Для встроенных правил из библиотеки сценарий берётся из сценария устранения в настройках транзакций, затем из сценария Биометрическая аутентификация вашего приложения (если у субъекта есть сохранённое эталонное лицо), затем из сценария по умолчанию вашего приложения. Транзакции Travel Rule исключены из этого автоматического выбора: их ожидающее действие - подтверждение владения кошельком. Транзакция (ответ, каждое последующее чтение и каждый webhook) содержит его в каноническом блоке action_required:

{
  "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). Действие wallet_ownership само по себе не меняет статус транзакции: транзакция сохраняет тот статус, который ей присваивают ваши правила, часто APPROVED, поэтому проверяйте action_required в каждом ответе, а не только при AWAITING_USER. Пользователь проходит верификацию. Для сценария Биометрическая аутентификация это селфи с проверкой живости, сопоставленное с лицом, полученным при его исходном онбординге KYC, и это самый строгий дополнительный шаг для транзакций высокой стоимости. Как только сессия получает решение, транзакция следует ему автоматически: APPROVED (decision_reason_code: user_action_approved), DECLINED (user_action_declined) или IN_REVIEW (user_action_in_review), и срабатывает webhook transaction.status.updated.

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

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

Практика	Почему
Всегда передавайте `vendor_data`	Обеспечивает агрегацию.
Используйте собственный `txn_id`	Идемпотентность.
Подпишитесь и на `transaction.created`, и на `transaction.status.updated`	Фиксируйте асинхронные изменения статуса (например, результаты проверки аналитиком).
Задавайте пороги правил осознанно	Низкие пороги = больше оповещений; высокие = больше пропущенных рисков. См. скоринг рисков.
Следите за количеством срабатываний правил в консоли	Обнаруживайте правила, которые никогда не срабатывают (настроены неверно), или срабатывают на всё (слишком мягкие).
Тестируйте правила в режиме TEST перед запуском в продакшн	См. правила.

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

См. ограничение частоты запросов. Создание транзакции - один из самых высоконагруженных endpoint’ов; типичные лимиты составляют сотни запросов в секунду. Соблюдайте осторожность при отправке всплесков запросов.

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

Транзакции

Полный справочник по payload.

Правила

Как оцениваются правила.

Webhook

Каталог событий.

Устранение неполадок

Частые проблемы интеграции.

Начало работы

Функции

Справочник

Консоль

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

Архитектура

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

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

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

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

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

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

Webhook

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

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

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

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

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

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

Транзакции

Правила

Webhook

Устранение неполадок

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

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

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

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

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

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

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

​Webhook

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

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

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

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

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

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

Транзакции

Правила

Webhook

Устранение неполадок

Архитектура

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

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

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

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

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

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

Webhook

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

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

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

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

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

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