跳转到主要内容
WEBHOOK
addressPaymentNotify
{
  "bizType": "PAY_ADDRESS",
  "bizId": "79553671353466882",
  "bizStatus": "PAY_SUCCESS",
  "client_id": "cuqrgOWUjWusqagz",
  "data": "{\"address\":\"0xa4EE143921a6Fb307c620506Be533A3e6c0edE12\",\"chain\":\"BSC\",\"channelId\":\"\",\"clientId\":\"cuqrgOWUjWusqagz\",\"createTime\":1780037563198,\"currency\":\"USDT\",\"doneAmountOnChain\":\"98.2\",\"fromAddress\":\"0xBD612a3f30dcA67bF60a39Fd0D35e39B7aB80774\",\"goodsName\":\"Wallet Deposit\",\"merchantTradeNo\":\"01kss83byksw7h7k60n957e50e\",\"orderAmount\":\"98.2\",\"originalOrderId\":\"\",\"payerId\":0,\"productName\":\"Wallet Deposit\",\"productType\":\"\",\"terminalType\":\"APP\",\"tradeType\":\"APP\",\"transactionId\":\"\",\"waitAmountOnChain\":\"0\"}"
}
{
  "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.

​
概述

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

​
说明

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

​
触发情形

  • 订单由创建状态转为支付完成状态
  • 订单由创建状态转为过期状态
  • 用户在有效期内支付足够金额，但截止订单过期时间链上未确认完毕，进入 PROCESS 状态
  • 订单结束（过期或完成）前，每次检测到成功的支付记录后向商户支付账户转入对应金额；有效期内累计某笔付款总金额达到订单金额后将订单状态改为完成
  • 订单结束后，订单地址检测到新的到账，确认完毕后转入商户支付账户
  • 订单结束后，闪兑订单地址检测到新的到账

​
消息结构

字段名类型说明
bizTypestring通知类别，见下表
bizIdstring订单 ID
bizStatusstring业务状态，见下表
client_idstring创建订单的商户 client_id（TRANSFER_ADDRESS 等场景常见）
datastring业务数据 JSON 字符串；结构因 bizType 不同而不同

​
bizType 枚举值

值说明
PAY_ADDRESS订单状态变更通知
TRANSFER_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闪兑：延迟到账，通知商户但不充值到商户支付账户
TRANSFERRED_ADDRESS_BLOCK资金 Gate 已成功接收，但有风险，不会入账

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

字段名类型说明
merchantTradeNostring商户交易号
productTypestring创建订单时的 goodsType
productNamestring创建订单时的 goodsName
tradeTypestring创建订单时的 terminalType
goodsNamestring商品名称
terminalTypestring终端类型
currencystring订单币种
orderAmountstring订单金额
underpaidAmountstring支付完成后未支付金额
payerIdint64支付用户 UID
createTimeint64订单创建时间（毫秒）
transactionIdstring交易流水号
waitAmountOnChainstring链上有效期内确认中金额
doneAmountOnChainstring链上有效期内确认完毕金额
channelIdstring客户名称
chainstring网络
addressstring收款地址
fromAddressstring付款方地址
clientIdstringdata 内嵌的商户 client_id（与顶层 client_id 可能同时出现）
originalOrderIdstring关联原订单 ID（闪兑等场景，无则空字符串）

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

除上表部分字段外，还可能包含：
字段名类型说明
totalFeestring订单金额
payCurrencystring支付币种
payAmountstring要求支付金额
ratestring汇率
transferAmountstring给商户转账金额；状态变更通知中常为空字符串
overPaystring用户超额支付部分；仅支付成功时有值，其它为 0

​
data 字段说明（bizType=TRANSFER_ADDRESS）

字段名类型说明
merchantTradeNostring商户交易号
productTypestring创建订单时的 goodsType
productNamestring创建订单时的 goodsName
tradeTypestring创建订单时的 terminalType
goodsNamestring商品名称
terminalTypestring终端类型
currencystring订单币种
orderAmountstring订单金额
payerIdint64支付用户 UID
createTimeint64订单创建时间（毫秒）
transactionIdstring交易流水号
transferAmountstring给商户转账金额（到账金额）
channelIdstring客户名称
chainstring网络
addressstring收款地址
txHash / tx_hashstring链上交易 Hash（建议兼容解析）

​
回调示例

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

{
  "bizType": "PAY_ADDRESS",
  "bizId": "79553671353466882",
  "bizStatus": "PAY_SUCCESS",
  "client_id": "cuqrgOWUjWusqagz",
  "data": "{\"address\":\"0xa4EE143921a6Fb307c620506Be533A3e6c0edE12\",\"chain\":\"BSC\",\"channelId\":\"\",\"clientId\":\"cuqrgOWUjWusqagz\",\"createTime\":1780037563198,\"currency\":\"USDT\",\"doneAmountOnChain\":\"98.2\",\"fromAddress\":\"0xBD612a3f30dcA67bF60a39Fd0D35e39B7aB80774\",\"goodsName\":\"Wallet Deposit\",\"merchantTradeNo\":\"01kss83byksw7h7k60n957e50e\",\"orderAmount\":\"98.2\",\"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": "{\"merchantTradeNo\":\"938402023010600017\",\"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": "{\"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\",\"transactionId\":\"79553755105198106\",\"transferAmount\":\"98.2\",\"tx_hash\":\"0xaddbe7f0f9c3ce0aac7d897266393dff31f9bf1741915691467436efc07dbe0e\"}"
}

请求体

application/json
​
bizType
enum<string>
必填

通知类别：PAY_ADDRESS 订单状态变更；TRANSFER_ADDRESS 订单资金流转。

可用选项:
PAY_ADDRESS,
TRANSFER_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、TRANSFERRED_ADDRESS_BLOCK。

​
data
string
必填

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

​
client_id
string

创建订单的商户 client_id。

​
addressPaymentData
object

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

​
description
any

响应

200 - application/json

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

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

​
returnCode
string
必填

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

​
returnMessage
string | null

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