跳转到主要内容
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": ""
}

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

​
说明

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

​
触发情形

  • 法币支付订单状态发生改变时（如支付成功、超出支付时间、订单取消或关闭等），GatePay 向商户注册时配置的 callback URL 发送通知
  • 若通知投递失败，重试规则见 通知概览。
适用范围：以法币币种下单并完成支付的订单（bizType 为 PAY_FIAT）。下单时若选择法币，平台会按实时汇率转换为加密货币收款。

​
消息结构

字段名类型说明
bizTypestring固定为 PAY_FIAT
bizIdstring预付单 ID（订单 ID）
bizStatusstring订单状态，见下表
client_idstring创建订单的商户 client_id（部分回调可能不返回，以实际为准）
datastring订单数据 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 字段说明

字段名类型说明
merchantTradeNostring商户交易号
productTypestring创建订单时的 goodsType
productNamestring创建订单时的 goodsName
tradeTypestring创建订单时的 terminalType
goodsNamestring商品名称
terminalTypestring终端类型
currencystring订单币种（法币）
orderAmountstring订单金额
expectCurrencystring商户指定营收币种
actualCurrencystring平台向商户结算的实际币种
actualAmountstring对应 actualCurrency 的金额
payerIdint64支付用户 UID；无 Gate 账户支付时为 0
createTimeint64订单创建时间（毫秒）
transactionIDstring平台交易 ID（部分历史回调亦可能为 transactionId，建议兼容解析）
channelIdstring客户名称 / 渠道标识
doneAmountOnChainstring链上已确认金额
waitAmountOnChainstring链上待确认金额

​
回调示例

​
法币支付成功（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 解析后的法币支付订单明细。

​
description
any

响应

200 - application/json

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

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

​
returnCode
string
必填

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

​
returnMessage
string | null

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