> ## 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.

# Refund Status Notification

> When a refund order status changes, GatePay sends a webhook with `bizType` `PAY_REFUND`.

Verify the signature and return `{"returnCode":"SUCCESS","returnMessage":""}` after successful processing. On delivery failure, GatePay retries at the intervals documented in [Notifications Overview](/api-reference/version/100/en/common/asyncNotification).

## Overview

This page documents `webhook refundWebhook`. The full schema, parameters, and examples are rendered from the linked OpenAPI or webhook definition above.

GatePay sends asynchronous notifications to the merchant callback URL when refund order status changes (`bizType` is `PAY_REFUND`).

## Notes

* Use `refundInfo.refundRequestId` or `bizId` for idempotency.
* Signature verification, retries, parsing `data`, and the success response are covered in [Notifications Overview](/api-reference/version/100/en/common/asyncNotification); see [Security and Signature](/api-reference/version/100/en/common/securityAndSignature) for signing rules.

## Trigger Scenarios

* When a refund order status changes (success, in progress, or rejected), GatePay sends a notification to the **callback URL** configured at merchant registration
* If delivery fails, see retry rules in [Notifications Overview](/api-reference/version/100/en/common/asyncNotification).

**Scope**: Refund order status changes (`bizType` is `PAY_REFUND`). For refund reconciliation, prefer the merchant-unique identifier `refundRequestId`.

## Query fallback

1. A successful refund API response only means acceptance, not the final refund outcome.
2. Wait for the `PAY_REFUND` callback first; if no status notification arrives within **10 seconds**, call [Query Refund Details](/api-reference/version/100/en/endpoint/checkout/refundDetails) (`GET /v2/pay/refund/details`) using `refundRequestId`.

## Message Structure

| Field                    | Type   | Description                                                             |
| ------------------------ | ------ | ----------------------------------------------------------------------- |
| `bizType`                | string | Always `PAY_REFUND`                                                     |
| `bizId`                  | string | Refund order ID                                                         |
| `bizStatus`              | string | Refund order status; see table below                                    |
| `client_id` / `clientId` | string | Merchant `client_id` (top-level field may be `client_id` or `clientId`) |
| `data`                   | string | Business payload as a JSON string                                       |

### Example Message

```json theme={null}
{
  "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 Enumeration

| Value             | Description        |
| ----------------- | ------------------ |
| `REFUND_SUCCESS`  | Refund succeeded   |
| `REFUND_PROCESS`  | Refund in progress |
| `REFUND_REJECTED` | Refund rejected    |

## data Field Reference

| Field             | Type   | Description                        |
| ----------------- | ------ | ---------------------------------- |
| `merchantTradeNo` | string | Merchant trade number              |
| `productType`     | string | `goodsType` at order creation      |
| `productName`     | string | `goodsName` at order creation      |
| `tradeType`       | string | `terminalType` at order creation   |
| `goodsName`       | string | Goods name                         |
| `terminalType`    | string | Terminal type                      |
| `currency`        | string | Order currency                     |
| `orderAmount`     | string | Order amount                       |
| `createTime`      | int64  | Order creation time (milliseconds) |
| `transactionId`   | string | Platform transaction ID            |
| `channelId`       | string | Customer name / channel identifier |
| `refundInfo`      | object | Refund details                     |

### refundInfo Fields

| Field               | Type   | Description                                                   |
| ------------------- | ------ | ------------------------------------------------------------- |
| `refundRequestId`   | string | Merchant refund ID; merchant-generated and less than 32 bytes |
| `prepayId`          | string | Original order ID to refund                                   |
| `orderAmount`       | string | Order amount                                                  |
| `refundAmount`      | string | Refund amount                                                 |
| `refundPayCurrency` | string | Refund payment currency                                       |
| `refundPayAmount`   | string | Refund payment amount                                         |

## Callback Example

### Refund succeeded (`bizStatus=REFUND_SUCCESS`)

```json theme={null}
{
  "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\":\"\"}"
}
```

### Refund in process (`bizStatus=REFUND_PROCESS`)

```json theme={null}
{
  "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\"}}"
}
```

### Refund rejected (`bizStatus=REFUND_REJECTED`)

```json theme={null}
{
  "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\"}}"
}
```


## OpenAPI

````yaml /api-reference/version/100/en/openapi/refund-callback-openapi.json webhook refundWebhook
openapi: 3.1.0
info:
  title: GatePay Refund Callback API
  version: 1.0.0
  description: >-
    Asynchronous notifications for refund order status changes. When a refund
    order status changes, GatePay sends a notification to the merchant callback
    URL; `data` is a JSON string.
servers:
  - url: https://openplatform.gateapi.io
    description: Production
security: []
paths: {}

````