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

# Gate 支付状态通知

> 适用于通过托管收银台、客户端拉起等方式下单，并由用户 Gate 支付账户完成付款的场景。`bizType` 固定为 `PAY`。

商户须校验签名，处理成功后返回 `{"returnCode":"SUCCESS","returnMessage":""}`。通知失败时按 [通知概览](/global/api-reference/version/100/cn/common/asyncNotification) 中的间隔重试；亦可调用订单查询接口 `/v1/pay/order/query` 补偿查单。

## 概述

本页说明 `webhook gatePaymentNotify`。完整的参数、响应结构与示例由上方关联的 OpenAPI 或 webhook 定义渲染。

Gate 支付订单状态变更时，GatePay 向商户配置的 callback URL 发送异步通知（`bizType` 为 `PAY`）。

## 说明

* 建议基于 `merchantTradeNo` 或 `bizId` 做幂等处理。
* 验签、重试、`data` 解析与成功应答见 [通知概览](/global/api-reference/version/100/cn/common/asyncNotification)；签名规则见 [安全与签名](/global/api-reference/version/100/cn/common/securityAndSignature)。

## 触发情形

* 订单状态发生改变时（如支付成功、超出支付时间、订单取消或关闭等），GatePay 向商户注册时配置的 **callback URL** 发送通知
* 若通知投递失败，重试规则见 [通知概览](/global/api-reference/version/100/cn/common/asyncNotification)。

**适用范围**：通过托管收银台、Web/客户端拉起等方式下单，用户通过 **Gate 支付账户** 完成付款的场景（`bizType` 为 `PAY`）。接入说明见 [支付](/global/essentials/version/100/cn/inflow/payment/payment)。

## 消息结构

| 字段名 | 类型 | 说明 |
| - | - | - |
| `bizType` | string | 固定为 `PAY` |
| `bizId` | string | 预付单 ID（订单 ID） |
| `bizStatus` | string | 订单状态，见下表 |
| `client_id` | string | 创建订单的商户 `client_id`（部分回调可能不返回，以实际为准） |
| `data` | string | 订单数据 JSON 字符串 |

### 消息结构示例

```json theme={null}
{
  "bizType": "PAY",
  "bizId": "79553572569350157",
  "bizStatus": "PAY_SUCCESS",
  "data": "{\"accountId\":10002,\"channelId\":\"\",\"createTime\":1780037371613,\"currency\":\"USDT\",\"doneAmountOnChain\":\"0\",\"goodsName\":\"KM/ORDER-63FDE37F - PUBG Mobile UC Global ( Special Offer ) - PUBG 1800 UC x 1\",\"merchantTradeNo\":\"6a1936fb6ac6f72b7a817576\",\"orderAmount\":\"21.88\",\"payerId\":16839589,\"productName\":\"KM/ORDER-63FDE37F - PUBG Mobile UC Global ( Special Offer ) - PUBG 1800 UC x 1\",\"productType\":\"\",\"terminalType\":\"WEB\",\"tradeType\":\"WEB\",\"waitAmountOnChain\":\"0\"}"
}
```

## bizStatus 枚举值

| 值 | 说明 |
| - | - |
| `PAY_SUCCESS` | 订单支付成功 |
| `PAY_ERROR` | 订单支付遇到错误 |
| `PAY_CLOSE` | 订单被商户关闭或订单超时 |

## data 字段说明

| 字段名 | 类型 | 说明 |
| - | - | - |
| `merchantTradeNo` | string | 商户交易号 |
| `productType` | string | 创建订单时的 `goodsType` |
| `productName` | string | 创建订单时的 `goodsName` |
| `tradeType` | string | 创建订单时的 `terminalType` |
| `goodsName` | string | 商品名称 |
| `terminalType` | string | 终端类型 |
| `currency` | string | 订单币种 |
| `orderAmount` | string | 订单金额（Gate 支付成功时为支付金额） |
| `totalFee` | string | 订单金额（部分回调中与 `orderAmount` 同时返回） |
| `expectCurrency` | string | 商户指定营收币种 |
| `actualCurrency` | string | 平台向商户结算的实际币种 |
| `actualAmount` | string | 对应 `actualCurrency` 的金额 |
| `payerId` | int64 | 支付用户 UID |
| `createTime` | int64 | 订单创建时间（毫秒） |
| `transactionId` | string | 平台交易 ID（部分回调可能不返回） |
| `channelId` | string | 客户名称 / 渠道标识 |
| `doneAmountOnChain` | string | 链上已确认金额 |
| `waitAmountOnChain` | string | 链上待确认金额 |
| `accountId` | int64 | 订单所属的账户ID（商户或机构发起返回其账户ID，机构代子账户发起则返回子账户ID） |

## 回调示例

### 支付成功（`bizStatus=PAY_SUCCESS`）

```json theme={null}
{
  "bizType": "PAY",
  "bizId": "79553572569350157",
  "bizStatus": "PAY_SUCCESS",
  "data": "{\"accountId\":10002,\"channelId\":\"\",\"createTime\":1780037371613,\"currency\":\"USDT\",\"doneAmountOnChain\":\"0\",\"goodsName\":\"KM/ORDER-63FDE37F - PUBG Mobile UC Global ( Special Offer ) - PUBG 1800 UC x 1\",\"merchantTradeNo\":\"6a1936fb6ac6f72b7a817576\",\"orderAmount\":\"21.88\",\"payerId\":16839589,\"productName\":\"KM/ORDER-63FDE37F - PUBG Mobile UC Global ( Special Offer ) - PUBG 1800 UC x 1\",\"productType\":\"\",\"terminalType\":\"WEB\",\"tradeType\":\"WEB\",\"waitAmountOnChain\":\"0\"}"
}
```

### 订单关闭（`bizStatus=PAY_CLOSE`）

```json theme={null}
{
  "bizType": "PAY",
  "bizId": "79553572569350157",
  "bizStatus": "PAY_CLOSE",
  "data": "{\"accountId\":10002,\"channelId\":\"\",\"createTime\":1780037371613,\"currency\":\"USDT\",\"doneAmountOnChain\":\"0\",\"goodsName\":\"KM/ORDER-63FDE37F\",\"merchantTradeNo\":\"6a1936fb6ac6f72b7a817576\",\"orderAmount\":\"21.88\",\"payerId\":0,\"productName\":\"KM/ORDER-63FDE37F\",\"productType\":\"\",\"terminalType\":\"WEB\",\"tradeType\":\"WEB\",\"waitAmountOnChain\":\"0\"}"
}
```

### 支付异常（`bizStatus=PAY_ERROR`）

```json theme={null}
{
  "bizType": "PAY",
  "bizId": "79553572569350157",
  "bizStatus": "PAY_ERROR",
  "data": "{\"accountId\":10002,\"channelId\":\"\",\"createTime\":1780037371613,\"currency\":\"USDT\",\"doneAmountOnChain\":\"0\",\"goodsName\":\"KM/ORDER-63FDE37F\",\"merchantTradeNo\":\"6a1936fb6ac6f72b7a817576\",\"orderAmount\":\"21.88\",\"payerId\":16839589,\"productName\":\"KM/ORDER-63FDE37F\",\"productType\":\"\",\"terminalType\":\"WEB\",\"tradeType\":\"WEB\",\"waitAmountOnChain\":\"0\"}"
}
```


## OpenAPI

````yaml global/api-reference/version/100/cn/openapi/gate-payment-callback-openapi.json webhook gatePaymentNotify
openapi: 3.1.0
info:
  title: GatePay Gate 支付回调 API
  version: 1.0.0
  description: >-
    Gate 支付（托管收银台、Web 拉起等通过 Gate 支付账户付款）订单状态异步通知。当预付单状态发生变化时，GatePay 向商户注册的
    callback URL 发送通知；`data` 为 JSON 字符串。
servers:
  - url: https://openplatform.gateapi.io
    description: 生产环境
security: []
paths: {}

````

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