API Reference
English

风险验证(必要)

交易反欺诈风险验证 API 用于您实时获取我们的风险验证结果。

为了有效地阻止欺诈发生并避免商品或资金损失,建议您在以下业务节点发送请求进行风险验证。通过在这些关键环节进行验证,您可以确保最大程度地保护商品和资金的安全。

  • 创建订单时,这样可以有效的阻止如恶意抢占库存等欺诈行为。
  • 支付订单时,建议您在进行支付网关的资金授权之前发送请求进行风险验证,或在收到支付网关的授权响应后但在获取资金之前立即发送请求进行风险验证。这样可以确保在进行资金交易之前对风险进行有效验证。

API 方式

Base URL

API

URL请求方式Content-Type输出格式字符集
api-base-url?partner_code=xxx&partner_key=xxxPOSTapplication/jsonJSONUTF-8

示例:https://cn.apitd.net/fraud/transaction/v3?partner_code=test_code&partner_key=test_key

认证参数
字段类型含义建议备注
partner_codeString合作方标识必须由 TD 分配
partner_keyString合作方密钥必须由 TD 分配

请求参数

字段类型含义建议备注
channelString渠道标识必须由 TD 分配
session_idString会话 ID必须会话 ID 是网站服务器为特定用户在访问期间分配的唯一标识,通常可以用 Cookie、表单字段或 URL 的形式存储
decision_eventString风险验证时的业务节点必须枚举值:
order_create:创建订单
order_payment:支付订单
event_timeString业务真实发生时间必须符合 ISO 8601 标准,格式 YYYY-MM-DDTHH:mm:ss.sssZ ,例如 2021-10-12T14:20:50.521+07:00
account_idString账户 ID条件必须:当账户注册(创建)后必须当账户不存在时可不传
order_idString订单号必须
terminalTerminal终端信息必须
extExt扩展信息条件必须:如果扩展信息用于本次决策则必须与 TD 约定好的扩展信息
accountAccount账户信息强烈建议
orderOrder订单信息必须
paymentPayment支付信息强烈建议
payment_resultPaymentResult支付结果强烈建议
billingBilling账单信息强烈建议
merchantMerchant卖家信息强烈建议

请求示例

{
    "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
        }
    }
}

响应参数

字段类型含义建议备注
codeIntegerAPI 状态码必须
messageString状态信息必须在 API 异常状态下会输出具体的异常原因
sequence_idString响应唯一码必须用于跟踪每次请求记录的唯一标识
scoreInteger风险分必须范围为 0 - 100
resultString决策结果必须枚举值:
decline:拒绝
review:核验
accept:通过
reasonsArray决策原因列表必须
idString决策原因 ID必须每个决策原因都会有一个唯一编码
reasonString决策原因必须

API 状态码

code含义
200成功
301未购买此服务
302流量已被禁用
303流量不足
304服务已过期
305日流量已封顶
9001{字段名}为空
9002{字段名}参数校验错误
9003{字段名}参数长度或者大小超过1024
9004black_box或ip至少存在一个
9200系统异常
9201未知异常
9202content-type不合法
9203没有对应的策略配置

响应示例

{
    "code": 200,
    "message": "",
    "sequence_id": "1648777165770866F82AC7F326307055",
    "score": 90,
    "result": "decline",
    "reasons": [
        {
            "id": "IDZPQJEG",
            "reason": "可疑的交易行为"
        }
    ]
}