api/对接接口文档.md

印尼支付行为画像查询接口

接口概览

接口	路径	说明
V1 特征	POST /api/v1/fortispay/payment-feature	返回 V1 版 536 个特征字段（6 模块）
V2 特征	POST /api/v1/fortispay/payment-feature-v2	返回 V2.2 版 606 个特征字段（6 模块，不含综合评分）
V2 评分	POST /api/v1/fortispay/payment-feature-v2-score	返回 V2.2 版 15 个综合评分字段（overall_score 模块）

三个接口调用同一三方 API，入参、缓存、日志相同，仅响应 data.result 字段过滤规则不同。

---

公共信息

项目	说明
请求格式	application/json; charset=UTF-8
响应格式	application/json

请求头部

参数	类型	必填	说明
Content-Type	String	Y	application/json
X-Request-Id	String	N	网关请求唯一标识ID，用于全链路追踪，原样回显在响应头中
X-Language	String	N	语言标识，传 en 返回英文结果，不传默认英文

响应头部

参数	类型	说明
X-Request-Id	String	回显请求头中的 X-Request-Id，未传则自动生成 32 位 UUID
X-Session-Id	String	三方服务返回的唯一会话标识（Fortispay responseId）

请求体

字段	类型	必填	说明
name	String	Y	用户姓名
id_card	String	Y	身份证号，支持明文或 MD5 密文
mobile	String	Y	手机号（带国家码），支持明文或 MD5 密文
encrypt_algo	String	N	加密算法。不传表示明文，服务端原样透传给三方；传入 MD5 表示已加密，直接透传

请求示例

{
  "name": "ABCXYZ",
  "id_card": "3201190108990002",
  "mobile": "6285887456612"
}

id_card、mobile 传明文时无需传 encrypt_algo，服务端原样透传给三方。

{
  "name": "ABCXYZ",
  "id_card": "cf0ab15098ab149e5273dd82f2c737e6",
  "mobile": "bd82af6340240c43175a80aedf7e6eef",
  "encrypt_algo": "MD5"
}

id_card、mobile 传密文时必须传 encrypt_algo="MD5"。

错误响应

错误响应与三方接口响应保持相同结构，其中 data 中 status=0、result=null：

{
  "code": "503",
  "message": "Connection error",
  "responseId": "a1b2c3d4e5f6789012345678abcdef01",
  "data": {
    "status": 0,
    "result": null
  }
}

HTTP状态码	code	对外 message	说明
400	400	{字段}: {校验提示}	请求参数校验失败
502	502	Service temporarily unavailable	三方 API HTTP 错误 / 响应解析失败 / 内部配置错误
503	503	Connection error	三方 API 网络不可达
500	500	Internal server error	服务内部未知异常

---

一、V1 特征接口

POST /api/v1/fortispay/payment-feature

响应说明

data.result 只保留 V1.xlsx 中的 536 个字段，6 个模块：

模块	字段数	说明
app_behavior	90	申请行为变量
loan_behavior	140	放款行为变量
repay_behavior	150	还款行为变量
time_structure	46	行为时间结构变量
delinq_monitor	50	逾期行为监控
flow_anomaly	60	资金流量异常监控变量

完整调用示例

curl -X POST http://{host}:{port}/api/v1/fortispay/payment-feature \
  -H "Content-Type: application/json" \
  -H "X-Request-Id: 9c6ccc0f3ad3886dfe56ed364b6dc3e8" \
  -H "X-Language: en" \
  -d '{
    "name": "ABCXYZ",
    "id_card": "3201190108990002",
    "mobile": "6285887456612"
  }'

---

二、V2 特征接口

POST /api/v1/fortispay/payment-feature-v2

响应说明

data.result 保留 V2.2.xlsx 中的 606 个特征字段（6 模块，不含综合评分）：

模块	字段数	相比 V1 新增
app_behavior	90	—
loan_behavior	150	+10（credit_to_apply_rate_by_org_cnt_day*）
repay_behavior	190	+40（还款与放款/申请的交叉比率）
time_structure	46	—
delinq_monitor	70	+20（逾期与申请/还款的交叉比率）
flow_anomaly	60	—

注意：比率类字段类型为 float（V1 中为 Int）。

完整调用示例

curl -X POST http://{host}:{port}/api/v1/fortispay/payment-feature-v2 \
  -H "Content-Type: application/json" \
  -H "X-Request-Id: 9c6ccc0f3ad3886dfe56ed364b6dc3e8" \
  -H "X-Language: en" \
  -d '{
    "name": "ABCXYZ",
    "id_card": "3201190108990002",
    "mobile": "6285887456612"
  }'

---

三、V2 评分接口

POST /api/v1/fortispay/payment-feature-v2-score

响应说明

data.result 只保留 V2.2.xlsx 中 overall_score 模块的 15 个字段：

字段	类型	说明
recent_risk_level_v1 ~ v5	Int	申请人即时风险资质等级 V1~V5
mid_risk_level_v1 ~ v5	Int	申请人阶段风险资质等级 V1~V5
long_risk_level_v1 ~ v5	Int	申请人长效风险资质等级 V1~V5

成功响应示例

{
  "code": "0",
  "message": "success",
  "responseId": "0b5a09b6ea7d77dbbbb92e05dc9744ad",
  "data": {
    "status": 1,
    "result": {
      "overall_score": {
        "recent_risk_level_v1": 7,
        "recent_risk_level_v2": 70,
        "recent_risk_level_v3": 8,
        "recent_risk_level_v4": 18,
        "recent_risk_level_v5": 35,
        "mid_risk_level_v1": 46,
        "mid_risk_level_v2": 47,
        "mid_risk_level_v3": 30,
        "mid_risk_level_v4": 87,
        "mid_risk_level_v5": 51,
        "long_risk_level_v1": 36,
        "long_risk_level_v2": 37,
        "long_risk_level_v3": 13,
        "long_risk_level_v4": 16,
        "long_risk_level_v5": 89
      }
    }
  }
}

完整调用示例

curl -X POST http://{host}:{port}/api/v1/fortispay/payment-feature-v2-score \
  -H "Content-Type: application/json" \
  -H "X-Request-Id: 9c6ccc0f3ad3886dfe56ed364b6dc3e8" \
  -H "X-Language: en" \
  -d '{
    "name": "ABCXYZ",
    "id_card": "3201190108990002",
    "mobile": "6285887456612"
  }'

---

缓存说明

三个接口共享同一套缓存。缓存以原始三方响应存储，命中缓存后按接口版本过滤 result 字段返回。同一用户查询任意接口后，其他接口命中缓存均无需再次调用三方。