Chargeback 回调

文档目的

正式争议进入以下客户资金状态时，TrustPay 向原支付订单的 notify_url 发送带签名的 JSON 回调：

案件已创建并暂扣资金；

客户败诉；

客户胜诉。

正式争议回调与 type = 7 争议预警回调相互独立。

请求

请求方法： POST

Content-Type： application/json

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

通知类型： type = 4

投递与幂等

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

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

更新业务状态前必须验证签名。

可靠接收事件后再返回 HTTP 200。

使用 dispute_id 与 dispute_status 组合对重复事件做幂等处理。

字段

字段	类型	必填	说明
`type`	integer	是	固定为 `4`
`merchant_id`	integer	是	TrustPay 客户 ID
`order_no`	string	是	原客户订单号
`order_amount`	number	是	正式争议本金
`balance_amount`	number	是	本次生命周期事件对应的客户余额变动
`reason`	string	是	TrustPay 生命周期说明
`dispute_status`	string	是	`chargeback_pending`、`chargeback_lost` 或 `chargeback_won`
`dispute_id`	string	否	有值时为 TrustPay 正式争议 ID
`response_status`	string	否	当前客户响应状态
`dispute_fee`	number	是	本次事件收取的处理费；败诉/胜诉确认时为零
`expiration_date`	string	否	响应截止日期，格式为 `YYYY-MM-DD`
`sign`	string	是	MD5 小写十六进制签名

正式争议回调不包含仅用于支付或退款的 status、paid_amount、refund_amount、merchant_refund_no、fee 和 pay_time。

资金语义

`dispute_status`	`balance_amount`	`dispute_fee`	含义
`chargeback_pending`	负数	配置的处理费	案件创建时暂扣本金并收取处理费
`chargeback_lost`	`0`	`0`	创建阶段已完成暂扣，败诉确认时不重复扣款
`chargeback_won`	正数本金	`0`	返还此前暂扣的本金，处理费不返还

待裁决示例

{
  "type": 4,
  "merchant_id": 1001,
  "order_no": "ORDER_123456",
  "order_amount": 100,
  "balance_amount": -115,
  "reason": "Chargeback opened: funds held pending dispute decision",
  "dispute_status": "chargeback_pending",
  "dispute_id": "dsp_example_001",
  "response_status": "needs_response",
  "dispute_fee": 15,
  "expiration_date": "2026-08-15",
  "sign": "SIGNATURE_VALUE"
}

败诉示例

{
  "type": 4,
  "merchant_id": 1001,
  "order_no": "ORDER_123456",
  "order_amount": 100,
  "balance_amount": 0,
  "reason": "Chargeback lost: dispute refund confirmed",
  "dispute_status": "chargeback_lost",
  "dispute_id": "dsp_example_001",
  "response_status": "no_response_allowed",
  "dispute_fee": 0,
  "sign": "SIGNATURE_VALUE"
}

胜诉示例

{
  "type": 4,
  "merchant_id": 1001,
  "order_no": "ORDER_123456",
  "order_amount": 100,
  "balance_amount": 100,
  "reason": "Chargeback won: held funds released",
  "dispute_status": "chargeback_won",
  "dispute_id": "dsp_example_001",
  "response_status": "responded",
  "dispute_fee": 0,
  "sign": "SIGNATURE_VALUE"
}

chargeback_* 和当前英文 reason 文本是现有机器契约值，客户可见文档统一称为正式争议。

验签

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

移除 sign。

移除空值字段。

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

拼接为 key1=value1&key2=value2。

追加 &secret=YOUR_SECRET。

计算 MD5 小写十六进制值。

验签前不要对金额做舍入或重新格式化。

Chargeback 回调

文档目的

请求

投递与幂等

字段

资金语义

待裁决示例

败诉示例

胜诉示例

验签

推荐处理流程

相关文档

Chargeback 回调

文档目的#

请求#

投递与幂等#

字段#

资金语义#

待裁决示例#

败诉示例#

胜诉示例#

验签#

推荐处理流程#

相关文档#

文档目的

请求

投递与幂等

字段

资金语义

待裁决示例

败诉示例

胜诉示例

验签

推荐处理流程

相关文档