法币支付状态通知

{
  "bizType": "PAY_FIAT",
  "bizId": "84818925449510912",
  "bizStatus": "PAY_SUCCESS",
  "data": "{\"channelId\":\"\",\"createTime\":1779935094492,\"currency\":\"USDT\",\"doneAmountOnChain\":\"0\",\"goodsName\":\"GateRouter Credits\",\"merchantTradeNo\":\"RC-2059215456644927488-1779935094210-105420\",\"orderAmount\":\"5\",\"payerId\":0,\"productName\":\"GateRouter Credits\",\"productType\":\"\",\"terminalType\":\"WEB\",\"tradeType\":\"WEB\",\"transactionID\":\"84818925449510914\",\"waitAmountOnChain\":\"0\"}"
}

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

WEBHOOK

fiatPaymentNotify

{
  "bizType": "PAY_FIAT",
  "bizId": "84818925449510912",
  "bizStatus": "PAY_SUCCESS",
  "data": "{\"channelId\":\"\",\"createTime\":1779935094492,\"currency\":\"USDT\",\"doneAmountOnChain\":\"0\",\"goodsName\":\"GateRouter Credits\",\"merchantTradeNo\":\"RC-2059215456644927488-1779935094210-105420\",\"orderAmount\":\"5\",\"payerId\":0,\"productName\":\"GateRouter Credits\",\"productType\":\"\",\"terminalType\":\"WEB\",\"tradeType\":\"WEB\",\"transactionID\":\"84818925449510914\",\"waitAmountOnChain\":\"0\"}"
}

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

概述

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

说明

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

触发情形

法币支付订单状态发生改变时（如支付成功、超出支付时间、订单取消或关闭等），GatePay 向商户注册时配置的 callback URL 发送通知
若通知投递失败，重试规则见通知概览。

适用范围：以法币币种下单并完成支付的订单（bizType 为 PAY_FIAT）。下单时若选择法币，平台会按实时汇率转换为加密货币收款。

消息结构

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

消息结构示例

{
  "bizType": "PAY_FIAT",
  "bizId": "84818925449510912",
  "bizStatus": "PAY_SUCCESS",
  "data": "{\"channelId\":\"\",\"createTime\":1779935094492,\"currency\":\"USDT\",\"doneAmountOnChain\":\"0\",\"goodsName\":\"GateRouter Credits\",\"merchantTradeNo\":\"RC-2059215456644927488-1779935094210-105420\",\"orderAmount\":\"5\",\"payerId\":0,\"productName\":\"GateRouter Credits\",\"productType\":\"\",\"terminalType\":\"WEB\",\"tradeType\":\"WEB\",\"transactionID\":\"84818925449510914\",\"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	订单金额
`expectCurrency`	string	商户指定营收币种
`actualCurrency`	string	平台向商户结算的实际币种
`actualAmount`	string	对应 `actualCurrency` 的金额
`payerId`	int64	支付用户 UID；无 Gate 账户支付时为 `0`
`createTime`	int64	订单创建时间（毫秒）
`transactionID`	string	平台交易 ID（部分历史回调亦可能为 `transactionId`，建议兼容解析）
`channelId`	string	客户名称 / 渠道标识
`doneAmountOnChain`	string	链上已确认金额
`waitAmountOnChain`	string	链上待确认金额
`payAccount`	string	法币支付使用的支付方式，枚举值见下表

payAccount 枚举值

值	支付方式
`card`	Card
`google_pay`	Google Pay
`apple_pay`	Apple Pay
`link`	Link

回调示例

法币支付成功（`bizStatus=PAY_SUCCESS`）

{
  "bizType": "PAY_FIAT",
  "bizId": "84818925449510912",
  "bizStatus": "PAY_SUCCESS",
  "data": "{\"channelId\":\"\",\"createTime\":1779935094492,\"currency\":\"USDT\",\"doneAmountOnChain\":\"0\",\"goodsName\":\"GateRouter Credits\",\"merchantTradeNo\":\"RC-2059215456644927488-1779935094210-105420\",\"orderAmount\":\"5\",\"payerId\":0,\"productName\":\"GateRouter Credits\",\"productType\":\"\",\"terminalType\":\"WEB\",\"tradeType\":\"WEB\",\"transactionID\":\"84818925449510914\",\"waitAmountOnChain\":\"0\"}"
}

订单关闭（`bizStatus=PAY_CLOSE`）

{
  "bizType": "PAY_FIAT",
  "bizId": "84818925449510912",
  "bizStatus": "PAY_CLOSE",
  "data": "{\"channelId\":\"\",\"createTime\":1779935094492,\"currency\":\"USDT\",\"doneAmountOnChain\":\"0\",\"goodsName\":\"GateRouter Credits\",\"merchantTradeNo\":\"RC-2059215456644927488-1779935094210-105420\",\"orderAmount\":\"5\",\"payerId\":0,\"productName\":\"GateRouter Credits\",\"productType\":\"\",\"terminalType\":\"WEB\",\"tradeType\":\"WEB\",\"waitAmountOnChain\":\"0\"}"
}

支付异常（`bizStatus=PAY_ERROR`）

{
  "bizType": "PAY_FIAT",
  "bizId": "84818925449510912",
  "bizStatus": "PAY_ERROR",
  "data": "{\"channelId\":\"\",\"createTime\":1779935094492,\"currency\":\"USDT\",\"doneAmountOnChain\":\"0\",\"goodsName\":\"GateRouter Credits\",\"merchantTradeNo\":\"RC-2059215456644927488-1779935094210-105420\",\"orderAmount\":\"5\",\"payerId\":0,\"productName\":\"GateRouter Credits\",\"productType\":\"\",\"terminalType\":\"WEB\",\"tradeType\":\"WEB\",\"waitAmountOnChain\":\"0\"}"
}

请求体

application/json

bizType

enum<string>

必填

业务类型，固定为 PAY_FIAT。

可用选项:

PAY_FIAT

bizId

string

必填

预付单 ID。

bizStatus

enum<string>

必填

法币支付订单状态。

可用选项:

PAY_SUCCESS,

PAY_ERROR,

PAY_CLOSE

data

string

必填

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

client_id

string

创建订单的商户 client_id。

fiatPaymentData

object

data 解析后的法币支付订单明细。

Show child attributes

description

any

响应

200 - application/json

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

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

returnCode

string

必填

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

returnMessage

string | null

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

Gate 支付状态通知

批量转账状态通知

⌘I

公共

余额

机构

支付

OTC

闪兑

出金

礼品卡

订阅

对账

通知

法币支付状态通知

概述

说明

触发情形

消息结构

消息结构示例

bizStatus 枚举值

data 字段说明

payAccount 枚举值

回调示例

法币支付成功（`bizStatus=PAY_SUCCESS`）

订单关闭（`bizStatus=PAY_CLOSE`）

支付异常（`bizStatus=PAY_ERROR`）

请求体

响应

​概述

​说明

​触发情形

​消息结构

​消息结构示例

​bizStatus 枚举值

​data 字段说明

​payAccount 枚举值

​回调示例

​法币支付成功（bizStatus=PAY_SUCCESS）

​订单关闭（bizStatus=PAY_CLOSE）

​支付异常（bizStatus=PAY_ERROR）

请求体

响应

概述

说明

触发情形

消息结构

消息结构示例

bizStatus 枚举值

data 字段说明

payAccount 枚举值

回调示例

法币支付成功（`bizStatus=PAY_SUCCESS`）

订单关闭（`bizStatus=PAY_CLOSE`）

支付异常（`bizStatus=PAY_ERROR`）