跳转到主要内容

上下文信号

MarkdownChatGPTClaude

开始之前​

上下文信号会评估已完成的信用交易，并返回风险评估结果——自我欺诈或社会工程——以丰富您自己的反欺诈决策。

它们是对无卡验证的补充：不会更改您已在使用的交易端点的约定或行为。您依然照常接收交易的终态（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是交易 ID（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—结果尚未计算完成——异步处理仍在进行中。重复调用（轮询），直到收到 200。
40040004transaction_id 无效（不是 UUID v4）或参数格式错误。在再次发送请求之前修正 ID 格式。
40340305贵公司未启用该端点所需的权限（角色）。请向 Unico 团队申请启用。
40440401未找到该交易。检查交易 ID。
40440484未找到用于评估的交易。将其视为“不会有结果”并停止查询。
40940983交易尚未达到终态。等待终态后再次查询。
500—内部服务错误。使用退避策略重试。如果问题持续存在，请联系 Unico 支持团队。

规则和最佳实践​

  • 仅在交易达到终态后查询该端点。提前查询将返回 409。
  • 仅评估信用交易。以静默模式捕获的交易不会被评估。
  • 收到 202 时，重复调用直到获得 200。在交易响应后 1 秒发送第一次请求，然后按 2 秒、4 秒、8 秒、16 秒退避——最多尝试 5 次。
  • 服务级别目标为交易响应后 10 秒内。
  • 将 404 视为“不会有结果”并停止查询。
  • auto_fraud_risk 和 social_eng_risk 互斥。
最后更新 于