争议预警回调

文档目的

争议预警唯一匹配到客户订单，并且客户预警费成功记录后，TrustPay 向原订单的 notify_url 发送带签名的 JSON 回调。

争议预警属于正式争议前的风险提醒，不等同于正式争议，不会修改支付订单状态，也不表示已经完成退款或正式争议处理。

请求

请求方法： POST

Content-Type： application/json

请求地址： 原订单提交的 notify_url

通知类型： type = 7

投递语义

回调异步投递，采用至少一次语义。

TrustPay 仅将 HTTP 200 视为投递成功。

网络错误、超时和非 200 响应可能触发重试。

客户必须使用 alert_id 对重复回调做幂等处理。

完成验签并可靠接收事件后再返回 HTTP 200。

回调失败不会冲正已经成功记录的预警费。

机器字段兼容性

客户可见名称统一使用“争议预警”。当前实现仍保留以下历史 JSON 标识：

event_type = chargeback_alert.created

chargeback_alert_fee

接收方不得自行重命名。修改这些标识需要版本化 API 和代码变更。

字段

字段	类型	必填	说明
`type`	integer	是	固定为 `7`
`merchant_id`	integer	是	TrustPay 客户 ID
`order_no`	string	是	原客户订单号
`order_amount`	number	是	原订单金额
`paid_amount`	number	是	原实付金额
`reason`	string	是	服务商提供的原因码，可能为空
`event_type`	string	是	当前兼容值：`chargeback_alert.created`
`alert_id`	string	是	TrustPay 争议预警 ID 和客户侧幂等键
`provider_alert_id`	string	是	服务商提供的预警编号
`platform_order_no`	string	否	TrustPay 平台订单号
`warning_type`	string	是	`ethoca`、`rdr` 或 `cdrn`
`alert_type`	string	是	`fraud` 或 `dispute`
`match_method`	string	是	`arn` 或 `card_amount_time`
`currency`	string	是	原订单币种，大写 ISO 4217 代码
`chargeback_amount`	number	是	服务商争议金额；缺失或为零时回退为 `paid_amount`
`chargeback_currency`	string	是	服务商争议币种；缺失时回退为订单币种
`chargeback_alert_fee`	number	是	兼容字段，表示客户争议预警费
`masked_card_number`	string	否	脱敏卡号，不包含完整 PAN
`arn`	string	否	Acquirer Reference Number
`chargeback_reason_code`	string	否	服务商争议原因码
`source`	string	否	服务商事件来源
`alert_timestamp`	string	否	预警时间，UTC RFC 3339 格式
`transaction_timestamp`	string	否	原交易时间，UTC RFC 3339 格式
`received_at`	string	是	TrustPay 接收时间，UTC RFC 3339 格式
`sign`	string	是	MD5 小写十六进制签名

可选字段在无法取得值时可能省略。金额使用 JSON number，最多可能包含四位小数，不要假设固定尾零。

回调不会包含：

完整 PAN 或 CVV；

服务商账号凭据；

原始服务商负载；

渠道成本或平台利润；

内部错误或重试次数。

示例

{
  "type": 7,
  "merchant_id": 1001,
  "order_no": "ORDER_123456",
  "order_amount": 352.99,
  "paid_amount": 352.99,
  "reason": "10.4",
  "event_type": "chargeback_alert.created",
  "alert_id": "cba_example_001",
  "provider_alert_id": "2L07DBRFGBDLIW7SH59V969JG",
  "platform_order_no": "TP202607270001",
  "warning_type": "ethoca",
  "alert_type": "fraud",
  "match_method": "arn",
  "currency": "USD",
  "chargeback_amount": 352.99,
  "chargeback_currency": "USD",
  "chargeback_alert_fee": 4.5299,
  "masked_card_number": "800012******6824",
  "arn": "12345678901234567890123",
  "chargeback_reason_code": "10.4",
  "source": "ethoca",
  "alert_timestamp": "2026-07-27T12:00:00Z",
  "transaction_timestamp": "2026-07-26T12:00:00Z",
  "received_at": "2026-07-27T12:00:01Z",
  "sign": "SIGNATURE_VALUE"
}

验签

除 sign 外，实际回调中的所有非空字段都参与签名。

移除 sign。

移除值为空的字段。

按字段名进行字典序排序。

拼接为 key1=value1&key2=value2。

追加 &secret=YOUR_SECRET。

计算 MD5 小写十六进制值。

验签前不要对金额做舍入或重新格式化。参考代码请查看《签名计算》。

争议预警回调

文档目的

请求

投递语义

机器字段兼容性

字段

示例

验签

推荐处理流程

相关文档

争议预警回调

文档目的#

请求#

投递语义#

机器字段兼容性#

字段#

示例#

验签#

推荐处理流程#

相关文档#

文档目的

请求

投递语义

机器字段兼容性

字段

示例

验签

推荐处理流程

相关文档