API отправки транзакций: payload и модель данных

Передайте транзакции в Didit через API Создать транзакцию. Каждая транзакция содержит структурированные данные о сторонах, платеже и контексте, которые движок правил оценивает в реальном времени.

Если транзакция создаётся на устройстве конечного пользователя, например при выводе криптовалюты или платеже в приложении, рассмотрите отправку транзакции через SDK. Вместо API-ключа используется token с ограниченной областью действия, данные об устройстве собираются автоматически, а необходимые действия пользователя (подтверждение владения кошельком, дополнительная верификация) запускаются сразу.

Категории транзакций

У каждой транзакции есть transaction_category, который определяет, как правила и аналитика обрабатывают её:

Категория	Описание
`finance`	Стандартная финансовая транзакция (депозит, вывод, перевод)
`kyc`	Событие, связанное с верификацией личности
`travel_rule`	Перевод виртуальных активов, требующий соблюдения Travel Rule
`user_event`	Пользовательское событие платформы (вход, изменение профиля и т. д.)
`gambling_bet`	Ставка или размещение пари
`gambling_limit_change`	Изменение лимита игрока на депозиты, проигрыши или ставки
`gambling_bonus_change`	Начисление, использование или аннулирование бонуса
`audit_trail_event`	Системное событие или событие комплаенс-аудита

Данные транзакции

Объект transaction_details содержит финансовые данные:

Поле	Тип	Описание
`direction`	string	`inbound` или `outbound`
`amount`	string	Сумма транзакции в виде десятичной строки (например, `"1500.50"`)
`currency`	string	Код валюты ISO (например, `USD`, `EUR`, `BTC`)
`currency_kind`	string	`fiat` или `crypto` (псевдоним `currencyType`); определяет, запускается ли скрининг криптовалют
`action_type`	string	Метка действия, заданная поставщиком (например, `deposit`, `withdrawal`, `purchase`)
`payment_details`	string	Свободное текстовое описание платежа (например, `"Bank transfer from ABC Corp"`)
`payment_reference_id`	string	Внешний идентификатор платежа. Для скрининга криптовалют после перевода используйте хеш транзакции в блокчейне.

Субъект и контрагент

Каждая транзакция имеет субъекта (обязательно) и необязательного контрагента. Оба используют одну модель стороны:

Поле	Тип	Описание
`entity_type`	string	`person` или `company`
`vendor_data`	string	Ваш идентификатор этой стороны: связывает транзакцию с пользователем или профилем компании
`full_name`	string	Полное имя стороны
`first_name`	string	Имя
`last_name`	string	Фамилия
`date_of_birth`	string	Дата в формате ISO (например, `1990-01-15`)
`country_code`	string	Код страны ISO 3166-1 alpha-2
`address`	object or string	Структурированный адрес с полями `street`, `city`, `state`, `country`, `postal_code`. Также принимает обычную строку, например адрес кошелька для криптоконтрагента: Didit сохраняет её без изменений в данных стороны.

Если address передан объектом, Didit получает country_code стороны из address.country. Если address передан строкой, country_code для этой стороны возвращается как null. Когда vendor_data совпадает с существующим пользователем или компанией, Didit автоматически связывает транзакцию с профилем этой сущности, что позволяет оценивать правила в рамках нескольких сессий и проверять частоту операций. В ответе обе стороны возвращаются в массиве parties с ролями APPLICANT и COUNTERPARTY.

Способы оплаты

Прикрепите payment_method к каждой стороне, чтобы описать платёжный инструмент с её стороны:

Поле	Тип	Описание
`method_type`	string	`bank_card`, `bank_account`, `e_wallet`, `crypto_wallet`, `unhosted_wallet` или `other` (псевдоним `type`); `ewallet`, `card` и `crypto` также принимаются как псевдонимы, а нераспознанное значение сохраняется как `other`
`account_id`	string	Номер счёта, адрес кошелька или token карты
`issuing_country`	string	Страна, выпустившая платёжный инструмент

В транзакциях travelRule способ оплаты контрагента с method_type: "unhosted_wallet" (псевдоним type) указывает, что кошелёк контрагента является некастодиальным. Если Travel Rule включён и сумма в валюте по умолчанию вашего приложения не ниже threshold_amount, перевод сразу переходит в статус UNCONFIRMED_OWNERSHIP и попадает в процесс подтверждения владения. См. раздел Заявленные некастодиальные кошельки. Для криптотранзакций указывайте адреса кошельков в account_id и задавайте currency_kind равным crypto, чтобы скрининг блокчейна запускался автоматически. Направление определяет, какой кошелёк проверяется: при входящем скрининге до перевода используется кошелёк отправителя в counterparty.payment_method.account_id; при исходящем скрининге используется кошелёк получателя в counterparty.payment_method.account_id. Если вы передаёте хеш блокчейна в transaction_details.payment_reference_id, для скрининга входящей транзакции требуется адрес депозита вашего сервиса в subject.payment_method.account_id, а для скрининга исходящей транзакции требуется кошелёк получателя в counterparty.payment_method.account_id.

Переопределение скрининга криптовалют

Используйте include_crypto_screening на верхнем уровне запроса, чтобы переопределить значение по умолчанию, заданное в разделе Транзакции > Настройки в консоли:

Значение	Описание
`true`	Принудительно запустить скрининг криптовалют для этой транзакции
`false`	Пропустить скрининг криптовалют для этой транзакции
не указано или `null`	Использовать значение по умолчанию на уровне приложения

Контекст устройства

Передайте информацию об устройстве субъекта (а при необходимости и контрагента), чтобы работали правила анализа устройства. Поле запроса называется device_context и передаётся для каждой стороны. Также принимается алиас в camelCase device, именно он используется в формате SDK. В ответе оно возвращается как device в каждом элементе массива parties.

Поле	Тип	Описание
`device_context.fingerprint`	string	Уникальный отпечаток устройства
`device_context.persistent_device_id`	string	Стабильный идентификатор устройства между сессиями (схема фингерпринта v2)
`device_context.user_agent`	string	Строка User-Agent браузера или приложения
`device_context.browser_family`	string	Семейство браузера (например, `Chrome`, `Firefox`, `Safari`). Обязательно передавайте явно: значение не выводится из `user_agent`. Используется в правилах вроде `subject_browser_family`.
`device_context.browser_version`	string	Версия браузера (например, `131.0`). Обязательно передавайте явно.
`device_context.platform`	string	Идентификатор платформы (`web`, `ios`, `android`, `macos`, `windows`, `linux`). Обязательно передавайте явно: значение не выводится из `user_agent`. Используется в правилах вроде `subject_platform`.
`device_context.os_family`	string	Семейство операционной системы (например, `iOS`, `Android`, `Windows`)
`device_context.os_version`	string	Версия операционной системы
`device_context.accept_language`	string	Значение заголовка Accept-Language (например, `en-US,en;q=0.9`). При работе через SDK собирается автоматически.
`device_context.session_id`	string	Идентификатор текущей сессии пользователя. Сохраняется в метаданных. Алиас в camelCase: `sessionId`.
`device_context.session_age_ms`	number	Возраст сессии пользователя в миллисекундах на момент транзакции. Используется в правилах вроде `subject_session_age_ms`.
`device_context.network_context.ip_address`	string	IP-адрес клиента
`device_context.network_context.ip_country_code`	string	Страна IP-адреса, определённая по геолокации (ISO 3166-1 alpha-3)
`device_context.network_context.latitude`	number	Географическая широта IP-адреса
`device_context.network_context.longitude`	number	Географическая долгота IP-адреса

browser_family и platform не выводятся из user_agent. Их нужно передавать как явные ключи верхнего уровня внутри device_context, иначе правила анализа устройства не сработают. Если вы используете SDK Didit, эти поля собираются автоматически.

Для каждого поля принимаются алиасы в camelCase: userAgent, browserFamily, browserVersion, osFamily, osVersion, acceptLang, sessionId, sessionAgeMs. Подобъект network_context принимает алиасы ip / countryCode3 / lat / lon, а блок верхнего уровня ipInfo также включается в network_context. Контекст устройства позволяет настроить правила для выявления мультиаккаунтинга (один и тот же отпечаток у разных субъектов), сочетания нового браузера и нового IP, перевода крупной суммы при малом возрасте сессии, а также скоринга риска по местоположению.

Пользовательские свойства

Добавляйте любые дополнительные пары ключ-значение в объект custom_properties. Правила могут ссылаться на эти поля в своих условиях. Это удобно для передачи бизнес-контекста, например категории товара, ID мерчанта или канала.

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

В условиях правил ссылайтесь на каждый ключ через путь к полю custom_values.<key>. Например, payload выше соответствует условию custom_values.product_category eq "electronics". В конструкторе правил в Console ключи, встречавшиеся в недавно поступивших транзакциях, отображаются в селекторе полей условий в разделе Пользовательские свойства. Кнопка Ввести пользовательское свойство в той же группе позволяет вручную ввести любой ключ (с учётом регистра). Подробности см. в разделе Правила и скоринг.

Пример запроса

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"
    }
  }'

Ответ

API возвращает созданную транзакцию с первичными результатами оценки:

Поле	Тип	Описание
`uuid`	string	Уникальный идентификатор транзакции в Didit
`txn_id`	string	Идентификатор транзакции, который вы передали
`status`	string	`APPROVED`, `IN_REVIEW`, `DECLINED` или `AWAITING_USER`
`score`	number	Совокупная оценка риска по всем сработавшим правилам
`severity`	string	Наивысшая серьёзность сработавших правил (`LOW`, `MEDIUM`, `HIGH`, `CRITICAL`)
`decision_reason_code`	string	Машиночитаемая причина решения о статусе
`decision_reason_label`	string	Описание решения, понятное человеку

Полную схему запроса и ответа см. в справочнике API. Разбор payload с пояснениями см. в справочнике схемы ответа.

Назначение транзакции проверяющему

Назначьте приостановленную транзакцию участнику вашего приложения или снимите назначение с помощью API-ключа с правом write:transactions. Каждое изменение фиксируется на временной шкале транзакции как TRANSACTION_ASSIGNED.

Вызов	Назначение
`POST /v3/transactions/{transaction_uuid}/assign/`	Назначить одну транзакцию.
`POST /v3/transactions/assign/`	Назначить до 500 транзакций одному участнику.

В обоих вызовах передаётся assignee_email, адрес электронной почты участника приложения, который вошёл в Didit. Передайте null или пустую строку, чтобы снять назначение. Массовый вызов также принимает transaction_ids, список из 1–500 UUID транзакций.

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"}'

Одиночный вызов возвращает uuid, transaction_number, assignee и changed (false, если транзакции уже был назначен этот проверяющий), либо 404, если транзакция не существует в приложении. Массовый вызов возвращает transactions (по одной записи в формате выше), updated_count и not_found_transaction_ids. Фильтруйте список транзакций по assignee. Это список через запятую, где достаточно совпадения любого значения: me, unassigned, rules (решение принято только правилами, проверяющий не участвовал) или email участника.

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

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

Загрузка исторических транзакций

Передайте txn_date в прошлом, чтобы загрузить исторические транзакции. Правила по умолчанию всё равно выполняются. Если вы хотите пропустить оценку правил при массовой загрузке исторических данных, используйте импорт CSV в консоли в режиме dry-ingest. См. руководство по интеграции.

Дальнейшие шаги

Правила и скоринг

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

Схема ответа

Полный аннотированный payload ответа.

Скрининг криптовалют

Автоматический скрининг кошельков и транзакций для криптовалютных транзакций.

Travel Rule

Прикрепление данных о соблюдении Travel Rule к переводам виртуальных активов.

Обогащение данных по IP

Контекст, полученный из IP, доступен правилам.

Справочник API

Полная схема запроса для endpoint Create Transaction.

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

Функции

Справочник

Консоль

API отправки транзакций: payload и модель данных

Категории транзакций

Данные транзакции

Субъект и контрагент

Способы оплаты

Переопределение скрининга криптовалют

Контекст устройства

Пользовательские свойства

Пример запроса

Ответ

Назначение транзакции проверяющему

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

Загрузка исторических транзакций

Дальнейшие шаги

Правила и скоринг

Схема ответа

Скрининг криптовалют

Travel Rule

Обогащение данных по IP

Справочник API

​Категории транзакций

​Данные транзакции

​Субъект и контрагент

​Способы оплаты

​Переопределение скрининга криптовалют

​Контекст устройства

​Пользовательские свойства

​Пример запроса

​Ответ

​Назначение транзакции проверяющему

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

​Загрузка исторических транзакций

​Дальнейшие шаги

Правила и скоринг

Схема ответа

Скрининг криптовалют

Travel Rule

Обогащение данных по IP

Справочник API

Категории транзакций

Данные транзакции

Субъект и контрагент

Способы оплаты

Переопределение скрининга криптовалют

Контекст устройства

Пользовательские свойства

Пример запроса

Ответ

Назначение транзакции проверяющему

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

Загрузка исторических транзакций

Дальнейшие шаги