Skip to main content
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": ""
}

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.

​
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

​
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

FieldTypeDescription
bizTypestringAlways PAY_FIAT
bizIdstringPrepaid order ID
bizStatusstringOrder status; see table below
client_idstringMerchant client_id that created the order (may be omitted in some callbacks; use actual payload)
datastringOrder 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

ValueDescription
PAY_SUCCESSPayment succeeded
PAY_ERRORPayment error
PAY_CLOSEOrder closed by merchant or timed out

​
data Field Reference

FieldTypeDescription
merchantTradeNostringMerchant trade number
productTypestringgoodsType at order creation
productNamestringgoodsName at order creation
tradeTypestringterminalType at order creation
goodsNamestringGoods name
terminalTypestringTerminal type
currencystringOrder currency (fiat)
orderAmountstringOrder amount
expectCurrencystringMerchant expected settlement currency
actualCurrencystringActual settlement currency
actualAmountstringAmount in actualCurrency
payerIdint64Payer UID; 0 when paid without a Gate account
createTimeint64Order creation time (milliseconds)
transactionIDstringPlatform transaction ID (some legacy callbacks may use transactionId; parse compatibly)
channelIdstringCustomer name / channel identifier
doneAmountOnChainstringOn-chain confirmed amount
waitAmountOnChainstringOn-chain amount awaiting confirmation

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

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