> ## 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.

# Fiat Payment Status Notification

> When a fiat payment order status changes, GatePay sends a webhook with `bizType` `PAY_FIAT`.

Verify the signature and return `{"returnCode":"SUCCESS","returnMessage":""}` after successful processing. On delivery failure, GatePay retries at the intervals documented in [Notifications Overview](/api-reference/version/100/en/common/asyncNotification); you may also call the order query API for the latest status.

## Overview

This page documents `webhook fiatPaymentWebhook`. The full schema, parameters, and examples are rendered from the linked OpenAPI or webhook definition above.

GatePay sends asynchronous notifications to the merchant callback URL when fiat payment order status changes (`bizType` is `PAY_FIAT`).

## Notes

* Use `merchantTradeNo` or `bizId` for idempotency.
* Signature verification, retries, parsing `data`, and the success response are covered in [Notifications Overview](/api-reference/version/100/en/common/asyncNotification); see [Security and Signature](/api-reference/version/100/en/common/securityAndSignature) for signing rules.

## Trigger Scenarios

* When a fiat payment order status changes (payment success, timeout, cancellation, or closure), GatePay sends a notification to the **callback URL** configured at merchant registration
* If delivery fails, see retry rules in [Notifications Overview](/api-reference/version/100/en/common/asyncNotification).

**Scope**: Orders placed and paid in fiat currency (`bizType` is `PAY_FIAT`). When fiat is selected at checkout, GatePay converts to crypto at the live rate for collection.

## Message Structure

| Field       | Type   | Description                                                                                        |
| ----------- | ------ | -------------------------------------------------------------------------------------------------- |
| `bizType`   | string | Always `PAY_FIAT`                                                                                  |
| `bizId`     | string | Prepaid order ID                                                                                   |
| `bizStatus` | string | Order status; see table below                                                                      |
| `client_id` | string | Merchant `client_id` that created the order (may be omitted in some callbacks; use actual payload) |
| `data`      | string | Order payload as a JSON string                                                                     |

### Example Message

```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 Enumeration

| Value         | Description                           |
| ------------- | ------------------------------------- |
| `PAY_SUCCESS` | Payment succeeded                     |
| `PAY_ERROR`   | Payment error                         |
| `PAY_CLOSE`   | Order closed by merchant or timed out |

## data Field Reference

| Field               | Type   | Description                                                                               |
| ------------------- | ------ | ----------------------------------------------------------------------------------------- |
| `merchantTradeNo`   | string | Merchant trade number                                                                     |
| `productType`       | string | `goodsType` at order creation                                                             |
| `productName`       | string | `goodsName` at order creation                                                             |
| `tradeType`         | string | `terminalType` at order creation                                                          |
| `goodsName`         | string | Goods name                                                                                |
| `terminalType`      | string | Terminal type                                                                             |
| `currency`          | string | Order currency (fiat)                                                                     |
| `orderAmount`       | string | Order amount                                                                              |
| `expectCurrency`    | string | Merchant expected settlement currency                                                     |
| `actualCurrency`    | string | Actual settlement currency                                                                |
| `actualAmount`      | string | Amount in `actualCurrency`                                                                |
| `payerId`           | int64  | Payer UID; `0` when paid without a Gate account                                           |
| `createTime`        | int64  | Order creation time (milliseconds)                                                        |
| `transactionID`     | string | Platform transaction ID (some legacy callbacks may use `transactionId`; parse compatibly) |
| `channelId`         | string | Customer name / channel identifier                                                        |
| `doneAmountOnChain` | string | On-chain confirmed amount                                                                 |
| `waitAmountOnChain` | string | On-chain amount awaiting confirmation                                                     |

## Callback Example

### Fiat payment succeeded (`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\"}"
}
```

### Order closed (`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\"}"
}
```

### Payment error (`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/en/openapi/fiat-payment-callback-openapi.json webhook fiatPaymentWebhook
openapi: 3.1.0
info:
  title: GatePay Fiat Payment Callback API
  version: 1.0.0
  description: >-
    Asynchronous notifications for fiat payment order status changes. When a
    fiat payment order status changes, GatePay sends a notification to the
    merchant callback URL; `data` is a JSON string.
servers:
  - url: https://openplatform.gateapi.io
    description: Production
security: []
paths: {}

````