> ## 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](/global/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](/global/api-reference/version/100/en/common/asyncNotification); see [Security and Signature](/global/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](/global/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](/global/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": "{\"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 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 |
| `accountId` | int64 | Account ID that owns the order. Returns the merchant or institution's own account ID when the merchant or institution initiates the order; returns the sub-account ID when the institution initiates on behalf of a sub-account. |
| `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": "{\"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\":\"\"}"
}
```

### Refund in process (`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\"}}"
}
```

### Refund rejected (`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 global/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: {}

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.