更新日志
版本号 | 更新日期 | 描述 |
Alert_V1.5 | 2025.09.03 | 1.【ETHOCA预警反馈】增加【refunded】字段的枚举值,目前为7种反馈状态:
refunded (已匹配到交易并退款)
ignore (已匹配到交易但不做处理)
notfound (未匹配到对应交易)
chargeback_beforealert(原交易预警前已拒付)
refunded_beforealert(原交易预警前已退款)
transaction_failed(原交易状态为失败)
duplicate_alert(重复预警) |
Alert_V1.4 | 2025.08.12 | 1. 【ETHOCA预警通知】增加字段:descriptorRegister:注册时报送的descriptor
2. 【RDR预警通知】增加字段:descriptorRegister :注册时报送的descriptor |
Alert_V1.3 | 2025.08.05 | 1. 【ETHOCA预警通知】增加字段:alertStatus: 预警状态
timeOut:反馈截止时间
reasonCode:拒付原因码
2. 【RDR预警通知】增加字段:
alertStatus: 预警状态
timeOut:反馈截止时间
reasonCode:拒付原因码
merchantOrderId: VISA返回的商户ID
outcome:预警结果: |
Alert_V1.2 | 2025.05.24 | 新增
【3. 商户卡账单报备】
【4. 商户卡账单状态结果通知】
【5. 商户卡账单报备关闭】 |
Alert_V1.1 | 2023.10.18 | 上线拒付预警系统 |
业务流程
- 了解拒付预警的其他业务细节:常见问题解答
- 您可以通过跨拒通客户端直接使用拒付预警服务,而不需要对接API:客户端使用说明
对接前准备
- 通过 support@tradefensor.com 联系我们,提供您接收API_KEY等信息的电子邮件地址、以及您接收主动或手动服务的 API URL(例如https://www.tradefensor.com/api/notify/auto)
- 我们将向您的邮箱发送凭据,这些凭据用于识别和授权使用API服务,包括:
- MerchantNo,将用于在使用 API 时识别您的身份并获取用于访问受限资源的授权令牌
- SignKey,需要它来获取用于访问受限资源的授权令牌
- 请在您的生产环境中将 IP/s 列入白名单。例如eg. 111.222.333.444
- 加密方式:MD5 参与签名的参数按照ASCII码从小到大排序,将参数按固定顺序组装成签名原始串以“&”拼接,最后在拼接上商户密钥。签名的参数顺序和格式如下:key1=value1&key2=value2...keyn=valuen*****)
查看加密代码
- 接口参数:
- API 域名生产环境:
https://mer.tradefensor.com - 通讯方式:
https+JSON - 字符集:
UTF-8 - 加密方式:
MD5 Salt - Request Header:开始使用 API时,在请求 Header中设置以下属性
- MerchantNo,必填,由跨拒通提供
- SignKey,必需,加密 body内容字符串进行
- Request Body:Content Type
application/json
对接流程图
对接步骤
步骤1: 提交商户注册信息
- 调用方向:Merchant → Securego
- Path: /rest/third/predictor/merchant/alert/add
Request Payload
Field Name
Field Type
Required
Description
Example
notifyUrl
string
Required
通知地址,处理结果通过该 URL 反馈,请务必确保该 URL 可正常访问
https://mer.tradefensor.com/rest/alert/callback
alertType
string
Required
预警类型,枚举值:
- Ethoca
- RDR
Ethoca
descriptor
string
Required
Descriptor 是信用卡交易中客户账单上显示的描述信息,通常用于帮助客户识别这笔交易是从哪个商户发起的。
BOOKSTORE
cardBin
string
Conditionally required
银行卡前 6 或 8 位号码,用于识别收单机。当 alertType 为 RDR时必填,为ethoca时可以不填
430123
caid
string
Conditionally required
Card Acceptor ID,即“商户识别号”或“终端商户编号”,由收单银行或支付机构分配,用于在VISA网络中唯一标识一个商户实体。当 alertType 为 RDR时必填,为ethoca时可以不填
123456789012345(长度通常为15位)
dba
string
Optional
商户对外展示的名称(“以…名称经营”),即顾客在对账单或交易凭证上看到的商户名称。
QuickBuy HK Store
mcc
string
Optional
商户类别代码,用于表示商户所属的业务类型
5815:数字商品(Digital Goods)
website
string
Optional
商户网站地址
www.abc.com
arn
string
Optional
Acquirer Reference Number,即收单方参考号。常见为 23~24 位的纯数字,例如74843812345678901234567
74843812345678901234567
Response Payload
Field Name
Field Type
Required
Description
Example
status
boolean
Required
表示系统是否正常接收请求
true
message
string
Optional
若无法报备,则返回错误
System Error
data
object
Optional
data.status
string
Required
-WAITING: 等待预警开通中
-EFFECTED:已生效
-CLOSING:关闭中
-CLOSED:已关闭
WAITING
步骤2: Securego回复商户注册/关闭结果通知
- 调用方向:Securego → Merchant
Request Payload
Field Name
Field Type
Required
Description
Example
status
string
Required
枚举值:
1. WAITING(等待预警开通中)
2. EFFECTED(已生效)
3. CLOSING(关闭中)
4. CLOSED(已关闭)
EFFECTED
message
string
Optional
报备失败时,卡组返回的失败原因
报备失败
alertType
string
Required
报备类型,可选值
- Ethoca
- RDR
Ethoca
dba
string
Required
dba
descriptor
string
Required
卡账单
www.descriptor.com
mcc
string
Optional
当 alertType 为 RDR时,必填
cardBin
string
Optional
当 alertType 为 RDR时,必填
caid
string
Optional
当 alertType 为 RDR时,必填
website
string
Optional
当 alertType 为 RDR时,必填
arn
string
Optional
当 alertType 为 RDR时,必填
Response Payload
Field Name
Field Type
Required
Description
Example
status
boolean
Required
表示系统是否正常接收请求
true
message
string
Optional
若无法正常接收,则返回错误
System Error
步骤3: 预警通知
- 调用方向:Securego → Merchant
- 发生拒付预警时,Securego 会通过您先前报备的API URL传送预警信息
Request Payload ( ETHOCA)
Field Name
Field Type
Required
Description
Example
id
string
Required
贸御系统预警单唯一 id
902f4dc650ac4da48a138bfb2ec66703
alertId
string
Required
争议记录 id,Ethoca返回的唯一预警 id
5FWS6ZMJ72BF5C9LKBAHGAGJU
preAlertTypestring
Required
预警推送类型,固定值 Ethoca
Ethoca
age
string
Required
预警时间间隔,指交易日期/时间(授权日期/时间) 与预警创建时间之间的小时数
786
alertTime
string
Required
预警创建时间,UTC标准时间:YYYY-MM-DD hh:mm:ss
2024-05-03 17:54:48
alertType
string
Required
争议类型: dispute or fraud
dispute
amount
string
Required
交易金额
5000
currency
string
Required
交易币种,ISO 4217三位大写字母代码
USD
descriptor
string
Required
ETHOCA返回的descriptor
SP KIVAS.COM
alertSource
string
Optional
预警来源
VISA
arn
string
Optional
收单行参考号ARN,它只适用于已结算的交易
72231884092900061779028
authCode
string
Optional
授权码
031710
cardBin
string
Optional
卡bin前 8位
10293800
cardNumber
string
Optional
卡号,可以为全卡号或前6后4 (当“alertType”值为 dispute时,不一定提供该值;当值为 fraud时,总会提供该值)
031710
chargebackCode
string
Optional
拒付原因代码
REFUND
disputeAmount
string
Optional
争议金额,可以与交易金额不同
5000
disputeCurrency
string
Optional
争议币种,ISO 4217标准
USD
initiatedBy
string
Optional
交易由谁确认: issuer 发卡行, cardholder 持卡人, not_available 未提供值
issuer
issuer
string
Optional
发卡号名称
OCBC
liability
string
Optional
是否是3D安全交易责任方: yes 发卡行, no 商户, not_available 未提供值
yes
merchantCategoryCode
string
Optional
商户类别代码
02918
transactionId
string
Optional
卡组织分配的交易ID(当“alertType”值为 dispute时,才有可能传输此字段的值)
104877299
transactionTime
string
Optional
交易的日期,UTC标准时间:YYYY-MM-DDThh:mm:ss
2024-04-01 00:00:00
transactionType
string
Optional
交易类型或POS类型
keyed
alertStatus
string
Optional
状态:
PENDING(待处理)
CREATED (已创建)
COMPLETED (已完成)
TIMEOUT (超时未完成)
(*20250805新增)
COMPLETED
timeOut
string
Optional
处理截止时间
2024-04-01 00:00:00
reasonCode
string
Optional
拒付原因码
10.4
Request Payload ( RDR)
Field Name
Field Type
Required
Description
Example
id
string
Required
贸御系统预警单唯一 id
902f4dc650ac4da48a138bfb2ec66703
alertId
string
Required
争议记录 id,Ethoca返回的唯一预警 id
5FWS6ZMJ72BF5C9LKBAHGAGJU
preAlertTypestring
Required
预警推送类型,固定值 RDR
RDR
alertTime
string
Required
预警创建时间,UTC标准时间:YYYY-MM-DD hh:mm:ss
2024-05-03 17:54:48
alertType
string
Required
争议类型: dispute or fraud
dispute
amount
string
Required
交易金额
5000
currency
string
Required
交易币种,ISO 4217三位大写字母代码
USD
descriptor
string
Required
VISA返回的descriptor
SP KIVAS
descriptorRegisterstring
Required
注册时填写的descriptor
SP KIVAS 123
cardBin
string
Required
收单银行 BIN
019248
caid
string
Required
CAID:银行商户号
342411
cardNumber
string
Optional
卡bin
01847291838
acquirerBin
string
Optional
收单银行 BIN
10384
acquirerReferenceNumber
string
Optional
收单银行参考号
01847291838
alertSource
string
Optional
预警来源
VISA
authCode
string
Optional
授权码
102030
chargebackCode
string
Optional
拒付原因代码
REFUND
descriptorContact
string
Optional
描述联系人
Even
disputeAmount
string
Optional
争议金额,可以与交易金额不同
500
disputeCurrency
string
Optional
争议币种,ISO 4217标准
USD
merchantCategoryCode
string
Optional
商户类别代码
Code
ruleName
string
Optional
规则名称
RULE_NAME
ruleType
string
Optional
规则类型
RULE_TYPE
transactionTime
string
Optional
交易的日期,交易所在地的时区时间
2024-05-03 17:54:48
alertStatus
string
Optional
状态:
PENDING(待处理)
CREATED (已创建)
COMPLETED (已完成)
TIMEOUT (超时未完成)
(*20250805新增)
PENDING
timeOut
string
Optional
处理截止时间
(*20250805新增)
2024-04-01 00:00:00
reasonCode
string
Optional
拒付原因码
(*20250805新增)
10.4
merchantOrderId
string
Optional
商户订单号
(*20250805新增)
VB2019032008321890000003
outcome
string
Optional
预警结果(*20250805新增)
ACCEPTED
Response Payload
Field Name
Field Type
Required
Description
Example
status
boolean
Required
表示是否正常接收预警
true
message
string
Optional
若无法消费预警,可返回错误信息
System Error
步骤4: ETHOCA预警反馈
- 调用方向:Merchant → Securego
- Path: /rest/third/predictor/merchant/outcome
Request Payload
Field Name
Field Type
Required
Description
Example
predictorId
string
Required
贸御系统预警单唯一 id
902f4dc650ac4da48a138bfb2ec66703
refunded
string
Required
必须填写以下枚举值:
refunded (已匹配到交易并退款)
ignore (已匹配到交易但不做处理)
notfound (未匹配到对应交易)
chargeback_beforealert(原交易预警前已拒付)
refunded_beforealert(原交易预警前已退款)
transaction_failed(原交易状态为失败)
duplicate_alert(重复预警)
refunded
comments
string
Conditional Required
仅在【refunded】字段为duplicate_alert时为必填,填写重复预警的原预警【alertId】
补充意见
isFraud
string
Optional
是否为欺诈
yes
matchOrderNo
string
Optional
匹配的流水订单号
102493717192
refundNo
string
Optional
退款单号
当 refunded = ‘refunded’时,必填
TY12345567
refundDate
string
Optional
退款日期
当 refunded = ‘refunded’时,必填
2024-04-23 23:06:53
refundAmount
string
Optional
退款金额
当 refunded = ‘refunded’时,必填
128.12
refundCurrency
string
Optional
退款币种
当 refunded = ‘refunded’时,必填
USD
Response Payload
Field Name
Field Type
Required
Example
Description
status
boolean
Required
true
当状态为 true表示系统正常接受,false表示接受数据异常(参数值校验失败等)
message
string
Optional
System Error
错误信息,当 status为 false时传送
data
object
Required
data.predictorId
string
Required
82n1xcjaffflxoxnm8119
拒先知预警唯一id
data.outcomeStatus
string
Required
处理欺诈结果状态 success成功处理,failed处理失败
data.errorCode
string
Optional
当预警处理失败时,返回预警失败状态码
data.errorDesc
string
Optional
错误描述
步骤5: 关闭商户注册申请
- 调用方向:Merchant → Securego
- Path: /rest/third/predictor/merchant/alert/close
Request Payload
Field Name
Field Type
Required
Description
Example
notifyUrl
string
Required
通知地址,处理结果通过该 URL 反馈,
请务必确保该 URL 可正常访问
https://mer.tradefensor.com/rest/alert/callback
alertType
string
Required
报备类型,可选值
- Ethoca
- RDR
Ethoca
descriptor
string
Required
字段含义:
Descriptor 是信用卡交易中客户账单上显示的描述信息,通常用于帮助客户识别这笔交易是从哪个商户发起的。
如何获取:
• 由支付服务商、PF 或商户在接入收单时设置。
• 在对账单上能看到这个字段(也叫 "statement descriptor")。
• 也可在清算报文或交易响应中看到。
QUICKBUY*BOOKSTORE
cardBin
string
Conditionally required
当 alertType 为 RDR时必填,为ethoca时可以不填
字段含义:
BIN 是银行卡前 6 或 8 位号码,用于识别收单机构
如何获取:
• 向你的收单银行、支付网关或 PF 申请。
• VISA PF 或收单方分配并备案在系统中。
• 有时一个收单方有多个 BIN(代表不同产品/服务线)。
430123(某银行的收单 BIN)
caid
string
Conditionally required
当 alertType 为 RDR时必填,为ethoca时可以不填
字段含义:
CAID 是 Card Acceptor ID,即“商户识别号”或“终端商户编号”,由收单银行或支付机构分配,用于在VISA网络中唯一标识一个商户实体。
如何获取:
• 由收单银行或第三方支付公司为每个商户分配。
• 可通过商户的收单协议、商户管理平台(如VISA Portal、CyberSource、Adyen、Worldpay等)查看。
• 在交易报文或清算报文中也会包含CAID字段
123456789012345(长度通常为15位)
Response Payload
Field Name
Field Type
Required
Description
Example
status
boolean
Required
表示系统是否正常接收请求
true
message
string
Optional
若无法报备,则返回错误
System Error
data
object
Optional
data.status
string
Required
-WAITING: 等待预警开通中
-EFFECTED:已生效
-CLOSING:关闭中
-CLOSED:已关闭
WAITING
- 如果您在API集成过程中有任何疑问,请通过以下方式联系我们
support@tradefensor.com