Перейти к основному содержимому

Контекстные сигналы

Прежде чем начать​

Контекстные сигналы анализируют завершённые кредитные транзакции и возвращают оценку риска — самостоятельное мошенничество или социальная инженерия — для дополнения вашего собственного решения по борьбе с мошенничеством.

Они дополняют Верификацию без предъявления карты: они не изменяют контракт или поведение эндпоинтов транзакций, которые вы уже используете. Вы по-прежнему получаете финальное состояние транзакции (approved, inconclusive и так далее) как обычно, а затем запрашиваете контекстные сигналы.

Ваши запросы к API аутентифицируются с помощью токена доступа. Любой запрос без действительного токена доступа вернёт ошибку. Подробнее в разделе Аутентификация.

Доступ на основе разрешений

Доступ к этому эндпоинту контролируется разрешением (ролью), назначенным вашей компании. Без него эндпоинт возвращает 403. Запросите включение доступа у команды Unico.

Базовый URL
  • UAT: https://transactions.transactional.uat.unico.app/api/public/v1
  • Продакшн: https://transactions.transactional.unico.app/api/public/v1

Получение контекстных сигналов​

GET /transactions/{transaction_id}/signals — возвращает оценку риска завершённой транзакции.

Результат вычисляется асинхронно заранее, как только транзакция достигает финального состояния, поэтому этот эндпоинт лишь получает уже доступный результат.

Параметры пути
ПараметрТипОбязательныйОписание
transaction_idstringдаИдентификатор транзакции (UUID v4). Например, 6ab1771e-dfab-4e47-8316-2452268e5481.
Заголовки
ЗаголовокЗначение
AuthorizationBearer {token} — действительный токен доступа.
Acceptapplication/json
Пример запроса
GET /api/public/v1/transactions/6ab1771e-dfab-4e47-8316-2452268e5481/signals HTTP/1.1
Host: transactions.transactional.uat.unico.app
Authorization: Bearer {token}
Accept: application/json
200 OK
{
  "signals": {
    "auto_fraud_risk": "high",
    "more_info": {
      "limited_data": false,
      "holder_identified": true
    }
  }
}
ПолеТипНаличиеОписание
signals.auto_fraud_riskstring (enum)опциональноУровень риска самостоятельного мошенничества. Присутствует только при обнаружении.
signals.social_eng_riskstring (enum)опциональноУровень риска социальной инженерии. Присутствует только при обнаружении.
signals.more_info.limited_databooleanвсегдаtrue, если данных недостаточно для надёжной оценки.
signals.more_info.holder_identifiedbooleanвсегдаfalse, если держателя карты не удалось идентифицировать.

Возможные значения риска: very_low, low, medium, high, very_high.

информация

auto_fraud_risk и social_eng_risk являются взаимоисключающими — они никогда не появляются вместе в одном ответе. Когда limited_data равно true, оба поля риска должны отсутствовать, поскольку данных недостаточно для оценки.

Примеры ответов

Обнаружен риск социальной инженерии:

{
  "signals": {
    "social_eng_risk": "very_high",
    "more_info": {
      "limited_data": false,
      "holder_identified": true
    }
  }
}

Риск не выявлен — обычная транзакция:

{
  "signals": {
    "more_info": {
      "limited_data": false,
      "holder_identified": true
    }
  }
}

Недостаточно данных:

{
  "signals": {
    "more_info": {
      "limited_data": true,
      "holder_identified": true
    }
  }
}

Держатель карты не идентифицирован:

{
  "signals": {
    "more_info": {
      "limited_data": false,
      "holder_identified": false
    }
  }
}
Другие коды ответа

Ошибки возвращаются в стандартном формате ошибок, описанном в разделе Ошибки.

HTTP-кодКодСитуацияЧто делать
202—Результат ещё не вычислен — асинхронная обработка всё ещё выполняется.Повторяйте запрос (polling), пока не получите 200.
40040004transaction_id недействителен (не UUID v4) или параметр некорректен.Исправьте формат идентификатора перед повторной отправкой запроса.
40340305У компании не включено разрешение (роль) для этого эндпоинта.Запросите включение доступа у команды Unico.
40440401Транзакция не найдена.Проверьте идентификатор транзакции.
40440484Транзакция не найдена для оценки.Считайте, что результата не будет, и прекратите запросы.
40940983Транзакция ещё не достигла финального состояния.Дождитесь финального состояния перед повторным запросом.
500—Внутренняя ошибка сервиса.Повторите запрос с задержкой (backoff). Если проблема сохраняется, обратитесь в поддержку Unico.

Правила и рекомендации​

  • Запрашивайте эндпоинт только после того, как транзакция достигнет финального состояния. Более ранний запрос вернёт 409.
  • Оценке подлежат только кредитные транзакции. Транзакции, зафиксированные в тихом режиме (silent mode), не оцениваются.
  • При получении 202 повторяйте запрос, пока не получите 200. Отправьте первый запрос через 1 секунду после ответа транзакции, затем увеличивайте интервал: 2с, 4с, 8с, 16с — до 5 попыток.
  • Целевой уровень обслуживания — 10 секунд после ответа транзакции.
  • Считайте 404 признаком того, что результата не будет, и прекратите запросы.
  • auto_fraud_risk и social_eng_risk являются взаимоисключающими.
Последнее обновление