Skip to main content
WEBHOOK
refundWebhook
{
  "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\":\"\"}"
}
{
  "returnCode": "SUCCESS",
  "returnMessage": ""
}

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.

​
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

​
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

  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 (GET /v2/pay/refund/details) using refundRequestId.

​
Message Structure

FieldTypeDescription
bizTypestringAlways PAY_REFUND
bizIdstringRefund order ID
bizStatusstringRefund order status; see table below
client_id / clientIdstringMerchant client_id (top-level field may be client_id or clientId)
datastringBusiness payload as a JSON string

​
Example Message

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

ValueDescription
REFUND_SUCCESSRefund succeeded
REFUND_PROCESSRefund in progress
REFUND_REJECTEDRefund rejected

​
data Field Reference

FieldTypeDescription
merchantTradeNostringMerchant trade number
productTypestringgoodsType at order creation
productNamestringgoodsName at order creation
tradeTypestringterminalType at order creation
goodsNamestringGoods name
terminalTypestringTerminal type
currencystringOrder currency
orderAmountstringOrder amount
createTimeint64Order creation time (milliseconds)
transactionIdstringPlatform transaction ID
channelIdstringCustomer name / channel identifier
refundInfoobjectRefund details

​
refundInfo Fields

FieldTypeDescription
refundRequestIdstringMerchant refund ID; merchant-generated and less than 32 bytes
prepayIdstringOriginal order ID to refund
orderAmountstringOrder amount
refundAmountstringRefund amount
refundPayCurrencystringRefund payment currency
refundPayAmountstringRefund payment amount

​
Callback Example

​
Refund succeeded (bizStatus=REFUND_SUCCESS)

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

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

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

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.

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