地址支付状态通知

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

{
  "returnCode": "SUCCESS",
  "returnMessage": ""
}

WEBHOOK

addressPaymentNotify

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

{
  "returnCode": "SUCCESS",
  "returnMessage": ""
}

概述

本页说明 webhook addressPaymentNotify。完整的参数、响应结构与示例由上方关联的 OpenAPI 或 webhook 定义渲染。地址支付订单状态或资金流转变更时，GatePay 向商户配置的 callback URL 发送异步通知（bizType 为 PAY_ADDRESS、TRANSFER_ADDRESS 或 CHAIN_ADDRESS）。

说明

建议基于 merchantTradeNo 或 bizId 做幂等处理。
验签、重试、data 解析与成功应答见通知概览；签名规则见安全与签名。

触发情形

订单由创建状态转为支付完成状态
订单由创建状态转为过期状态
用户在有效期内支付足够金额，但截止订单过期时间链上未确认完毕，进入 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`，支付成功）

{
  "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`，闪兑）

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

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

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

请求体

application/json

bizType

enum<string>

必填

通知类别：PAY_ADDRESS 订单状态变更；TRANSFER_ADDRESS 订单资金流转；CHAIN_ADDRESS 链上交易与验证状态通知。

可用选项:

PAY_ADDRESS,

TRANSFER_ADDRESS,

CHAIN_ADDRESS

bizId

string

必填

订单 ID。

bizStatus

string

必填

业务状态，因 bizType 而异。PAY_ADDRESS 常见：PAY_SUCCESS、PAY_ERROR、PAY_CLOSE、PAY_EXPIRED_IN_PROCESS 等；TRANSFER_ADDRESS 常见：TRANSFERRED_ADDRESS_IN_TERM、TRANSFERRED_ADDRESS_DELAY、CONVERT_ADDRESS_PAY_DELAY；CHAIN_ADDRESS 常见：PAY_PASSED（链上交易合规验证通过）、PAY_CONFIRMING（链上交易开始同步）、PAY_DONE（链上交易已确认）。

data

string

必填

业务数据 JSON 字符串，解析后结构见 addressPaymentData。

client_id

string

创建订单的商户 client_id。

addressPaymentData

object

data 解析后的对象；非闪兑/闪兑、PAY_ADDRESS/TRANSFER_ADDRESS/CHAIN_ADDRESS 下字段可能不同。

Show child attributes

description

any

响应

200 - application/json

返回 HTTP 200 表示商户已成功接收通知。

商户接收通知后的响应体。

returnCode

string

必填

返回状态码，SUCCESS 表示成功。

returnMessage

string | null

返回说明，成功时可为空。

子账户认证结果通知

静态地址支付状态通知

⌘I

公共

余额

机构

支付

OTC

闪兑

出金

礼品卡

订阅

对账

通知

地址支付状态通知

概述

说明

触发情形

消息结构

bizType 枚举值

bizStatus 枚举值（`bizType=PAY_ADDRESS`）

bizStatus 枚举值（`bizType=TRANSFER_ADDRESS`）

bizStatus 枚举值（`bizType=CHAIN_ADDRESS`）

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

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

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

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

回调示例

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

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

资金流转（`bizType=TRANSFER_ADDRESS`）

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

请求体

响应

​概述

​说明

​触发情形

​消息结构

​bizType 枚举值

​bizStatus 枚举值（bizType=PAY_ADDRESS）

​bizStatus 枚举值（bizType=TRANSFER_ADDRESS）

​bizStatus 枚举值（bizType=CHAIN_ADDRESS）

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

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

​data 字段说明（bizType=TRANSFER_ADDRESS）

​data 字段说明（bizType=CHAIN_ADDRESS）

​回调示例

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

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

​资金流转（bizType=TRANSFER_ADDRESS）

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

请求体

响应

概述

说明

触发情形

消息结构

bizType 枚举值

bizStatus 枚举值（`bizType=PAY_ADDRESS`）

bizStatus 枚举值（`bizType=TRANSFER_ADDRESS`）

bizStatus 枚举值（`bizType=CHAIN_ADDRESS`）

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

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

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

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

回调示例

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

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

资金流转（`bizType=TRANSFER_ADDRESS`）

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