1.
TrustPay 会向商户提交订单时设置的 notify_url 发送带签名的 JSON 回调；
2.
正式争议和争议预警回调请分别查看 争议管理 / 正式争议回调 与 争议管理 / 争议预警回调；
Content-Type： application/json
成功响应#
商户端应返回 HTTP 200。非 200（含 400/500）、超时均视为失败并重试。| 项 | 规则 |
|---|
| 成功 | 仅 HTTP 200 |
| 最大发送次数 | 3 次（首次 + 最多 2 次重试） |
| 间隔 | 指数退避，约 60s → 120s（上限 1h） |
支付通知类型总览#
| type | 含义 | 判定主字段 |
|---|
0 | 代收 Payin | 数字 status |
1 | 代付 Payout | 数字 status |
2 | 退款 Refund | 数字 refund_status |
通用字段#
| 字段 | 类型 | 必填 | 说明 |
|---|
type | integer | 是 | 0 = 代收，1 = 代付， 2 = 退款 |
merchant_id | integer | 是 | TrustPay 商户 ID |
order_no | string | 是 | 商户订单号 |
order_amount | number | 是 | 订单金额 |
status | integer | 仅支付回调 | 订单状态，请查看 枚举类型说明 |
reason | string | 是 | 结果或失败原因，可能为空 |
sign | string | 是 | MD5 小写十六进制签名 |
金额字段#
| 字段名 | 类型 | 必填 | 说明 |
|---|
order_amount | number | 是 | 订单金额 |
paid_amount | number | 否 | 实际支付金额 |
balance_amount | number | 否 | 结算/余额变动口径（见各 type） |
refund_amount | number | 否 | 退款金额（见 §6） |
fee | number | 否 | 手续费 |
退款字段#
| 字段名 | 类型 | 必填 | 说明 |
|---|
merchant_refund_no | string | 否 | 本次退款的商户退款单号（仅当前这一笔） |
refund_status | int64 | 否 | 1 处理中 / 2 成功 / 3 失败 / 4 回滚 / 5 账务冲突。退款结果以此判定 |
金额使用 JSON number，序列化结果可能省略尾零。验签时必 须使用从回调请求体解析出的值，不要先对金额做舍入或重新格式化。回调类型示例#
1. 代收 Payin ( type = 0 )#
字段规则#
| 场景 | status | paid_amount | balance_amount | fee | pay_time |
|---|
| 失败/超时 | 3/4 | 省略 | 省略 | 省略 | 省略 |
| 成功（未退款） | 如 5/6 | 有值 | paid_amount - fee | 有值 | 有值（未结算且无 pay_time 时可能用当前 UTC） |
示例（代收未结算）#
{
"type": 0,
"merchant_id": 8820250900009,
"order_no": "MCH-PAYIN-20260513-001",
"order_amount": 500.00,
"paid_amount": 500.00,
"balance_amount": 492.50,
"fee": 7.50,
"status": 5,
"reason": "payment received",
"pay_time": "2026-05-13T08:30:00Z",
"sign": "..."
}
2. 代付 Payout ( type = 1 )#
字段规则#
| 场景 | paid_amount | balance_amount |
|---|
| 失败/超时 | 省略 | 省略 |
| 其他 | order.paid_amount | paid_amount + fee（代付口径） |
{
"type": 1,
"merchant_id": 8820250900009,
"order_no": "MCH-PAYOUT-20260513-001",
"order_amount": 1000.00,
"paid_amount": 1000.00,
"balance_amount": 1003.00,
"fee": 3.00,
"status": 2,
"reason": "payout success",
"pay_time": "2026-05-13T09:00:00Z",
"sign": "..."
}
3. 退款refund ( type = 2 )#
字段规则#
| 字段 | 规则 |
|---|
type | 固定 2 |
order_no | 原支付商户订单号（不新增 payment_order_no） |
merchant_refund_no | 本次商户退款单号（正常路径应有；找不到对应退款记录时可能省略） |
refund_status | 判定退款结果：见下表 |
refund_amount | 处理中/失败：当前这一笔金额；成功（自动路径）：多为原支付单累计已退金额 |
status | 订单侧展示：处理中 9；全额成功 7；部分成功 8；失败 = 恢复后的原支付状态（如 5/6/17），不固定为 3 |
paid_amount / balance_amount / fee / pay_time | 均省略 |
枚举值说明#
refund_status | 含义 |
|---|
1 | 处理中 processing |
2 | 成功 success |
3 | 失败 failed |
4 | 回滚 rollback |
5 | 账务冲突 accounting_conflict |
{
"type": 2,
"merchant_id": 10001,
"order_no": "TPC_PAY_202508130001",
"order_amount": 20.00,
"refund_amount": 20.00,
"merchant_refund_no": "TPC_REFUND_202508130001",
"refund_status": 1,
"status": 9,
"reason": "refund processing",
"sign": "..."
}
{
"type": 2,
"merchant_id": 8820250900009,
"order_no": "TPC_PAY_202508130001",
"order_amount": 20.00,
"refund_amount": 20.00,
"merchant_refund_no": "TPC_REFUND_202508130001",
"refund_status": 2,
"status": 7,
"reason": "refund completed",
"sign": "..."
}
{
"type": 2,
"merchant_id": 8820250900009,
"order_no": "TPC_PAY_202508130001",
"order_amount": 100.00,
"refund_amount": 30.00,
"merchant_refund_no": "TPC_REFUND_202508130002",
"refund_status": 2,
"status": 8,
"reason": "refund completed",
"sign": "..."
}
{
"type": 2,
"merchant_id": 8820250900009,
"order_no": "TPC_PAY_202508130001",
"order_amount": 20.00,
"refund_amount": 20.00,
"merchant_refund_no": "TPC_REFUND_202508130001",
"refund_status": 3,
"status": 5,
"reason": "channel rejected refund",
"sign": "..."
}
推荐判定（保守策略）#
if type == 2:
refund_status=1 → 保持处理中
refund_status=2 且 merchant_refund_no、金额与本笔匹配 → 成功
refund_status=3 → 失败
仅有 status∈{5,6,17} 且无 refund_status=3 → 不自动失败
创建接口返回 7/8 → 不单独认定成功，等 webhook / 查单交叉确认
sign。实际负载中的所有非空字段都参与签名。待签名字符串、示例以及 JavaScript、Go 参考实现请查看 签名计算。安全检查清单#
为审计安全保存原始回调请求体；涉及卡信息时必须脱敏。
Modified at 2026-08-29 06:36:58
