Fiat Payment Status Notification

{
  "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

fiatPaymentWebhook

{
  "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": ""
}

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; see Security and Signature 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.

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

{
  "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
`payAccount`	string	Payment method used for the fiat payment; see enumeration below

payAccount Enumeration

Value	Payment Method
`card`	Card
`google_pay`	Google Pay
`apple_pay`	Apple Pay
`link`	Link

Callback Example

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

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

Payment error (`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\"}"
}

Body

application/json

bizType

enum<string>

required

Business type; always PAY_FIAT.

Available options:

PAY_FIAT

bizId

string

required

Prepaid order ID.

bizStatus

enum<string>

required

Fiat payment order status.

Available options:

PAY_SUCCESS,

PAY_ERROR,

PAY_CLOSE

data

string

required

Business data as a JSON string; parsed structure see fiatPaymentData.

client_id

string

Merchant client_id that created the order.

fiatPaymentData

object

Parsed fiat payment order details from data.

Show child attributes

description

any

Response

200 - application/json

HTTP 200 indicates the merchant successfully received the notification.

Response body returned by the merchant after receiving the notification.

returnCode

string

required

Return status code; SUCCESS indicates success.

returnMessage

string | null

Return message; may be empty on success.

Gate Payment Status Notification

Batch Transfer Status Notification

⌘I

Common

Balance

Institution

Payment

OTC

Convert

Payout

Gift Card

Subscription

Reconciliation

Notifications

Fiat Payment Status Notification

Overview

Notes

Trigger Scenarios

Message Structure

Example Message

bizStatus Enumeration

data Field Reference

payAccount Enumeration

Callback Example

Fiat payment succeeded (`bizStatus=PAY_SUCCESS`)

Order closed (`bizStatus=PAY_CLOSE`)

Payment error (`bizStatus=PAY_ERROR`)

Body

Response

​Overview

​Notes

​Trigger Scenarios

​Message Structure

​Example Message

​bizStatus Enumeration

​data Field Reference

​payAccount Enumeration

​Callback Example

​Fiat payment succeeded (bizStatus=PAY_SUCCESS)

​Order closed (bizStatus=PAY_CLOSE)

​Payment error (bizStatus=PAY_ERROR)

Body

Response

Overview

Notes

Trigger Scenarios

Message Structure

Example Message

bizStatus Enumeration

data Field Reference

payAccount Enumeration

Callback Example

Fiat payment succeeded (`bizStatus=PAY_SUCCESS`)

Order closed (`bizStatus=PAY_CLOSE`)

Payment error (`bizStatus=PAY_ERROR`)