回调请求

请求方式

Method: POST

Content-Type: application/json

URL: 商户在创建订单时配置的 notifyUrl

请求头

Content-Type: application/json

请求体格式

回调请求体为 JSON 格式，包含订单信息和签名字段。

回调数据结构

字段说明

通用字段

字段名	类型	必填	说明
`type`	int64	是	订单类型：0=代收(Payin), 1=代付(Payout)
`merchantId`	int64	是	商户ID
`orderNo`	string	是	商户订单号
`status`	int64	是	订单状态（见状态值说明）
`reason`	string	是	原因说明（英文）
`payTime`	string	否	支付时间
`sign`	string	是	签名（MD5，小写十六进制）

金额字段

所有金额字段均为数字类型（decimal.Decimal），在 JSON 序列化时输出为数字，保留两位小数。

字段名	类型	必填	说明
`orderAmount`	decimal.Decimal	是	订单金额
`paidAmount`	decimal.Decimal	否	实际支付金额
`balanceAmount`	decimal.Decimal	否	结算金额（商户实际到账金额）
`refundAmount`	decimal.Decimal	否	退款金额
`fee`	decimal.Decimal	否	手续费

状态值说明

详情请看: 枚举类型说明

金额字段响应规则

根据订单状态和支付类型，系统会在不同场景下响应不同的金额字段：

1. 失败/超时状态 (status = 3 或 4)

✅ orderAmount: 订单金额

❌ 其他金额字段不包含

2. 代收退款状态 (type = 0, status = 6 或 7)

✅ orderAmount: 订单金额

✅ refundAmount: 退款金额

❌ 其他金额字段不包含

3. 代收成功状态 (type = 0, status = 5)

✅ orderAmount: 订单金额

✅ paidAmount: 实际支付金额

✅ balanceAmount: 结算金额 = paidAmount - fee

✅ fee: 手续费

✅ payTime: 支付时间

4. 代付成功状态 (type = 1, status = 2)

✅ orderAmount: 订单金额

✅ paidAmount: 实际支付金额

✅ balanceAmount: 结算金额 = paidAmount + fee

✅ fee: 手续费

✅ payTime: 支付时间

签名规则

排除 sign 字段：计算签名时不包含 sign 字段本身

过滤空值：排除值为空（null、空字符串、0、false）的字段

按键名排序：将所有字段按键名进行字典序排序

构建查询字符串：格式为 key1=value1&key2=value2

添加密钥：在查询字符串后追加 &secret=YOUR_SECRET_KEY

计算 MD5：对完整字符串计算 MD5 哈希值，输出小写十六进制

签名计算步骤示例

假设有以下回调数据：

{
  "type": 0,
  "merchantId": 1001,
  "orderNo": "ORDER_123456",
  "orderAmount": 100.50,
  "paidAmount": 100.50,
  "balanceAmount": 98.50,
  "fee": 2.00,
  "status": 5,
  "reason": "Payment successful"
}

Secret Key: test_secret_key_12345_abcdefghijklmnop

步骤 1: 排除 sign 字段（本例中没有）

步骤 2: 过滤空值（本例中所有字段都有值）

步骤 3: 按键名排序

balanceAmount=98.5
fee=2
merchantId=1001
orderAmount=100.5
orderNo=ORDER_123456
paidAmount=100.5
reason=Payment successful
status=5
type=0

步骤 4: 构建查询字符串

balanceAmount=98.5&fee=2&merchantId=1001&orderAmount=100.5&orderNo=ORDER_123456&paidAmount=100.5&reason=Payment successful&status=5&type=0

步骤 5: 添加密钥

balanceAmount=98.5&fee=2&merchantId=1001&orderAmount=100.5&orderNo=ORDER_123456&paidAmount=100.5&reason=Payment successful&status=5&type=0&secret=test_secret_key_12345_abcdefghijklmnop

步骤 6: 计算 MD5

MD5("balanceAmount=98.5&fee=2&merchantId=1001&orderAmount=100.5&orderNo=ORDER_123456&paidAmount=100.5&reason=Payment successful&status=5&type=0&secret=test_secret_key_12345_abcdefghijklmnop")
= "987c6aa62092e2c6f5357da2da178d93"

签名计算示例代码

Go 语言

FAQ

当签名计算错误时,可以确认金额字段序列化是否省略了末尾的0

支付回调说明

回调请求#

请求方式#

请求头#

请求体格式#

回调数据结构#

字段说明#

通用字段#

金额字段#

状态值说明#

金额字段响应规则#

1. 失败/超时状态 (status = 3 或 4)#

2. 代收退款状态 (type = 0, status = 6 或 7)#

3. 代收成功状态 (type = 0, status = 5)#

4. 代付成功状态 (type = 1, status = 2)#

签名规则#

签名计算步骤示例#

签名计算示例代码#

Go 语言#

FAQ#

回调请求

请求方式

请求头

请求体格式

回调数据结构

字段说明

通用字段

金额字段

状态值说明

金额字段响应规则

1. 失败/超时状态 (status = 3 或 4)

2. 代收退款状态 (type = 0, status = 6 或 7)

3. 代收成功状态 (type = 0, status = 5)

4. 代付成功状态 (type = 1, status = 2)

签名规则

签名计算步骤示例

签名计算示例代码

Go 语言

FAQ