支付回调说明

回调请求

请求方式

Method: POST

Content-Type: application/json

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

请求头

Content-Type: application/json

请求体格式

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

回调数据结构

字段说明

通用字段

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

金额字段

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

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

退款字段

字段名	类型	必填	说明
`merchant_refund_no`	string[]	否	此 payin 订单关联的全部商户退款单号，来源于 refunds 表

状态值说明

详情请看: 枚举类型说明

金额字段响应规则

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

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

✅ order_amount: 订单金额

❌ 其他金额字段不包含

2. 代收退款中状态 (type = 0, status = 9)

✅ order_amount: 订单金额

✅ merchant_refund_no: 商户退款单号数组

❌ paid_amount、balance_amount、fee、pay_time 不包含

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

✅ order_amount: 订单金额

✅ refund_amount: 退款金额

✅ merchant_refund_no: 商户退款单号数组

❌ paid_amount、balance_amount、fee、pay_time 不包含

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

✅ order_amount: 订单金额

✅ paid_amount: 实际支付金额

✅ balance_amount: 结算金额 = paid_amount - fee

✅ fee: 手续费

✅ pay_time: 支付时间

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

✅ order_amount: 订单金额

✅ paid_amount: 实际支付金额

✅ balance_amount: 结算金额 = paid_amount + fee

✅ fee: 手续费

✅ pay_time: 支付时间

签名规则

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

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

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

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

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

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

数组字段（如 merchant_refund_no）按 JSON 字符串参与签名，例如 ["refund_1","refund_2"]。

签名计算步骤示例

假设有以下回调数据：

{
  "type": 0,
  "merchant_id": 1001,
  "order_no": "ORDER_123456",
  "order_amount": 100.50,
  "paid_amount": 100.50,
  "balance_amount": 98.50,
  "fee": 2.00,
  "status": 5,
  "reason": "Payment successful"
}

Secret Key: test_secret_key_12345_abcdefghijklmnop

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

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

步骤 3: 按键名排序

balance_amount=98.5
fee=2
merchant_id=1001
order_amount=100.5
order_no=ORDER_123456
paid_amount=100.5
reason=Payment successful
status=5
type=0

步骤 4: 构建查询字符串

balance_amount=98.5&fee=2&merchant_id=1001&order_amount=100.5&order_no=ORDER_123456&paid_amount=100.5&reason=Payment successful&status=5&type=0

步骤 5: 添加密钥

balance_amount=98.5&fee=2&merchant_id=1001&order_amount=100.5&order_no=ORDER_123456&paid_amount=100.5&reason=Payment successful&status=5&type=0&secret=test_secret_key_12345_abcdefghijklmnop

步骤 6: 计算 MD5

MD5("balance_amount=98.5&fee=2&merchant_id=1001&order_amount=100.5&order_no=ORDER_123456&paid_amount=100.5&reason=Payment successful&status=5&type=0&secret=test_secret_key_12345_abcdefghijklmnop")
= "29fa2ad03349c534baafd36094e23c7f"

签名计算示例代码

Go 语言

FAQ

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

支付回调说明

回调请求#

请求方式#

请求头#

请求体格式#

回调数据结构#

字段说明#

通用字段#

金额字段#

退款字段#

状态值说明#

金额字段响应规则#

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

2. 代收退款中状态 (type = 0, status = 9)#

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

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

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

签名规则#

签名计算步骤示例#

签名计算示例代码#

Go 语言#

FAQ#

回调请求

请求方式

请求头

请求体格式

回调数据结构

字段说明

通用字段

金额字段

退款字段

状态值说明

金额字段响应规则

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

2. 代收退款中状态 (type = 0, status = 9)

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

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

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

签名规则

签名计算步骤示例

签名计算示例代码

Go 语言

FAQ