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

# 地址支付状态通知

> 地址支付场景下，GatePay 通过 `PAY_ADDRESS`（订单状态变更）、`TRANSFER_ADDRESS`（订单资金流转）与 `CHAIN_ADDRESS`（链上交易与验证状态）向商户 callback URL 投递消息。

商户须校验签名，处理成功后返回 `{"returnCode":"SUCCESS","returnMessage":""}`。通知失败时按 [通知概览](/global/api-reference/version/100/cn/common/asyncNotification) 中的间隔重试。

## 概述

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

地址支付订单状态或资金流转变更时，GatePay 向商户配置的 callback URL 发送异步通知（`bizType` 为 `PAY_ADDRESS`、`TRANSFER_ADDRESS` 或 `CHAIN_ADDRESS`）。

## 说明

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

## 触发情形

* 订单由创建状态转为支付完成状态
* 订单由创建状态转为过期状态
* 用户在有效期内支付足够金额，但截止订单过期时间链上未确认完毕，进入 `PROCESS` 状态
* 订单结束（过期或完成）前，每次检测到成功的支付记录后向商户余额账户转入对应金额；有效期内累计某笔付款总金额达到订单金额后将订单状态改为完成
* 订单结束后，订单地址检测到新的到账，确认完毕后转入商户余额账户
* 订单结束后，闪兑订单地址检测到新的到账
* 动态地址支付场景下，链上充值交易同步、合规验证、确认完成等生命周期节点（`CHAIN_ADDRESS`）

## 消息结构

| 字段名 | 类型 | 说明 |
| - | - | - |
| `bizType` | string | 通知类别，见下表 |
| `bizId` | string | 订单 ID |
| `bizStatus` | string | 业务状态，见下表 |
| `client_id` | string | 创建订单的商户 `client_id`（`TRANSFER_ADDRESS` 等场景常见） |
| `data` | string | 业务数据 JSON 字符串；结构因 `bizType` 不同而不同 |

## bizType 枚举值

| 值 | 说明 |
| - | - |
| `PAY_ADDRESS` | 订单状态变更通知 |
| `TRANSFER_ADDRESS` | 订单资金流转通知 |
| `CHAIN_ADDRESS` | 链上交易与验证状态通知（充值同步、合规通过、交易确认） |

## bizStatus 枚举值（`bizType=PAY_ADDRESS`）

| 值 | 说明 |
| - | - |
| `PAY_SUCCESS` | 订单支付成功 |
| `PAY_ERROR` | 订单支付遇到错误 |
| `PAY_CLOSE` | 订单过期，订单关闭 |
| `PAY_EXPIRED_IN_PROCESS` | 用户在有效期内支付金额 ≥ 订单金额，但链上仍有尚未确认的支付单，订单进入 `PROCESS` 中间状态 |

闪兑地址支付单还可能使用 `PAY_EXPIRED_IN_EXCHANGE_FLUCTUATION` 等状态（以实际回调为准）。

## bizStatus 枚举值（`bizType=TRANSFER_ADDRESS`）

| 值 | 说明 |
| - | - |
| `TRANSFERRED_ADDRESS_IN_TERM` | 非闪兑：检测到成功支付后，将对应金额充值到商户余额账户（有效期内到账） |
| `TRANSFERRED_ADDRESS_DELAY` | 非闪兑：延迟支付记录对应金额充值到商户余额账户（超过有效期到账） |
| `CONVERT_ADDRESS_PAY_DELAY` | 闪兑：延迟到账，通知商户但不充值到商户余额账户 |
| `PAY_PASSED` | 非闪兑：链上交易合规验证通过 |
| `PAY_CONFIRMING` | 非闪兑：链上交易开始同步 |
| `PAY_DONE` | 非闪兑：链上交易已确认 |

## bizStatus 枚举值（`bizType=CHAIN_ADDRESS`）

| 值 | 说明 |
| - | - |
| `PAY_PASSED` | 链上交易合规验证通过 |
| `PAY_CONFIRMING` | 链上交易开始同步 |
| `PAY_DONE` | 链上交易已确认 |

> 仅作为记录链上交易与验证过程中的状态，不能等同于订单终态

## data 字段说明（`bizType=PAY_ADDRESS`，非闪兑）

| 字段名 | 类型 | 说明 |
| - | - | - |
| `merchantTradeNo` | string | 商户交易号 |
| `originalMerchantTradeNo` | string | 关联的原始商户订单号（补单、闪兑等场景有值） |
| `productType` | string | 创建订单时的 `goodsType` |
| `productName` | string | 创建订单时的 `goodsName` |
| `tradeType` | string | 创建订单时的 `terminalType` |
| `goodsName` | string | 商品名称 |
| `terminalType` | string | 终端类型 |
| `currency` | string | 订单币种 |
| `orderAmount` | string | 订单金额 |
| `underpaidAmount` | string | 支付完成后未支付金额 |
| `payerId` | int64 | 支付用户 UID |
| `createTime` | int64 | 订单创建时间（毫秒） |
| `transactionId` | string | 交易流水号 |
| `waitAmountOnChain` | string | 链上有效期内确认中金额 |
| `doneAmountOnChain` | string | 链上有效期内确认完毕金额 |
| `channelId` | string | 客户名称 |
| `chain` | string | 网络 |
| `address` | string | 收款地址 |
| `fromAddress` | string | 付款方地址 |
| `clientId` | string | `data` 内嵌的商户 `client_id`（与顶层 `client_id` 可能同时出现） |
| `originalOrderId` | string | 关联 Gate Pay 原始订单号（补单、闪兑等场景有值） |
| `accountId` | int64 | 订单所属的账户ID（商户或机构发起返回其账户ID，机构代子账户发起则返回子账户ID） |

## data 字段说明（`bizType=PAY_ADDRESS`，闪兑）

除上表部分字段外，还可能包含：

| 字段名 | 类型 | 说明 |
| - | - | - |
| `totalFee` | string | 订单金额 |
| `payCurrency` | string | 支付币种 |
| `payAmount` | string | 要求支付金额 |
| `rate` | string | 汇率 |
| `transferAmount` | string | 用户的实际支付金额；状态变更通知中常为空字符串 |
| `overPay` | string | 用户超额支付部分；仅支付成功时有值，其它为 `0` |
| `accountId` | int64 | 订单所属的账户ID（商户或机构发起返回其账户ID，机构代子账户发起则返回子账户ID） |

## data 字段说明（`bizType=TRANSFER_ADDRESS`）

| 字段名 | 类型 | 说明 |
| - | - | - |
| `merchantTradeNo` | string | 商户交易号 |
| `originalMerchantTradeNo` | string | 关联的原始商户订单号（补单、闪兑等场景有值） |
| `originalOrderId` | string | 关联 Gate Pay 原始订单号（补单、闪兑等场景有值） |
| `productType` | string | 创建订单时的 `goodsType` |
| `productName` | string | 创建订单时的 `goodsName` |
| `tradeType` | string | 创建订单时的 `terminalType` |
| `goodsName` | string | 商品名称 |
| `terminalType` | string | 终端类型 |
| `currency` | string | 订单币种 |
| `orderAmount` | string | 订单金额 |
| `payerId` | int64 | 支付用户 UID |
| `createTime` | int64 | 订单创建时间（毫秒） |
| `transactionId` | string | 交易流水号 |
| `transferAmount` | string | 用户的实际支付金额 |
| `channelId` | string | 客户名称 |
| `chain` | string | 网络 |
| `address` | string | 收款地址 |
| `txHash` / `tx_hash` | string | 链上交易 Hash（建议兼容解析） |
| `accountId` | int64 | 订单所属的账户ID（商户或机构发起返回其账户ID，机构代子账户发起则返回子账户ID） |

## data 字段说明（`bizType=CHAIN_ADDRESS`）

| 字段名 | 类型 | 说明 |
| - | - | - |
| `merchantTradeNo` | string | 商户交易号 |
| `productType` | string | 创建订单时的 `goodsType` |
| `productName` | string | 创建订单时的 `goodsName` |
| `clientId` | string | 商户 `client_id` |
| `tradeType` | string | 创建订单时的 `terminalType` |
| `goodsName` | string | 商品名称 |
| `terminalType` | string | 终端类型 |
| `currency` | string | 订单币种 |
| `orderAmount` | number | 订单金额 |
| `payerId` | int64 | 支付用户 UID |
| `createTime` | int64 | 订单创建时间（毫秒） |
| `transferAmount` | number | 链上到账金额 |
| `txHash` | string | 链上交易 Hash |
| `channelId` | string | 客户名称 |
| `chain` | string | 网络 |
| `address` | string | 收款地址 |
| `fromAddress` | string | 付款方地址 |
| `passedTime` | int64 | 链上交易合规验证通过时间（毫秒）；`bizStatus=PAY_PASSED` 时返回 |
| `confirmingTime` | int64 | 链上交易开始同步时间（毫秒）；`bizStatus=PAY_CONFIRMING` 时返回 |
| `doneTime` | int64 | 链上交易已确认时间（毫秒）；`bizStatus=PAY_DONE` 时返回 |
| `accountId` | int64 | 订单所属的账户ID（商户或机构发起返回其账户ID，机构代子账户发起则返回子账户ID） |

## 回调示例

### 订单状态变更（`bizType=PAY_ADDRESS`，支付成功）

```json theme={null}
{
  "bizType": "PAY_ADDRESS",
  "bizId": "79553671353466882",
  "bizStatus": "PAY_SUCCESS",
  "client_id": "cuqrgOWUjWusqagz",
  "data": "{\"accountId\":10002,\"address\":\"0xa4EE143921a6Fb307c620506Be533A3e6c0edE12\",\"chain\":\"BSC\",\"channelId\":\"\",\"clientId\":\"cuqrgOWUjWusqagz\",\"createTime\":1780037563198,\"currency\":\"USDT\",\"doneAmountOnChain\":\"98.2\",\"fromAddress\":\"0xBD612a3f30dcA67bF60a39Fd0D35e39B7aB80774\",\"goodsName\":\"Wallet Deposit\",\"merchantTradeNo\":\"01kss83byksw7h7k60n957e50e\",\"orderAmount\":\"98.2\",\"originalMerchantTradeNo\":\"\",\"originalOrderId\":\"\",\"payerId\":0,\"productName\":\"Wallet Deposit\",\"productType\":\"\",\"terminalType\":\"APP\",\"tradeType\":\"APP\",\"transactionId\":\"\",\"waitAmountOnChain\":\"0\"}"
}
```

### 订单状态变更（`bizType=PAY_ADDRESS`，闪兑）

```json theme={null}
{
  "bizType": "PAY_ADDRESS",
  "bizId": "46301072319320064",
  "bizStatus": "PAY_EXPIRED_IN_EXCHANGE_FLUCTUATION",
  "client_id": "ygMRT5SdrGpiISVV",
  "data": "{\"accountId\":10002,\"merchantTradeNo\":\"938402023010600017\",\"originalMerchantTradeNo\":\"\",\"productType\":\"\",\"productName\":\"USDT_PAY_WMHH_TEST\",\"tradeType\":\"MINIAPP\",\"goodsName\":\"USDT_PAY_WMHH_TEST\",\"terminalType\":\"MINIAPP\",\"currency\":\"USDT\",\"totalFee\":\"2.1\",\"orderAmount\":\"2.1\",\"payCurrency\":\"WMHH\",\"payAmount\":\"0.2142\",\"rate\":\"0.1\",\"payerId\":10002,\"createTime\":1673000635873,\"transactionId\":\"\",\"waitAmountOnChain\":\"0\",\"doneAmountOnChain\":\"0.2142\",\"transferAmount\":\"\",\"overPay\":\"0\"}"
}
```

### 资金流转（`bizType=TRANSFER_ADDRESS`）

```json theme={null}
{
  "bizType": "TRANSFER_ADDRESS",
  "bizId": "79553671353466882",
  "bizStatus": "TRANSFERRED_ADDRESS_IN_TERM",
  "client_id": "cuqrgOWUjWusqagz",
  "data": "{\"accountId\":10002,\"address\":\"0xa4EE143921a6Fb307c620506Be533A3e6c0edE12\",\"chain\":\"BSC\",\"channelId\":\"\",\"clientId\":\"cuqrgOWUjWusqagz\",\"createTime\":1780037563198,\"currency\":\"USDT\",\"fromAddress\":\"0xBD612a3f30dcA67bF60a39Fd0D35e39B7aB80774\",\"goodsName\":\"\",\"merchantTradeNo\":\"01kss83byksw7h7k60n957e50e\",\"orderAmount\":\"98.2\",\"originalMerchantTradeNo\":\"\",\"originalOrderId\":\"\",\"payerId\":0,\"productName\":\"Wallet Deposit\",\"productType\":\"\",\"terminalType\":\"APP\",\"tradeType\":\"APP\",\"transactionId\":\"79553755105198106\",\"transferAmount\":\"98.2\",\"tx_hash\":\"0xaddbe7f0f9c3ce0aac7d897266393dff31f9bf1741915691467436efc07dbe0e\"}"
}
```

### 链上交易与验证状态（`bizType=CHAIN_ADDRESS`）

```json theme={null}
{
  "bizType": "CHAIN_ADDRESS",
  "bizId": "79553671353466882",
  "bizStatus": "PAY_PASSED",
  "client_id": "cuqrgOWUjWusqagz",
  "data": "{\"accountId\":10002,\"address\":\"0xa4EE143921a6Fb307c620506Be533A3e6c0edE12\",\"chain\":\"BSC\",\"channelId\":\"\",\"clientId\":\"cuqrgOWUjWusqagz\",\"createTime\":1780037563198,\"currency\":\"USDT\",\"fromAddress\":\"0xBD612a3f30dcA67bF60a39Fd0D35e39B7aB80774\",\"goodsName\":\"\",\"merchantTradeNo\":\"01kss83byksw7h7k60n957e50e\",\"orderAmount\":98.2,\"payerId\":0,\"productName\":\"Wallet Deposit\",\"productType\":\"\",\"terminalType\":\"APP\",\"tradeType\":\"APP\",\"transferAmount\":98.2,\"txHash\":\"0xaddbe7f0f9c3ce0aac7d897266393dff31f9bf1741915691467436efc07dbe0e\",\"passedTime\":1780037570000}"
}
```


## OpenAPI

````yaml global/api-reference/version/100/cn/openapi/address-payment-callback-openapi.json webhook addressPaymentNotify
openapi: 3.1.0
info:
  title: GatePay 地址支付回调 API
  version: 1.0.0
  description: >-
    地址支付订单状态变更与资金流转回调。GatePay 向商户注册时配置的 callback URL 发送异步 POST 通知；`data` 为 JSON
    字符串，须先验签再处理。
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.