结果通知

创建收款订单、申请退款、申请出款时分别传入 callback_url。未填写或为空字符串时不通知；各类订单独立使用本次请求的地址。

触发事件

event	触发条件	data
PAYMENT.SUCCESS	收款成功	收款订单数据
REFUND.SUCCESS	退款成功	退款订单数据
REFUND.FAILED	退款失败	退款订单数据，包含失败原因
PAYOUT.SUCCESS	出款成功	出款订单数据
PAYOUT.FAILED	出款失败	出款订单数据，包含失败原因

请求

POST 至订单回调地址。地址须使用公网 HTTPS，证书有效；不跟随重定向。

请求头	说明
Content-Type	application/json; charset=utf-8
X-App-Id	商户 APPID，用于选择解密密钥

请求体仅包含加密信息：

{
  "algorithm": "AEAD_AES_256_GCM",
  "nonce": "Base64编码的12字节随机数",
  "ciphertext": "Base64编码的密文及认证标签"
}

解密

参数	规则
算法	AES-256-GCM
Key	当前商户密钥的 32 字节 UTF-8 值，不做 MD5、不做十六进制解码
Nonce	nonce 经标准 Base64 解码，长度 12 字节
AAD	固定字符串 TGPay-Merchant-Notify-v1 的 UTF-8 字节
Ciphertext / Tag	ciphertext 经标准 Base64 解码；最后 16 字节为认证标签，其余为密文

认证标签验证通过后，将明文按 UTF-8 JSON 解析。核对 data.app_id 与请求头一致，金额使用十进制字符串处理。

{
  "notification_id": "371000000000000001",
  "event": "REFUND.SUCCESS",
  "create_time": "2026-10-22T00:00:00Z",
  "data": {
    "callback_url": "https://merchant.example.com/notify/refund",
    "refund_id": "202610220000000043",
    "order_id": "202610220000000042",
    "app_id": "1234567890",
    "third_order_no": "ORDER202610220001",
    "third_refund_no": "REFUND202610220001",
    "currency": "USDT",
    "refund_amount": "3.33",
    "fee_refund_amount": "0.20",
    "merchant_debit_amount": "3.13",
    "status": "SUCCESS",
    "failure_reason": "",
    "create_time": "2026-10-22T00:00:00Z",
    "success_time": "2026-10-22T00:00:01Z",
    "update_time": "2026-10-22T00:00:01Z"
  }
}

notification_id 为通知唯一标识；create_time 为通知创建时间。data 字段与对应查询接口的 data 一致，为首次生成通知时的快照。

下载 Node.js 解密示例：

import { decryptNotification } from './notification.mjs'
const content = decryptNotification(requestBody, merchantSecret, appId)
// 以 content.notification_id 去重，完成持久化或事务提交后再确认接收。

接收确认

在 10 秒内返回 HTTP 200 和以下 JSON：

{"code":"SUCCESS"}

仅 HTTP 200 不代表成功；空响应、code=0、其他状态码、无效 JSON、超时或响应超过 4096 字节均视为失败。确认前须完成可靠接收；重复通知也应返回上述成功确认。

重试与幂等

• 首次立即通知，失败后间隔 60 秒重试，包含首次共 10 次，随后停止自动重试。
• 后台手动重试开启新一轮，仍最多 10 次；通知 ID 和业务内容不变。
• 每次通知使用新的随机数和当前商户密钥加密。密钥刷新后须同步更新接收端。
• 通知可能重复，请以 notification_id 建立唯一约束，防止重复记账。不得依赖通知到达顺序；需要最新状态时调用查询接口。