跳转到主要内容
WEBHOOK
refundNotify
{
  "bizType": "PAY_REFUND",
  "bizId": "79553022813274112",
  "bizStatus": "REFUND_SUCCESS",
  "clientId": "smsWJbaQektcDhOw",
  "data": "{\"merchantTradeNo\":\"native5939082218\",\"productName\":\"goodsName\",\"tradeType\":\"APP\",\"goodsName\":\"goodsName\",\"terminalType\":\"APP\",\"currency\":\"USDT\",\"orderAmount\":\"0.01200000\",\"createTime\":1780017217454,\"transactionId\":\"79553022813274118\",\"refundInfo\":{\"refundRequestId\":\"6559049045\",\"prepayId\":\"79553022813274112\",\"orderAmount\":\"0.01200000\",\"refundAmount\":\"0.012\",\"refundPayCurrency\":\"USDT\",\"refundPayAmount\":\"0.012\"},\"channelId\":\"\"}"
}
{
  "returnCode": "SUCCESS",
  "returnMessage": ""
}

Documentation Index

Fetch the complete documentation index at: https://docs.gate.com/llms.txt

Use this file to discover all available pages before exploring further.

​
概述

本页说明 webhook refundNotify。完整的参数、响应结构与示例由上方关联的 OpenAPI 或 webhook 定义渲染。 退款单状态变更时，GatePay 向商户配置的 callback URL 发送异步通知（bizType 为 PAY_REFUND）。

​
说明

  • 建议基于 refundInfo.refundRequestId 或 bizId 做幂等处理。
  • 验签、重试、data 解析与成功应答见 通知概览；签名规则见 安全与签名。

​
触发情形

  • 退款单状态发生改变时（退款成功、处理中或被拒绝等），GatePay 向商户注册时配置的 callback URL 发送通知
  • 若通知投递失败，重试规则见 通知概览。
适用范围：退款单状态变更（bizType 为 PAY_REFUND）。退款查询与对账时，请优先使用商户侧唯一标识 refundRequestId。

​
查单兜底

  1. 调用退款接口创建退款单后，接口成功仅表示受理，不代表最终退款结果。
  2. 优先等待本页 PAY_REFUND 回调；若 10 秒内未收到状态通知，请调用 查询退款详情（GET /v2/pay/refund/details），以 refundRequestId 为准。

​
消息结构

字段名类型说明
bizTypestring固定为 PAY_REFUND
bizIdstring退款单 ID
bizStatusstring退款单状态，见下表
client_id / clientIdstring商户 client_id（顶层字段名可能为 client_id 或 clientId）
datastring业务数据 JSON 字符串

​
消息结构示例

{
  "bizType": "PAY_REFUND",
  "bizId": "79553022813274112",
  "bizStatus": "REFUND_SUCCESS",
  "clientId": "smsWJbaQektcDhOw",
  "data": "{\"merchantTradeNo\":\"native5939082218\",\"productName\":\"goodsName\",\"tradeType\":\"APP\",\"goodsName\":\"goodsName\",\"terminalType\":\"APP\",\"currency\":\"USDT\",\"orderAmount\":\"0.01200000\",\"createTime\":1780017217454,\"transactionId\":\"79553022813274118\",\"refundInfo\":{\"refundRequestId\":\"6559049045\",\"prepayId\":\"79553022813274112\",\"orderAmount\":\"0.01200000\",\"refundAmount\":\"0.012\",\"refundPayCurrency\":\"USDT\",\"refundPayAmount\":\"0.012\"},\"channelId\":\"\"}"
}

​
bizStatus 枚举值

值说明
REFUND_SUCCESS退款成功
REFUND_PROCESS退款处理中
REFUND_REJECTED退款被拒绝

​
data 字段说明

字段名类型说明
merchantTradeNostring商户交易号
productTypestring创建订单时的 goodsType
productNamestring创建订单时的 goodsName
tradeTypestring创建订单时的 terminalType
goodsNamestring商品名称
terminalTypestring终端类型
currencystring订单币种
orderAmountstring订单金额
createTimeint64订单创建时间（毫秒）
transactionIdstring平台交易 ID
channelIdstring客户名称 / 渠道标识
refundInfoobject退款详情

​
refundInfo 字段

字段名类型说明
refundRequestIdstring商户退款 ID，由商户生成且小于 32 字节
prepayIdstring拟退款的订单 ID
orderAmountstring订单金额
refundAmountstring退款金额
refundPayCurrencystring退款支付币种
refundPayAmountstring退款支付金额

​
回调示例

​
退款成功（bizStatus=REFUND_SUCCESS）

{
  "bizType": "PAY_REFUND",
  "bizId": "79553022813274112",
  "bizStatus": "REFUND_SUCCESS",
  "clientId": "smsWJbaQektcDhOw",
  "data": "{\"merchantTradeNo\":\"native5939082218\",\"productName\":\"goodsName\",\"tradeType\":\"APP\",\"goodsName\":\"goodsName\",\"terminalType\":\"APP\",\"currency\":\"USDT\",\"orderAmount\":\"0.01200000\",\"createTime\":1780017217454,\"transactionId\":\"79553022813274118\",\"refundInfo\":{\"refundRequestId\":\"6559049045\",\"prepayId\":\"79553022813274112\",\"orderAmount\":\"0.01200000\",\"refundAmount\":\"0.012\",\"refundPayCurrency\":\"USDT\",\"refundPayAmount\":\"0.012\"},\"channelId\":\"\"}"
}

​
退款处理中（bizStatus=REFUND_PROCESS）

{
  "bizType": "PAY_REFUND",
  "bizId": "79553022813274112",
  "bizStatus": "REFUND_PROCESS",
  "clientId": "smsWJbaQektcDhOw",
  "data": "{\"merchantTradeNo\":\"native5939082218\",\"currency\":\"USDT\",\"orderAmount\":\"0.01200000\",\"refundInfo\":{\"refundRequestId\":\"6559049045\",\"prepayId\":\"79553022813274112\",\"orderAmount\":\"0.01200000\",\"refundAmount\":\"0.012\",\"refundPayCurrency\":\"USDT\",\"refundPayAmount\":\"0.012\"}}"
}

​
退款被拒绝（bizStatus=REFUND_REJECTED）

{
  "bizType": "PAY_REFUND",
  "bizId": "79553022813274112",
  "bizStatus": "REFUND_REJECTED",
  "clientId": "smsWJbaQektcDhOw",
  "data": "{\"merchantTradeNo\":\"native5939082218\",\"currency\":\"USDT\",\"orderAmount\":\"0.01200000\",\"refundInfo\":{\"refundRequestId\":\"6559049045\",\"prepayId\":\"79553022813274112\",\"orderAmount\":\"0.01200000\",\"refundAmount\":\"0.012\",\"refundPayCurrency\":\"USDT\",\"refundPayAmount\":\"0.012\"}}"
}

请求体

application/json
​
bizType
enum<string>
必填

业务类型，固定为 PAY_REFUND。

可用选项:
PAY_REFUND
​
bizId
string
必填

退款单 ID。

​
bizStatus
enum<string>
必填

退款单状态，见枚举值。

可用选项:
REFUND_SUCCESS,
REFUND_PROCESS,
REFUND_REJECTED
​
data
string
必填

业务数据 JSON 字符串，解析后结构见 refundData。

​
client_id
string

创建订单的商户 client_id。

​
refundData
object

data 解析后的退款通知明细。

​
description
any

响应

200 - application/json

返回 HTTP 200 表示商户已成功接收通知。

商户接收通知后的响应体。

​
returnCode
string
必填

返回状态码，SUCCESS 表示成功。

​
returnMessage
string | null

返回说明，成功时可为空。