退款状态通知

{
  "bizType": "PAY_REFUND",
  "bizId": "79553022813274112",
  "bizStatus": "REFUND_SUCCESS",
  "clientId": "smsWJbaQektcDhOw",
  "data": "{\"accountId\":10002,\"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": ""
}

WEBHOOK

refundNotify

{
  "bizType": "PAY_REFUND",
  "bizId": "79553022813274112",
  "bizStatus": "REFUND_SUCCESS",
  "clientId": "smsWJbaQektcDhOw",
  "data": "{\"accountId\":10002,\"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": ""
}

概述

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

说明

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

触发情形

退款单状态发生改变时（退款成功、处理中或被拒绝等），GatePay 向商户注册时配置的 callback URL 发送通知
若通知投递失败，重试规则见通知概览。

适用范围：退款单状态变更（bizType 为 PAY_REFUND）。退款查询与对账时，请优先使用商户侧唯一标识 refundRequestId。

查单兜底

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

消息结构

字段名	类型	说明
`bizType`	string	固定为 `PAY_REFUND`
`bizId`	string	退款单 ID
`bizStatus`	string	退款单状态，见下表
`client_id` / `clientId`	string	商户 `client_id`（顶层字段名可能为 `client_id` 或 `clientId`）
`data`	string	业务数据 JSON 字符串

消息结构示例

{
  "bizType": "PAY_REFUND",
  "bizId": "79553022813274112",
  "bizStatus": "REFUND_SUCCESS",
  "clientId": "smsWJbaQektcDhOw",
  "data": "{\"accountId\":10002,\"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 字段说明

字段名	类型	说明
`merchantTradeNo`	string	商户交易号
`productType`	string	创建订单时的 `goodsType`
`productName`	string	创建订单时的 `goodsName`
`tradeType`	string	创建订单时的 `terminalType`
`goodsName`	string	商品名称
`terminalType`	string	终端类型
`currency`	string	订单币种
`orderAmount`	string	订单金额
`createTime`	int64	订单创建时间（毫秒）
`transactionId`	string	平台交易 ID
`channelId`	string	客户名称 / 渠道标识
`accountId`	int64	订单所属的账户ID（商户或机构发起返回其账户ID，机构代子账户发起则返回子账户ID）
`refundInfo`	object	退款详情

refundInfo 字段

字段名	类型	说明
`refundRequestId`	string	商户退款 ID，由商户生成且小于 32 字节
`prepayId`	string	拟退款的订单 ID
`orderAmount`	string	订单金额
`refundAmount`	string	退款金额
`refundPayCurrency`	string	退款支付币种
`refundPayAmount`	string	退款支付金额

回调示例

退款成功（`bizStatus=REFUND_SUCCESS`）

{
  "bizType": "PAY_REFUND",
  "bizId": "79553022813274112",
  "bizStatus": "REFUND_SUCCESS",
  "clientId": "smsWJbaQektcDhOw",
  "data": "{\"accountId\":10002,\"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": "{\"accountId\":10002,\"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": "{\"accountId\":10002,\"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 解析后的退款通知明细。

Show child attributes

description

any

响应

200 - application/json

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

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

returnCode

string

必填

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

returnMessage

string | null

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

礼品卡支付状态通知

异常支付通知

⌘I

公共

余额

机构

支付

OTC

闪兑

出金

礼品卡

订阅

对账

通知

概述

说明

触发情形

查单兜底

消息结构

消息结构示例

bizStatus 枚举值

data 字段说明

refundInfo 字段

回调示例

退款成功（`bizStatus=REFUND_SUCCESS`）

退款处理中（`bizStatus=REFUND_PROCESS`）

退款被拒绝（`bizStatus=REFUND_REJECTED`）

请求体

响应

​概述

​说明

​触发情形

​查单兜底

​消息结构

​消息结构示例

​bizStatus 枚举值

​data 字段说明

​refundInfo 字段

​回调示例

​退款成功（bizStatus=REFUND_SUCCESS）

​退款处理中（bizStatus=REFUND_PROCESS）

​退款被拒绝（bizStatus=REFUND_REJECTED）

请求体

响应

概述

说明

触发情形

查单兜底

消息结构

消息结构示例

bizStatus 枚举值

data 字段说明

refundInfo 字段

回调示例

退款成功（`bizStatus=REFUND_SUCCESS`）

退款处理中（`bizStatus=REFUND_PROCESS`）

退款被拒绝（`bizStatus=REFUND_REJECTED`）