Refund Status Notification

{
  "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

refundWebhook

{
  "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": ""
}

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; see Security and Signature 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.

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

Query fallback

A successful refund API response only means acceptance, not the final refund outcome.
Wait for the PAY_REFUND callback first; if no status notification arrives within 10 seconds, call Query Refund Details (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

{
  "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`)

{
  "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`)

{
  "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`)

{
  "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\"}}"
}

Body

application/json

bizType

enum<string>

required

Business type; always PAY_REFUND.

Available options:

PAY_REFUND

bizId

string

required

Refund order ID.

bizStatus

enum<string>

required

Refund order status; see enum values.

Available options:

REFUND_SUCCESS,

REFUND_PROCESS,

REFUND_REJECTED

data

string

required

Business data as a JSON string; parsed structure see refundData.

client_id

string

Merchant client_id that created the order.

refundData

object

Parsed refund notification details from data.

Show child attributes

description

any

Response

200 - application/json

HTTP 200 indicates the merchant successfully received the notification.

Response body returned by the merchant after receiving the notification.

returnCode

string

required

Return status code; SUCCESS indicates success.

returnMessage

string | null

Return message; may be empty on success.

Gift Card Payment Status Notification

Unresolved Payment Notification

⌘I

Common

Balance

Institution

Payment

OTC

Convert

Payout

Gift Card

Subscription

Reconciliation

Notifications

Refund Status Notification

Overview

Notes

Trigger Scenarios

Query fallback

Message Structure

Example Message

bizStatus Enumeration

data Field Reference

refundInfo Fields

Callback Example

Refund succeeded (`bizStatus=REFUND_SUCCESS`)

Refund in process (`bizStatus=REFUND_PROCESS`)

Refund rejected (`bizStatus=REFUND_REJECTED`)

Body

Response

​Overview

​Notes

​Trigger Scenarios

​Query fallback

​Message Structure

​Example Message

​bizStatus Enumeration

​data Field Reference

​refundInfo Fields

​Callback Example

​Refund succeeded (bizStatus=REFUND_SUCCESS)

​Refund in process (bizStatus=REFUND_PROCESS)

​Refund rejected (bizStatus=REFUND_REJECTED)

Body

Response

Overview

Notes

Trigger Scenarios

Query fallback

Message Structure

Example Message

bizStatus Enumeration

data Field Reference

refundInfo Fields

Callback Example

Refund succeeded (`bizStatus=REFUND_SUCCESS`)

Refund in process (`bizStatus=REFUND_PROCESS`)

Refund rejected (`bizStatus=REFUND_REJECTED`)