历史订单（强烈建议）

历史订单 API 是 TD 系统的一项重要数据接入能力，旨在通过标准化接口获取商户的历史订单信息，为交易风险识别、模型效果评估与持续优化提供更完整的数据基础。

通过历史订单 API，TD 能够更充分地了解商户的业务特征、历史交易分布及用户交易行为，为风险分析提供更加丰富的上下文。相较于仅依赖单笔订单信息，结合历史交易记录进行综合判断，有助于发现单次交易中不易识别的异常模式与潜在风险，同时更准确地区分正常用户的偶发异常行为与可疑交易。

此外，历史订单数据能够为交易模型的特征分析、训练验证及效果优化提供支持。在历史订单具备有效交易结果和风险标签的情况下，TD 可进一步分析不同业务场景下的欺诈特征，评估模型的风险识别表现，并据此优化模型与策略，帮助商户在提升欺诈识别能力的同时，降低误报率，改善正常订单的通过率。

对于新接入的商户，历史订单 API 还能够补充接入前的交易数据，减少仅依靠新增订单积累样本的限制，帮助 TD 更早建立对商户业务及风险特征的理解。通过历史数据的补充与后续交易数据的积累，TD 能够为商户提供更贴合实际业务场景的交易风险管理支持。

API 方式

Base URL

中国节点：https://cn-event.apitd.net/order/history/v3
美国节点：https://us-event.apitd.net/order/history/v3
新加坡节点：https://sg-event.apitd.net/order/history/v3
德国节点：https://de-event.apitd.net/order/history/v3

API

URL	请求方式	Content-Type	输出格式	字符集
api-base-url?partner_code=xxx&partner_key=xxx	POST	application/json	JSON	UTF-8

示例：https://cn-event.apitd.net/order/history/v3?partner_code=test_code&partner_key=test_key

认证参数

字段	类型	含义	建议	备注
partner_code	String	合作方标识	必须	由 TD 分配
partner_key	String	合作方密钥	必须	由 TD 分配

请求参数

字段	类型	含义	建议	备注
channel	String	渠道标识	必须	由 TD 分配
account_id	String	账户 ID	必须
order_id	String	订单号	必须
payment_id	String	支付流水号	条件必须：如果有支付信息则必须
terminal	Terminal	终端信息	强烈建议
account	Account	账户信息	强烈建议
order	Order	订单信息	必须
payment	Payment	支付信息	必须
payment_result	PaymentResult	支付结果	强烈建议
billing	Billing	账单信息	强烈建议
merchant	Merchant	卖家信息	强烈建议
refund_result	RefundResult	退款结果	强烈建议
chargeback_result	ChargebackResult	拒付结果	强烈建议

请求示例

{
    "channel": "test",
    "account_id": "123456789",
    "order_id": "ID293846237467",
    "payment_id": "PID29384623788",
    "terminal": {
        "black_box": "aGPH1658920283672ropYaFxT7",
        "ip": "210.20.10.33"
    },
    "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
        }
    },
    "refund_result": {
        "refund_amount": {
            "currency": "CNY",
            "amount_local": 68,
            "amount_usd": 10,
            "amount_cny": 68
        },
        "refund_reason": "XXX"
    },
    "chargeback_result": {
        "chargeback_amount": {
            "currency": "CNY",
            "amount_local": 68,
            "amount_usd": 10,
            "amount_cny": 68
        },
        "chargeback_reason": "XXX",
        "chargeback_process": "need_response"
    }
}

响应参数

字段	类型	含义	建议	备注
code	Integer	API 状态码	必须
message	String	状态信息	必须	在 API 异常状态下会输出具体的异常原因
sequence_id	String	响应唯一码	必须	用于跟踪每次请求记录的唯一标识
results	Array	上报状态列表	必须
event_type	String	事件类别	必须
code	Integer	事件上报状态码	必须
message	String	事件上报状态信息	必须

API 状态码

code	含义
200	成功
301	未购买此服务
302	流量已被禁用
303	流量不足
304	服务已过期
305	日流量已封顶
9001	{字段名}为空
9002	{字段名}参数校验错误
9003	{字段名}参数长度或者大小超过1024
9200	系统异常
9201	未知异常
9202	content-type不合法
9203	没有对应的策略配置
9204	格式不支持
9205	get请求不支持
9206	系统环境异常

响应示例

{
    "code": 200,
    "message": "",
    "sequence_id": "1648777165770866F82AC7F326307055",
    "results": [
        {
            "event_type": "order_create",
            "code": 200,
            "message": "成功"
        },
        {
            "event_type": "order_payment_result",
            "code": 200,
            "message": "成功"
        },
    ]
}