> ## 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":""}`。通知失败时按 [通知概览](/api-reference/version/100/cn/common/asyncNotification) 中的间隔重试。 ## 概述 本页说明 `webhook addressPaymentNotify`。完整的参数、响应结构与示例由上方关联的 OpenAPI 或 webhook 定义渲染。 地址支付订单状态或资金流转变更时，GatePay 向商户配置的 callback URL 发送异步通知（`bizType` 为 `PAY_ADDRESS`、`TRANSFER_ADDRESS` 或 `CHAIN_ADDRESS`）。 ## 说明 * 建议基于 `merchantTradeNo` 或 `bizId` 做幂等处理。 * 验签、重试、`data` 解析与成功应答见 [通知概览](/api-reference/version/100/cn/common/asyncNotification)；签名规则见 [安全与签名](/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` | 闪兑：延迟到账，通知商户但不充值到商户余额账户 | ## 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 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: {} ````