> ## 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 отправки транзакций: payload и модель данных

> Didit: отправляйте транзакции на мониторинг в реальном времени — стороны, способы оплаты, устройство. 1,000 в месяц бесплатно, далее $0.001 за вызов.

Передайте транзакции в Didit через API [Создать транзакцию](https://docs.didit.me/ru/management-api/transactions/create.md). Каждая транзакция содержит структурированные данные о сторонах, платеже и контексте, которые движок правил оценивает в реальном времени.

> [!TIP]
>
> Если транзакция создаётся на устройстве конечного пользователя, например при выводе криптовалюты или платеже в приложении, рассмотрите [отправку транзакции через SDK](https://docs.didit.me/ru/transaction-monitoring/sdk-transaction-submission.md). Вместо 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 | Ваш идентификатор этой стороны: связывает транзакцию с [пользователем](https://docs.didit.me/ru/management-api/users/list.md) или [профилем компании](https://docs.didit.me/ru/business-verification/business-profiles.md) |
| `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` и попадает в процесс подтверждения владения. См. раздел [Заявленные некастодиальные кошельки](https://docs.didit.me/ru/transaction-monitoring/travel-rule.md#объявленные-некастодиальные-кошельки).

Для криптотранзакций указывайте адреса кошельков в `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-адреса |

> [!NOTE]
>
> `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 мерчанта или канала.

```json theme={null}
"custom_properties": {
  "product_category": "electronics",
  "merchant_id": "MER456",
  "channel": "mobile_app"
}
```

В условиях правил ссылайтесь на каждый ключ через путь к полю `custom_values.<key>`. Например, payload выше соответствует условию `custom_values.product_category eq "electronics"`. В конструкторе правил в Console ключи, встречавшиеся в недавно поступивших транзакциях, отображаются в селекторе полей условий в разделе **Пользовательские свойства**. Кнопка **Ввести пользовательское свойство** в той же группе позволяет вручную ввести любой ключ (с учётом регистра). Подробности см. в разделе [Правила и скоринг](https://docs.didit.me/ru/transaction-monitoring/rules.md#обращение-к-пользовательским-свойствам).

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

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

## Ответ

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](https://docs.didit.me/ru/management-api/transactions/create.md). Разбор payload с пояснениями см. в [справочнике схемы ответа](https://docs.didit.me/ru/transaction-monitoring/response-schema.md).

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

Назначьте приостановленную транзакцию участнику вашего приложения или снимите назначение с помощью 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 транзакций.

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

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

Фильтруйте [список транзакций](https://docs.didit.me/ru/management-api/transactions/list.md) по `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}/`](https://docs.didit.me/ru/management-api/transactions/get), используя `uuid` из первого ответа, или используйте `transaction_id` (uuid Didit), который передаётся в webhook `transaction.created` рядом с вашим `txn_id`.
Всегда генерируйте `txn_id` на своей стороне (например, ID из вашей базы транзакций, UUID или детерминированный хеш).

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

Передайте `txn_date` в прошлом, чтобы загрузить исторические транзакции. Правила по умолчанию всё равно выполняются. Если вы хотите пропустить оценку правил при массовой загрузке исторических данных, используйте импорт CSV в консоли в режиме dry-ingest. См. [руководство по интеграции](https://docs.didit.me/ru/transaction-monitoring/integration-guide.md#импорт-исторических-данных).

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

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

> [card] [Схема ответа](https://docs.didit.me/ru/transaction-monitoring/response-schema.md)
>
> Полный аннотированный payload ответа.

> [card] [Скрининг криптовалют](https://docs.didit.me/ru/transaction-monitoring/aml-screening.md)
>
> Автоматический скрининг кошельков и транзакций для криптовалютных транзакций.

> [card] [Travel Rule](https://docs.didit.me/ru/transaction-monitoring/travel-rule.md)
>
> Прикрепление данных о соблюдении Travel Rule к переводам виртуальных активов.

> [card] [Обогащение данных по IP](https://docs.didit.me/ru/transaction-monitoring/ip-enrichment.md)
>
> Контекст, полученный из IP, доступен правилам.

> [card] [Справочник API](https://docs.didit.me/ru/management-api/transactions/create.md)
>
> Полная схема запроса для endpoint Create Transaction.


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