POST /v3/transactions/ и GET /v3/transactions/{transaction_id}/. Оба эндпоинта возвращают один и тот же объект TransactionDetail. В справочнике API приведена схема по каждому полю, а на этой странице она разобрана по шагам.
Структура верхнего уровня
uuid является стабильным идентификатором Didit и передаётся в пути GET /v3/transactions/{transaction_id}/. Значение txn_id совпадает с transaction_id, который вы передали при создании. transaction_number указывает на последовательный номер в рамках приложения, который отображается в консоли.
Субъект и контрагент, которых вы передали, не возвращаются как ключи верхнего уровня. Они представлены элементами массива parties и различаются по role. Поле vendor_data на верхнем уровне является удобной копией vendor_data заявителя.
Ключевые поля
Финансовые поля
amount/currency– сумма транзакции в том виде, в каком она передана.amount– это десятичная строка без завершающих нулей ("1500","0.5"), с не более чем 18 знаками после запятой.currency_type–fiatилиcrypto, как передано вcurrency_kind;null, если не указано.amount_in_default_currency/default_currency_code– предварительно сконвертированная сумма, которую вы передали в запросе, возвращается обратно;null, если вы её не отправляли.preferred_currency_amount/preferred_currency_code–amount, сконвертированная в предпочтительную валюту вашего приложения.null, если дляcurrencyнет курса обмена и вы не передалиamount_in_default_currency.payment_details/payment_txn_id– свободный текстовый идентификатор платежа и внешний платёжный идентификатор (например, хеш транзакции в блокчейне) из запроса.
Поля статуса
status–APPROVED,IN_REVIEW,DECLINED,AWAITING_USER. Транзакции создаются со статусомAPPROVED; правила могут менять его синхронно.score– целочисленная оценка риска, накопленная правилами. Чем выше значение, тем выше риск.severity–UNKNOWN,LOW,MEDIUM,HIGH,CRITICALилиnull, пока правило или провайдер не установит значение.decision_reason_code/decision_reason_label– структурированная и понятная человеку причина текущего статуса.environment–liveилиsandbox, из приложения, которому принадлежит транзакция. Транзакция вsandboxсохраняется, но никогда не оценивается, поэтому пустойrule_runsозначает «не оценивалась», а не «ничего не сработало». См. Мониторинг транзакций в песочнице.source–LIVEдля транзакций, переданных через API или SDK,IMPORTEDдля транзакций, загруженных через импорт CSV в консоли.
Стороны
Каждая сторона транзакции представлена записью вparties. Эндпоинт создания записывает субъекта как APPLICANT, а необязательного контрагента как COUNTERPARTY; перечисление role также включает REMITTER и BENEFICIARY. Все записи имеют одинаковую структуру.
role–APPLICANT,COUNTERPARTY,REMITTER,BENEFICIARY. Используйте фильтр по этому полю, чтобы найти субъекта.entity_type–individual,company,external,unhostedWallet, как передано.kind–USERилиBUSINESS, если сторона связана с пользователем или бизнесом Didit черезvendor_data; в остальных случаяхEXTERNAL.country_code/dob– из переданныхaddress.countryиdate_of_birth.address/institution_info– объекты в том виде, в каком они переданы;{}, если они не указаны.external_party_snapshot– зафиксированная копия данных стороны для сторонEXTERNAL;null, пока сторона связана с пользователем или бизнесом Didit.
device
device – это device_context, который вы передали для этой стороны, приведённый к snake_case, с серверным обогащением данных об IP. Это {}, если в запросе не было контекста устройства, поэтому считайте каждый ключ необязательным.
Отдельного объекта обогащения нет. Если у стороны был публичный
network_context.ip_address, Didit определяет его прямо в процессе обработки и записывает обогащённые поля в тот же объект network_context, заполняя только те ключи, которые вы не передали. Ключи, для которых резолвер вернул пустое значение, опускаются, поэтому полностью обогащённый network_context содержит четыре переданных ключа (ip_address, ip_country_code, latitude, longitude) и те из ip_country, ip_state, ip_city, isp, organization, is_vpn_or_tor, is_data_center, time_zone, time_zone_offset, asn_number, asn_organization, connection_type, carrier и proxy_type, которые были определены. is_vpn_or_tor и is_data_center всегда присутствуют после успешного определения.
Обогащение пропускается, и network_context возвращается ровно в том виде, в каком был передан, если IP отсутствует или не маршрутизируется, если приложение работает в песочнице или если определить данные не удалось. ip_country_code – это код ISO 3166-1 alpha-2, если Didit его определил, и значение, которое вы передали, в остальных случаях; условия правил приводят обе формы к единому виду перед сравнением.
Платёжные методы
role–SOURCE,DESTINATION,FUNDING,BENEFICIARY. Эндпоинт создания присваиваетSOURCE/DESTINATIONна основеdirection: в исходящей транзакции платёжный метод субъекта получаетSOURCE, а контрагента –DESTINATION; во входящей транзакции роли меняются местами.payment_method_type–bank_card,bank_account,e_wallet,crypto_wallet,unhosted_wallet,other.fingerprint– SHA-256 отtype:account_id:issuing_country, стабильный для всех транзакций, поэтому вы можете отслеживать повторное использование одного и того же инструмента.null, еслиaccount_idне был передан.owner_kind/vendor_data/owner_name– владелец инструмента, с той же схемойUSER/BUSINESS/EXTERNAL, что и у сторон.details– исходный объектpayment_method, как передан.
Запуски правил
rule– UUID правила, которое запустилось;rule_title,rule_description,rule_categoryкопируются из него.matched– запуск записывается только тогда, когда условия правила совпали, поэтому у боевых оценок всегдаmatched: true. Правила, которые были оценены без совпадения, не оставляют записи. Демонстрационные данные могут содержать строки сmatched: false.is_test/mode–trueиTEST, когда правило запущено в тестовом режиме; тестовый запуск записывается, но не влияет наstatus,scoreилиseverity.score_delta/status_target/severity– вклад этого запуска.status_targetзадаётся, когда выполнилось действиеchange_statusили когда добавленная оценка пересекла порог.action_summary– строка с перечнем действий, выполненных правилом, объединённых через;(score +30,change_status:IN_REVIEW,add_tag:<name>,add_note,add_to_list,open_case);null, если правило не выполнило ни одного действия.metadata– подробности оценки:scope_match, а такжеconditions[]иaggregations[]. В этих двух списках используются разные ключи значений:conditions[]– одна запись на каждое условие с полямиfield,operator,expected_value,current_value(значение, прочитанное из транзакции),matched,group_indexиgroup_logic.field_sourceвсегдаnullдля запусков правил транзакций; он классифицируется только для событий мониторинга.aggregations[]– одна запись на каждую агрегацию по частоте, количеству или сумме с полямиmetric,field,operator,expected_value,computed_value(вычисленное агрегацией значение),window,filters,matchedиsample_references. Агрегации, которые можно вычислить только асинхронно, содержатcomputed_value: nullиdeferred: true.
Оповещения
alerts сейчас всегда пустой массив.
Открытое оповещение означает удерживаемую транзакцию, поэтому смотрите status (IN_REVIEW или AWAITING_USER). См. Оповещения.
Активность
Журнал активности транзакции: создание, заметки, ручные проверки и изменения статуса.TRANSACTION_NOTE_ADDED. Отдельного массива notes нет.
Документы
Файлы, прикреплённые к транзакции в консоли.[], если файлов нет.
file_url содержит подписанный URL с коротким сроком действия: получайте его по мере необходимости, а не сохраняйте.
Результаты провайдеров
Результаты внешних провайдеров (скрининг хеша транзакции, скрининг кошельков, мониторинг фиатных операций, скрининг санкций).result_type: FIAT_MONITORING, WALLET_SCREENING, TRANSACTION_SCREENING, TRAVEL_RULE, NETWORK_GRAPH, CUSTOM.
payload.risk_factors — ранжированное объяснение score: что привело к вердикту, сначала факторы высокого риска, затем по объёму переведённых средств. Высокий score без записи is_high_risk означает, что провайдер оценил субъект по собственной модели подверженности риску, не сообщив о совпадении с санкционным списком или атрибутированной сущностью; summary указывает на это прямо. Справочник по полям: Факторы риска. Результаты, проверенные до появления этого поля, не содержат этот ключ.
Для скрининга хешей криптотранзакций transaction_flows заполняется, когда доступно обогащение данными из блокчейна. Оно нормализует активность в сети, чтобы консоль могла отобразить и обзор транзакции, и граф визуализации по одному и тому же ответу.
Поддерживаемые источники обогащения:
- Цепочки EVM используют Blockscout для нормализации основной транзакции, внутренних вызовов и переводов токенов.
- Bitcoin использует mempool.space для нормализации входов и выходов транзакции.
- Solana использует Helius для нормализации переводов нативного SOL, переводов токенов SPL и доступного контекста событий NFT.
transaction_flows[] содержит стабильные нормализованные поля (flow_type, from_address, to_address, amount, amount_usd, currency, token_name, token_address, transaction_hash, block_timestamp, index, success) и специфичные для провайдера metadata.
Типичные примеры metadata:
metadata дополняет данные и зависит от провайдера. Не создавайте критичные интеграции, которые требуют наличия каждого ключа для каждой сети.
Travel Rule
null, если у транзакции нет перевода или проверки по Travel Rule. Поле заполняется, когда вы отправляете travel_rule_details, а также когда Travel Rule включён для приложения и транзакция создана с transaction_category: "travelRule". В этом случае Didit сам инициирует обмен, с travel_rule_details или без них, и отражает его status здесь. Читайте это поле, а не запрос, который вы отправили.
При входящем переводе originator_data и beneficiary_data контрагента остаются замаскированными (data_masked: true), пока владение кошельком не подтверждено (см. Замаскированные данные контрагента).
direction, rail, counterparty_vasp, delivery, discovery, reason и next_actions имеют ту же структуру, что и в endpoint переводов.
reason и next_actions объясняют, почему перевод со статусом COUNTERPARTY_VASP_NOT_FOUND или COUNTERPARTY_VASP_NOT_REACHABLE застрял и что позволяет продолжить его обработку. Для любых других статусов они равны "" и []. См. Почему перевод застрял.
Каждая строка в GET /v3/transactions/ содержит тот же блок.
См. Travel Rule.
Снимок сети
Сохранённый граф целиком, а не ссылка на него. Он приходит из одного из двух источников:network_snapshot, который вы отправили вместе с транзакцией, или- граф, который Didit строит, когда AML-скрининг кошельков успешно завершается для криптотранзакции, даже если запрос не содержал
network_snapshot. Граф, построенный при скрининге, заменяет отправленный, а асинхронный повторный скрининг его обновляет.
null, если нет ни одного из них:
Теги, metadata, props
tags[]: прикреплённые теги (по действию правила или аналитиком):{ "uuid", "name", "color", "description", "source" }, гдеsourceравенdiditдля предустановленного тега иcustomдля вашего тега.metadata: снимок payload-овsubjectиcounterpartyв точности таком виде, в каком вы их отправили при создании, под этими двумя ключами.props:custom_properties, которые вы передали при создании. Каждый ключ можно использовать в условиях правил какcustom_values.<key>.
Устранение нарушения
Когда правило переводит транзакцию вAWAITING_USER, Didit создаёт связанную сессию верификации и возвращает её в двух полях:
remediation: связанная сессия{ "session_id", "session_token", "url", "status" }. Поле остаётся заполненным на протяжении всей жизни транзакции, поэтому вы всегда видите, чем закончилось действие пользователя.action_required: действие, которое пользователь должен выполнить прямо сейчас, илиnull, когда больше нет ожидающих действий:{ "type": "verification_session", "url", "session_id", "session_token", "status" }. Перенаправьте пользователя наurlили передайтеsession_tokenв SDK Didit. Действия Travel Rule с подтверждением владения кошельком используют{ "type": "wallet_ownership", "url", "widget_session_id", "expires_at" }и имеют приоритет, если применимы оба варианта. Когда действие с подтверждением кошелька ожидает выполнения, а контрагент перевода не найден, тот же блок также содержитreasonиnext_actions(см. поиск контрагента).
transaction.created и transaction.status.updated (action_required). См. webhook.
Разбивка стоимости
null, пока для транзакции не выполнялась ни одна тарифицируемая функция. Иначе { "total_price", "items": [ { "usage_type", "price", "details" } ] }, по одному элементу на каждую тарифицируемую функцию (скрининг, обогащение и так далее).
Конвертация валют
preferred_currency_amount представляет собой значение amount, пересчитанное в предпочтительную валюту вашего приложения по среднерыночному курсу, если только вы не передали amount_in_default_currency. В этом случае используется уже пересчитанное значение из этого поля. Условия правил для amount сравнивают исходную сумму. Если нужен единый порог для всех валют, используйте preferred_currency_amount в условиях.
Следующие шаги
Отправка транзакций
Полная схема запроса.
Статусы
Что означает каждый статус.
Скоринг риска
Как вычисляется оценка.