> ## 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. # 退款状态通知 > 退款单状态变更时，GatePay 发送 `bizType` 为 `PAY_REFUND` 的 webhook 通知。 商户须校验签名，处理成功后返回 `{"returnCode":"SUCCESS","returnMessage":""}`。通知失败时按 [通知概览](/api-reference/version/100/cn/common/asyncNotification) 中的间隔重试。 ## 概述 本页说明 `webhook refundNotify`。完整的参数、响应结构与示例由上方关联的 OpenAPI 或 webhook 定义渲染。 退款单状态变更时，GatePay 向商户配置的 callback URL 发送异步通知（`bizType` 为 `PAY_REFUND`）。 ## 说明 * 建议基于 `refundInfo.refundRequestId` 或 `bizId` 做幂等处理。 * 验签、重试、`data` 解析与成功应答见 [通知概览](/api-reference/version/100/cn/common/asyncNotification)；签名规则见 [安全与签名](/api-reference/version/100/cn/common/securityAndSignature)。 ## 触发情形 * 退款单状态发生改变时（退款成功、处理中或被拒绝等），GatePay 向商户注册时配置的 **callback URL** 发送通知 * 若通知投递失败，重试规则见 [通知概览](/api-reference/version/100/cn/common/asyncNotification)。 **适用范围**：退款单状态变更（`bizType` 为 `PAY_REFUND`）。退款查询与对账时，请优先使用商户侧唯一标识 `refundRequestId`。 ## 查单兜底 1. 调用退款接口创建退款单后，接口成功仅表示受理，不代表最终退款结果。 2. 优先等待本页 `PAY_REFUND` 回调；若 **10 秒内**未收到状态通知，请调用 [查询退款详情](/api-reference/version/100/cn/endpoint/checkout/refundDetails)（`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 字符串 | ### 消息结构示例 ```json theme={null} { "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`） ```json theme={null} { "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`） ```json theme={null} { "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`） ```json theme={null} { "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\"}}" } ``` ## OpenAPI ````yaml api-reference/version/100/cn/openapi/refund-callback-openapi.json webhook refundNotify openapi: 3.1.0 info: title: GatePay 退款回调 API version: 1.0.0 description: 退款单状态异步通知。当退款单状态发生变化时，GatePay 向商户注册的 callback URL 发送通知；`data` 为 JSON 字符串。 servers: - url: https://openplatform.gateapi.io description: 生产环境 security: [] paths: {} ````