> ## 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 发送 `bizType` 为 `PAY_FIAT` 的 webhook 通知。

商户须校验签名，处理成功后返回 `{"returnCode":"SUCCESS","returnMessage":""}`。通知失败时按 [通知概览](/api-reference/version/100/cn/common/asyncNotification) 中的间隔重试；亦可调用订单查询接口获取最新状态。

## 概述

本页说明 `webhook fiatPaymentNotify`。完整的参数、响应结构与示例由上方关联的 OpenAPI 或 webhook 定义渲染。

法币支付订单状态变更时，GatePay 向商户配置的 callback URL 发送异步通知（`bizType` 为 `PAY_FIAT`）。

## 说明

* 建议基于 `merchantTradeNo` 或 `bizId` 做幂等处理。
* 验签、重试、`data` 解析与成功应答见 [通知概览](/api-reference/version/100/cn/common/asyncNotification)；签名规则见 [安全与签名](/api-reference/version/100/cn/common/securityAndSignature)。

## 触发情形

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

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

## 消息结构

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

### 消息结构示例

```json theme={null}
{
  "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`）

```json theme={null}
{
  "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`）

```json theme={null}
{
  "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`）

```json theme={null}
{
  "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\"}"
}
```


## OpenAPI

````yaml api-reference/version/100/cn/openapi/fiat-payment-callback-openapi.json webhook fiatPaymentNotify
openapi: 3.1.0
info:
  title: GatePay 法币支付回调 API
  version: 1.0.0
  description: >-
    法币支付订单状态异步通知。当法币支付订单状态发生变化时，GatePay 向商户注册的 callback URL 发送通知；`data` 为 JSON
    字符串。
servers:
  - url: https://openplatform.gateapi.io
    description: 生产环境
security: []
paths: {}

````