API 方式
Base URL
- 新加坡节点:https://sg.apitd.net/verification/persona/transaction/v3
- 美国节点:https://us.apitd.net/verification/persona/transaction/v3
- 德国节点:https://de.apitd.net/verification/persona/transaction/v3
API
| URL | 请求方式 | Content-Type | 输出格式 | 字符集 |
|---|---|---|---|---|
| api-base-url?partner_code=xxx&partner_key=xxx | POST | application/json | JSON | UTF-8 |
认证参数
| 字段 | 类型 | 含义 | 建议 | 备注 |
|---|---|---|---|---|
| partner_code | String | 合作方标识 | 必须 | 由 TD 分配 |
| partner_key | String | 合作方密钥 | 必须 | 由 TD 分配 |
请求参数
| 字段名称 | 字段类型 | 是否必填 | 字段描述 | 备注 |
|---|---|---|---|---|
| transaction_time | String | 是 | 交易发生时间 | UTC标准时间,YYYYMMDDHHMMSS,如20260416134043 |
| transaction_amount | String | 是 | 交易金额 | 以该货币的最小单位表示。如果购买金额为 123.45 美元,则该字段的值应为 12345 |
| transaction_currencyexponent | String | 是 | 购买币种的小数位数 | 如果购买金额为 123.45 美元,则该字段的值为 2 |
| transaction_currency | String | 是 | 交易金额所使用的币种 | 采用 ISO-4217 货币代码表示,如840 |
| merchant_name | String | 是 | 商户名称 | |
| merchant_countrycode | String | 是 | 商户所属国家编码 | 所属国家/地区的 ISO-3166 国家代码,如840或US |
| mcc | String | 是 | 商户类别代码 | |
| ip | String | 否 | IP 地址 | 支持 IPV4 和 IPV6 |
| billing_name | String | 否 | 账单姓名 | 必须<=45字符 |
| billing_phone_country_id | String | 否 | 账单电话国家编码 | 如86 |
| billing_phone | String | 否 | 账单电话 | |
| billing_email | String | 否 | 账单邮箱 | |
| billing_address_country_id | String | 否 | 账单地址国家编码 | 所属国家/地区的 ISO-3166 国家代码,如840或US |
| billing_address_state_id | String | 否 | 账单地址州编码 | |
| billing_address_postal_id | String | 否 | 账单地址邮政编码 | |
| billing_address_city | String | 否 | 账单地址城市 | |
| billing_address_street1 | String | 否 | 账单邮寄地址1 | 必须<=50字符 |
| billing_address_street2 | String | 否 | 账单邮寄地址2 | 必须<=50字符 |
| shipping_name | String | 否 | 货运收件人姓名 | 必须<=100字符 |
| shipping_phone_country_id | String | 否 | 货运收件人电话国家编码 | 如86 |
| shipping_phone | String | 否 | 货运收件人电话 | |
| shipping_email | String | 否 | 货运收件人邮箱 | |
| shipping_address_country_id | String | 否 | 货运地址国家编码 | 所属国家/地区的 ISO-3166 国家代码,如840或US |
| shipping_address_state_id | String | 否 | 货运地址州编码 | |
| shipping_address_postal_id | String | 否 | 货运地址邮政编码 | |
| shipping_address_city | String | 否 | 货运地址城市 | |
| shipping_address_street1 | String | 否 | 货运邮寄地址1 | 必须<=50字符 |
| shipping_address_street2 | String | 否 | 货运邮寄地址2 | 必须<=50字符 |
| user_agent | String | 否 | 设备的 user-agent 字符串 | user-agent 必须代表服务消费方的 HTTP 客户端,并包含发起该请求的软件详细信息 |
| timezone | String | 否 | 消费者设备的时区,该时区必须表示为基于当前主机系统设置、相对于 UTC 的时区偏移分钟数 | |
| screen_width | String | 否 | 消费者设备的屏幕宽度 | |
| screen_height | String | 否 | 消费者设备的屏幕高度 | |
| language | String | 否 | 消费者设备的语言。该语言必须是一个按照 BCP 47 定义的语言版本字符串 | |
| colordepth | String | 否 | 设备屏幕的颜色深度值 | |
| model | String | 否 | 移动设备制造商和型号 | Android:返回移动设备的制造商和型号,例如:samsung SM-G960U1 iOS:设备型号,例如:iPhone10,4,注意:由于所有 iOS 设备的制造商均为 Apple,因此不包含制造商信息 |
| major_os_version | String | 否 | 主操作系统版本 | |
| minor_os_version | String | 否 | 次要操作系统版本 | |
| account_number | String | 否 | 交易账户号 | |
| card_last4 | String | 否 | 交易卡号后4位 | |
| card_expirydate | String | 否 | 交易卡有效期 | 格式为“YYMM” |
| card_bin | String | 否 | 交易卡bin | |
| acquirer_merchant_id | String | 否 | 由收单机构分配的、该交易所归属的商户 ID | |
| acquirer_bin | String | 否 | 收单机构的 BIN(银行识别号) | |
| work_phone_country_id | String | 否 | 工作电话国家编码 | 如86 |
| work_phone | String | 否 | 工作电话 | |
| extra | String | 否 | 扩展字段,Json 字符串格式 | 可为空 |
请求示例
{
"transaction_time": "20260416134043",
"ip": "23.129.64.214",
"billing_name": "xxxxxx",
"billing_phone_country_id": "1",
"billing_phone": "3143978691",
"billing_email": "[email protected]",
"billing_address_country_id": "840",
"billing_address_state_id": "TX",
"billing_address_postal_id": "63124",
"billing_address_city": "Houston",
"billing_address_street1": "912 Uclan Dr",
"shipping_name": "xxxxx",
"shipping_phone_country_id": "1",
"shipping_phone": "3143978691",
"shipping_email": "[email protected]",
"shipping_address_country_id": "840",
"shipping_address_state_id": "TX",
"shipping_address_postal_id": "63124",
"shipping_address_city": "Houston",
"shipping_address_street1": "912 Uclan Dr",
"extra": "",
"transaction_amount": "12500",
"transaction_currencyexponent": "2",
"transaction_currency": "840",
"merchant_name": "Acme Inc",
"merchant_countrycode": "US",
"mcc": "5411",
"user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/147.0.0.0 Safari/537.36",
"timezone": "600",
"screen_width": "1512",
"screen_height": "982",
"language": "en-GB",
"colordepth": "30",
"model": "iPhone10.4",
"major_os_version": "12",
"minor_os_version": "0",
"account_number": "4111111111111111",
"card_last4": "1111",
"card_expirydate": "2311",
"card_bin": "411111",
"acquirer_merchant_id": "ACME",
"acquirer_bin": "444444",
"work_phone_country_id": "1",
"work_phone": "3143978691"
}响应参数
| 字段名称 | 字段类型 | 字段描述 | 备注 |
|---|---|---|---|
| code | Integer | API 状态码 | |
| message | String | 状态信息 | 在 API 异常状态下会输出具体的异常原因 |
| sequence_id | String | 响应唯一码 | 用于跟踪每次请求记录的唯一标识 |
| risk_score | Integer | 综合风险分,范围 0 - 100 | |
| risk_score_reason_code | String | 综合风险原因 | 含义详见附录1 |
| device_risk_score | Integer | 设备风险分,范围 0 - 100 | |
| ip_risk_score | Integer | IP 风险分,范围 0 - 100 | |
| ip_carrier | String | IP运营商 | |
| ip_connection_type | String | IP 连接类型 | cable-dsl:有线 corporate:公司 cellular:蜂窝 dialup:拨号 |
| ip_geolocation_city | String | IP地址所属城市 | |
| ip_geolocation_country_code | String | IP 地址所属国家编码 | |
| ip_geolocation_state | String | IP地址所属州 | |
| ip_last_seen_days | Integer | IP 地址最近一次出现至今的天数 | |
| ip_proxy | Boolean | 是否代理IP | |
| ip_proxy_riskclass | String | IP代理类型风险程度 | |
| billing_address_first_seen_days | Integer | 账单邮寄地址首次出现至今的天数 | |
| billing_address_last_seen_days | Integer | 账单邮寄地址最后出现至今的天数 | |
| billing_address_shipping_address_relationship | String | 账单地址与货运地址的关系 | match:匹配 city_match:城市匹配 seen_together:一起出现过 seen_with_others:账单地址与其他购物地址一起出现过 no_relationship:没有关系 null:地址无效或者不详细 |
| billing_address_to_name | String | 账单邮寄地址与账单姓名是否匹配 | not-found:无记录 match:匹配 no-match:不匹配 |
| billing_address_validity_level | String | 账单邮寄地址合法等级 | missing_address:地址缺失 invalid:非法 valid_to_country:国家合法 valid_to_city:国家、城市合法 valid_to_street:国家、城市、街道合法 valid_to_house_number:国家、城市、街道和门牌号合法 valid_to_house_number_missing_apt:国家、城市、街道和门牌号码合法,但 apartment 不合法 valid:合法 |
| billing_email_disposable | Boolean | 账单邮箱是否为一次性邮箱域名 | |
| billing_email_domain_creation_date | String | 电子邮件域的创建日期 | |
| billing_email_first_seen_days | Integer | 账单邮箱首次出现至今的天数 | |
| billing_email_last_seen_days | Integer | 账单邮箱最后出现至今的天数 | |
| billing_email_risk_score | Integer | 邮箱风险分,范围0-100 | |
| billing_email_to_name | String | 账单邮箱与账单姓名是否匹配 | not-found:无记录 match:匹配 no-match:不匹配 |
| billing_email_valid | Boolean | 账单邮箱是否合法 | true:合法 false:不合法 |
| billing_email_velocity | Integer | 账单邮箱在过去 180 天内被观测到的次数 | |
| billing_ip_address_distance | Integer | 账单邮寄地址与 IP 地址的距离(英里) | |
| billing_phone_carrier | String | 账单电话运营公司 | |
| billing_phone_to_name | String | 账单电话与账单姓名是否匹配 | not-found:无记录 match:匹配 no-match:不匹配 |
| billing_phone_type | String | 账单电话类型 | landline:传统座机 fixed-voip:固定 voip,互联网电话 non-fixed-voip:非固定 voip (虚拟号码) mobile:手机 voicemail:语音信箱 toll-free:免费电话,被叫方付费 premium:付费电话,呼叫方付费 other:其他 |
| billing_phone_valid | Boolean | 账单电话是否合法 | true:合法 false:不合法 |
| shipping_address_first_seen_days | Integer | 货运邮寄地址首次出现至今的天数 | |
| shipping_address_last_seen_days | Integer | 货运邮寄地址最后出现至今的天数 | |
| shipping_address_to_name | String | 货运邮寄地址与货运收件人姓名是否匹配 | not-found:无记录 match:匹配 no-match:不匹配 |
| shipping_address_validity_level | String | 货运邮寄地址合法等级 | missing_address:地址缺失 invalid:非法 valid_to_country:国家合法 valid_to_city:国家、城市合法 valid_to_street:国家、城市、街道合法 valid_to_house_number:国家、城市、街道和门牌号合法 valid_to_house_number_missing_apt:国家、城市、街道和门牌号码合法,但 apartment 不合法 valid:合法 |
| shipping_ip_address_distance | Integer | 货运邮寄地址与 IP 地址的距离(英里) | |
| shipping_phone_carrier | String | 货运电话运营公司 | |
| shipping_phone_to_name | String | 货运电话与姓名是否匹配 | not-found:无记录 match:匹配 no-match:不匹配 |
| shipping_phone_type | String | 货运电话类型 | landline:传统座机 fixed-voip:固定 voip,互联网电话 non-fixed-voip:非固定 voip (虚拟号码) mobile:手机 voicemail:语音信箱 toll-free:免费电话,被叫方付费 premium:付费电话,呼叫方付费 other:其他 |
| shipping_phone_valid | Boolean | 货运收件人电话是否合法 | true:合法 false:不合法 |
| browser | String | 浏览器名称 | |
| device_email_payment_first_seen_days | Integer | 设备 邮箱 支付信息 - 首次出现天数 | |
| device_ip_email_first_seen_days | Integer | 设备 IP 邮箱 - 首次出现天数 | |
| device_ip_first_seen_days | Integer | 设备 IP - 首次出现天数 | |
| device_ip_payment_first_seen_days | Integer | 设备 IP 支付信息 - 首次出现天数 | |
| device_ip_tz_difference | String | 设备浏览器时区与 IP 时区差异 | 设备浏览器时区与 IP 时区差异 Null: 无效输入 0 – 低风险 1 - 中风险 2+ – 高风险 |
| device_type | String | 设备类型 | |
| platform | String | 设备平台名称 | |
| card_holder_name_first_seen_days | Integer | 支付卡持卡人姓名首次出现天数 | |
| card_holder_name_velocity | Integer | 在过去 90 天内,支付卡与持卡人姓名这一组合在网络中被观察到的次数 | |
| merchant_category_ratio | String | 购买金额相对于同类别其他相似商户的购买金额中位数的比率,比率越高,风险越高 | |
| work_phone_carrier | String | 工作电话运营商 | |
| work_phone_to_name | String | 工作电话与姓名是否匹配 | not-found:无记录 match:匹配 no-match:不匹配 |
| work_phone_type | String | 工作电话类型 | landline:传统座机 fixed-voip:固定voip,互联网电话 non-fixed-voip:非固定 voip (虚拟号码) mobile:手机 voicemail:语音信箱 toll-free:免费电话,被叫方付费 premium:付费电话,呼叫方付费 other:其他 |
| work_phone_valid | Boolean | 工作电话是否合法 | true:合法 false:不合法 |
API 状态码
| code | 含义 |
|---|---|
| 200 | 成功 |
| 301 | 未购买此服务 |
| 302 | 流量已被禁用 |
| 303 | 流量不足 |
| 304 | 服务已过期 |
| 305 | 日流量已封顶 |
| 9600 | 系统错误 |
| 9606 | 参数非法 |
响应示例
{
"code": 200,
"message": "",
"sequence_id": "1648777165770866F82AC7F326307055",
"risk_score": 77,
"risk_score_reason_code": "JB",
"device_risk_score": 98,
"ip_risk_score": 86,
"ip_last_seen_days": 0,
"ip_geolocation_country_code": "US",
"ip_geolocation_city": "Colorado Springs",
"ip_carrier": "xxxxxxx",
"ip_geolocation_state": "Colorado",
"ip_proxy": true,
"ip_proxy_riskclass": "high",
"ip_connection_type": "cable-dsl",
"billing_email_risk_score": 89,
"billing_email_valid": true,
"billing_email_velocity": 9,
"billing_email_disposable": false,
"billing_email_to_name": "match",
"billing_email_domain_creation_date": "1995-08-13",
"billing_email_first_seen_days": 6979,
"billing_email_last_seen_days": 0,
"billing_phone_valid": true,
"billing_phone_type": "premium",
"billing_phone_carrier": "xxxxxx",
"billing_phone_to_name": "no-match",
"billing_ip_address_distance": 954,
"billing_address_validity_level": "valid",
"billing_address_to_name": "no-match",
"billing_address_first_seen_days": 1437,
"billing_address_last_seen_days": 0,
"billing_address_shipping_address_relationship": "match",
"shipping_phone_valid": true,
"shipping_ip_address_distance": 954,
"shipping_address_validity_level": "valid",
"shipping_address_to_name": "no-match",
"shipping_address_first_seen_days": 1011,
"shipping_address_last_seen_days": 0,
"shipping_phone_to_name": "no-match",
"shipping_phone_type": "premium",
"shipping_phone_carrier": "xxxxx",
"device_type": "Mac",
"browser": "Chrome",
"platform": "Mac OS X",
"device_ip_tz_difference": 840,
"device_ip_first_seen_days": 0,
"device_ip_payment_first_seen_days": 0,
"device_ip_email_first_seen_days": 0,
"device_email_payment_first_seen_days": 0,
"work_phone_to_name": "no-match",
"work_phone_valid": true,
"work_phone_type": "premium",
"work_phone_carrier": "xxxxx",
"card_holder_name_first_seen_days": 0,
"card_holder_name_velocity": 0,
"merchant_category_ratio": 2.6
}附录1
| Reason code | 含义 |
|---|---|
| AA | 消费者身份可疑 |
| AB | 与邮箱相关的风险升高 |
| AC | 与邮箱和IP相关的风险升高 |
| AD | 与邮箱和地址相关的风险升高 |
| AE | 与邮箱和电话相关的风险升高 |
| AF | 与邮箱和姓名相关的风险升高 |
| AG | 与IP相关的风险升高 |
| AH | 与IP和电话相关的风险升高 |
| AI | 与IP和地址相关的风险升高 |
| AJ | 与IP和姓名相关的风险升高 |
| AK | 与地址相关的风险升高 |
| AL | 与地址和电话相关的风险升高 |
| AM | 与地址和姓名相关的风险升高 |
| AN | 与姓名相关的风险升高 |
| AO | 与姓名和电话相关的风险升高 |
| AP | 与电话相关的风险升高 |
| AQ | 与设备和邮箱相关的风险升高 |
| AR | 与设备和IP相关的风险升高 |
| AS | 与地址和设备相关的风险升高 |
| AT | 与设备和姓名相关的风险升高 |
| AU | 与设备和电话相关的风险升高 |
| AV | 与邮箱和支付信息相关的风险升高 |
| AW | 与IP和支付信息相关的风险升高 |
| AX | 与地址和支付信息相关的风险升高 |
| AY | 与姓名和支付信息相关的风险升高 |
| AZ | 与支付信息和电话相关的风险升高 |
| JA | 新消费者或信息不足 |
| JB | 与邮箱相关的中等风险信号 |
| JC | 与地址相关的中等风险信号 |
| JD | 与电话相关的中等风险信号 |
| JE | 与姓名相关的中等风险信号 |
| JF | 与IP相关的中等风险信号 |
| RA | 在所有要素上均已建立消费者可信度 |
| RB | 邮箱可信度已建立 |
| RC | 邮箱和IP可信度已建立 |
| RD | 邮箱和地址可信度已建立 |
| RE | 邮箱和电话可信度已建立 |
| RF | 邮箱和姓名可信度已建立 |
| RG | IP可信度已建立 |
| RH | IP和电话可信度已建立 |
| RI | IP和地址可信度已建立 |
| RJ | IP和姓名可信度已建立 |
| RK | 地址可信度已建立 |
| RL | 地址和电话可信度已建立 |
| RM | 地址和姓名可信度已建立 |
| RN | 姓名可信度已建立 |
| RO | 姓名和电话可信度已建立 |
| RP | 电话可信度已建立 |
| RQ | 设备和邮箱可信度已建立 |
| RR | 设备和IP可信度已建立 |
| RS | 地址和设备可信度已建立 |
| TY | 设备和姓名可信度已建立 |
| RU | 设备和电话可信度已建立 |
| RV | 邮箱和支付信息可信度已建立 |
| RW | IP和支付信息可信度已建立 |
| RX | 地址和支付信息可信度已建立 |
| RY | 姓名和支付信息可信度已建立 |
| RZ | 支付信息和电话可信度已建立 |
