交易反欺诈风险验证 API 用于您实时获取我们的风险验证结果。
为了有效地阻止欺诈发生并避免资金损失，建议您在进行支付网关的资金授权之前发送请求进行风险验证，或在收到支付网关的授权响应后但在获取资金之前立即发送请求进行风险验证。这样可以确保在进行资金交易之前对风险进行有效验证。
API 方式
Base URL
- 中国节点：https://cn.apitd.net/fraud/transaction/v2
- 美国节点：https://us.apitd.net/fraud/transaction/v2
- 新加坡节点：https://sg.apitd.net/fraud/transaction/v2
- 德国节点：https://de.apitd.net/fraud/transaction/v2
API
| URL | 请求方式 | Content-Type | 输出格式 | 字符集 |
|---|---|---|---|---|
| api-base-url?partner_code=xxx&partner_key=xxx | POST | application/json | JSON | UTF-8 |
示例：https://cn.apitd.net/fraud/transaction/v2?partner_code=test_code&partner_key=test_key
认证参数
| 字段 | 类型 | 含义 | 建议 | 备注 |
|---|---|---|---|---|
| partner_code | String | 合作方标识 | 必须 | 由 TD 分配 |
| partner_key | String | 合作方密钥 | 必须 | 由 TD 分配 |
请求参数
| 字段 | 类型 | 含义 | 建议 | 备注 |
|---|---|---|---|---|
| channel | String | 渠道标识 | 必须 | 由 TD 分配 |
| session_id | String | 会话 ID | 必须 | 会话 ID 是网站服务器为特定用户在访问期间分配的唯一标识，通常可以用 Cookie、表单字段或 URL 的形式存储 |
| decision_event | String | 风险验证时的业务节点 | 必须 | 枚举值： order_payment：支付订单 |
| event_time | String | 业务真实发生时间 | 必须 | 符合 ISO 8601 标准，格式 YYYY-MM-DDTHH:mm:ss.sssZ ，例如 2021-10-12T14:20:50.521+07:00 |
| account_id | String | 账户 ID | 条件必须：当账户注册（创建）后必须 | 当账户不存在时可不传 |
| order_id | String | 订单号 | 必须 | |
| terminal | Terminal | 终端信息 | 必须 | |
| ext | Ext | 扩展信息 | 条件必须：如果扩展信息用于本次决策则必须 | 与 TD 约定好的扩展信息 |
| account | Account | 账户信息 | 强烈建议 | |
| order | Order | 订单信息 | 必须 | |
| payment | Payment | 支付信息 | 强烈建议 | |
| payment_result | PaymentResult | 支付结果 | 强烈建议 | |
| billing | Billing | 账单信息 | 强烈建议 | |
| merchant | Merchant | 卖家信息 | 强烈建议 |
请求示例
{
"channel": "test",
"session_id": "abc0123456789",
"decision_event": "order_payment",
"event_time": "2023-10-12T14:20:50.521+07:00",
"account_id": "123456789",
"order_id": "ID293846237467",
"terminal": {
"black_box": "aGPH1658920283672ropYaFxT7",
"ip": "210.20.10.33"
},
"ext": {
"ext_book_id": "LFOUHOFHOHFNOUH",
"ext_book_num": 10
},
"account": {
"register_time": "2021-10-12T14:20:50.521+07:00",
"login_time": "2021-10-12T14:25:50.521+07:00",
"phone": {
"country_code": 86,
"phone_number": "18700001111"
},
"email": "[email protected]"
},
"order": {
"order_create_time": "2021-10-12T14:25:50.521+07:00",
"merchandise_list": [
{
"merchandise_id": "NFH837824432",
"category_1": "3c",
"category_2": "phone",
"category_3": "android",
"name": "huawei phone",
"count": 1,
"unit_price": {
"currency": "CNY",
"amount_local": 6800,
"amount_usd": 1000,
"amount_cny": 6800
}
}
],
"amount": {
"currency": "CNY",
"amount_local": 6800,
"amount_usd": 1000,
"amount_cny": 6800
},
"shipping": {
"address": {
"country": "CN",
"region": "浙江省",
"city": "杭州市",
"district": "余杭区",
"detail": "文一西路海创园 18 幢",
"zip_code": "310000"
},
"phone": {
"country_code": 86,
"phone_number": "18700001112"
},
"email": "[email protected]",
"consignee": {
"first_name": "三",
"middle_name": "",
"last_name": "张",
"nickname": "HZhang"
},
"method": "logistics"
}
},
"payment": {
"payment_id": "NHF8736274",
"method": "card",
"channel": "paypal",
"amount": {
"currency": "CNY",
"amount_local": 68,
"amount_usd": 10,
"amount_cny": 68
},
"card": {
"card_bin": "622207",
"last_four_digits": "1234",
"card_number_length": 16,
"holder_name": {
"first_name": "三",
"middle_name": "",
"last_name": "张",
"nickname": "HZhang"
},
"debit_or_credit": "credit",
"issuer_region": "CN",
"expiration_date": "1998-01-01"
},
"is_coupon_used": true,
"coupons": [
{
"coupon_id": "NOHF08938",
"coupon_name": "双十一限时购",
"coupon_count": 1,
"begin_time": 1596358039000,
"expire_time": 1616358039000,
"coupon_type": "discount",
"coupon_rate": 0.85,
"coupon_threshold": "10",
"cash_back_amount": {
"currency": "CNY",
"amount_local": 6.8,
"amount_usd": 1,
"amount_cny": 6.8
}
}
]
},
"payment_result": {
"is_payment_success": true,
"payment_message": "success",
"is_3ds_used": false,
"response_by_3ds": {
"eci_value": "02",
"version": "2.2.0",
"authentication_type": "01",
"trans_status": "Y"
},
"response_by_avs": "",
"response_by_cvc": ""
},
"billing": {
"address": {
"country": "CN",
"region": "浙江省",
"city": "杭州市",
"district": "余杭区",
"detail": "文一西路海创园 18 幢",
"zip_code": "310000"
},
"phone": {
"country_code": 86,
"phone_number": "18700001112"
},
"email": "[email protected]",
"recipient": {
"first_name": "三",
"middle_name": "",
"last_name": "张",
"nickname": "HZhang"
}
},
"merchant": {
"merchant_id": "NFK00937",
"shop_name": "Hello World",
"shop_phone": {
"country_code": 86,
"phone_number": "18700001112"
},
"shop_email": "[email protected]",
"shop_address": {
"country": "CN",
"region": "浙江省",
"city": "杭州市",
"district": "余杭区",
"detail": "文一西路海创园 18 幢",
"zip_code": "310000"
},
"shop_url": "https://td/shop/0012",
"register_time": "2021-10-12T14:20:50.521+07:00",
"login_time": "2021-10-12T14:22:50.521+07:00",
"merchant_type": "entity",
"merchant_level": "A",
"company": "XXX",
"primary_category": "XXXX",
"product_count": 1,
"history_order_count": 1,
"history_order_amount": {
"currency": "CNY",
"amount_local": 68,
"amount_usd": 10,
"amount_cny": 68
}
}
}
响应参数
| 字段 | 类型 | 含义 | 建议 | 备注 |
|---|---|---|---|---|
| code | Integer | API 状态码 | 必须 | |
| message | String | 状态信息 | 必须 | 在 API 异常状态下会输出具体的异常原因 |
| sequence_id | String | 响应唯一码 | 必须 | 用于跟踪每次请求记录的唯一标识 |
| score | Integer | 风险分 | 必须 | 范围为 0 - 100 |
| result | String | 决策结果 | 必须 | 枚举值： decline：拒绝 review：核验 accept：通过 |
| reasons | Array | 决策原因列表 | 必须 | |
| id | String | 决策原因 ID | 必须 | 每个决策原因都会有一个唯一编码 |
| reason | String | 决策原因 | 必须 |
API 状态码
| code | 含义 |
|---|---|
| 200 | 成功 |
| 301 | 未购买此服务 |
| 302 | 流量已被禁用 |
| 303 | 流量不足 |
| 304 | 服务已过期 |
| 305 | 日流量已封顶 |
| 9001 | {字段名}为空 |
| 9002 | {字段名}参数校验错误 |
| 9003 | {字段名}参数长度或者大小超过1024 |
| 9004 | black_box或ip至少存在一个 |
| 9200 | 系统异常 |
| 9201 | 未知异常 |
| 9202 | content-type不合法 |
响应示例
{
"code": 200,
"message": "",
"sequence_id": "1648777165770866F82AC7F326307055",
"score": 90,
"result": "decline",
"reasons": [
{
"id": "IDZPQJEG",
"reason": "可疑的交易行为"
}
]
}