回调通知商户

支付回调

请求方式：POST

请求头

字段名	类型	必传	描述
content-type	string	是	application/json
x-api-key	string	是	Paydify提供，跟appId相同
x-api-timestamp	string	是	时间戳，单位毫秒
x-api-signature	string	是	签名，具体参看签名算法

请求体

字段名	类型	描述
appId	string	Paydify提供
txnId	string	Paydify支付订单号
mchTxnId	string	商户侧订单号
state	string	支付状态，枚举值参看支付状态
txnHash	string	链上交易Hash
txnAmount	string	订单金额，假如币种currency是USDT，则1.23表示1.23USDT
orderCurrency	string	订单币种
paidAmount	string	实际支付金额，假如币种currency是USDT，则1.23表示1.23USDT
mchReceivedAmount	string	商户应收金额，假如币种currency是USDT，则1.23表示1.23USDT
mchFee	string	Paydify收取的手续费，假如币种currency是USDT，则0.23表示0.23USDT
currency	string	支付币种
settlementCurrency	string	商户结算币种。加密结算为 USDT/USDC，法币结算为 USD
notifyType	string	通知类型，固定值：payment
fromAddress	string	付款地址
paidTime	int	支付成功时间戳，单位毫秒，只有支付成功才有值
failedTime	int	支付失败时间戳，单位毫秒，只有支付失败/超时才有值

响应

商户收到回调后应返回 HTTP 200。Paydify 根据响应体判断回调是否成功：

响应值	描述
success	回调确认成功，不再重试
fail	回调显式失败，按重试策略重试

推荐写法：

• Content-Type 建议 text/plain
• 响应体为裸字符串 success 或 fail，不区分大小写

兼容写法（以下同样会被识别为成功，不再重试）：

• 首尾空白或换行： success 、success\n
• JSON 字符串字面量："success"

以下写法仍会被判定为失败并触发重试：

• JSON 对象：{"status":"success"} / {"code":0} / {"result":"success"}
• HTML 错误页或空响应体
• 除 success 外的其他内容（含 fail）

任何无法识别为 success 的响应都会触发后续重试，最多 7 次。

请求示例

curl -X POST '{endpoint}' \
  -H 'content-type: application/json' \
  -H 'x-api-key: xxx' \
  -H 'x-api-timestamp: 121212121' \
  -H 'x-api-signature: xxxx' \
  -d '{
    "appId": "Axxxxxxxx",
    "txnId": "P4687529510003120897",
    "mchTxnId": "DCS20250905175704ICVAa11111211",
    "currency": "USDC",
    "state": "PAID",
    "txnHash": "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef",
    "fromAddress": "0x1111111111222222222233333333334444444444",
    "notifyType": "payment",
    "paidAmount": "0.22",
    "mchReceivedAmount": "0.22",
    "mchFee": "0",
    "txnAmount": "0.22",
    "paidTime": 1757328167000,
    "failedTime": 0
}'

---

退款回调

请求方式：POST

请求头

字段名	类型	必传	描述
content-type	string	是	application/json
x-api-key	string	是	Paydify提供，跟appId相同
x-api-timestamp	string	是	时间戳，单位毫秒
x-api-signature	string	是	签名，具体参看签名算法

请求体

字段名	类型	描述
appId	string	Paydify提供的应用ID
txnId	string	Paydify退款订单号
mchTxnId	string	商户退款订单号
currency	string	退款币种（如 USDT、USDC）
state	string	退款状态，枚举值参看退款状态。终态：REFUNDED（成功）/ FAILED（失败）
txnHash	string	链上交易Hash
notifyType	string	通知类型，固定值：refund
txnAmount	string	退款金额，假如币种currency是USDT，则"1.23"表示1.23USDT
failedTime	int	退款失败时间戳，单位毫秒，仅退款失败时有值
refundedTime	int	退款成功时间戳，单位毫秒，仅退款成功时有值
orderCurrency	string	原始订单币种（如 USD、EUR），仅法币支付场景存在
settlementCurrency	string	结算币种（如 USD），仅法币支付场景存在
orderAmount	string	原始法币订单金额，仅法币支付场景存在
settlementAmount	string	结算金额（负值表示退款），仅法币支付场景存在

响应

商户收到回调后应返回 HTTP 200。Paydify 根据响应体判断回调是否成功：

响应值	描述
success	回调确认成功，不再重试
fail	回调显式失败，按重试策略重试

推荐写法：

• Content-Type 建议 text/plain
• 响应体为裸字符串 success 或 fail，不区分大小写

兼容写法（以下同样会被识别为成功，不再重试）：

• 首尾空白或换行： success 、success\n
• JSON 字符串字面量："success"

以下写法仍会被判定为失败并触发重试：

• JSON 对象：{"status":"success"} / {"code":0} / {"result":"success"}
• HTML 错误页或空响应体
• 除 success 外的其他内容（含 fail）

任何无法识别为 success 的响应都会触发后续重试，最多 7 次。

请求示例

curl -X POST '{endpoint}' \
  -H 'content-type: application/json' \
  -H 'x-api-key: xxx' \
  -H 'x-api-timestamp: 121212121' \
  -H 'x-api-signature: xxxx' \
  -d '{
    "appId": "Axxxxxxxx",
    "txnId": "R4687326023007356672",
    "mchTxnId": "DCS20250905175704ICVAa1111",
    "currency": "USDC",
    "state": "REFUNDED",
    "txnHash": "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef",
    "notifyType": "refund",
    "txnAmount": "0.11",
    "failedTime": 0,
    "refundedTime": 1757315967000
}'

---

回调重试机制

回调如果拿不到预期的返回值 success，则会按照 1m / 5m / 30m / 2h / 6h / 12h / 24h 的间隔进行最多 7 次重试，超过仍未送达会进入告警：

请求序号	时间延迟	说明
0	0	第 1 次正常回调，立即执行，无延迟
1	1 分钟后	第 1 次重试
2	5 分钟后	第 2 次重试
3	30 分钟后	第 3 次重试
4	2 小时后	第 4 次重试
5	6 小时后	第 5 次重试
6	12 小时后	第 6 次重试
7	24 小时后	第 7 次重试