Skip to main content
WEBHOOK
addressPaymentWebhook
{ "bizType": "PAY_ADDRESS", "bizId": "79553671353466882", "bizStatus": "PAY_SUCCESS", "client_id": "cuqrgOWUjWusqagz", "data": "{\"address\":\"0xa4EE143921a6Fb307c620506Be533A3e6c0edE12\",\"chain\":\"BSC\",\"channelId\":\"\",\"clientId\":\"cuqrgOWUjWusqagz\",\"createTime\":1780037563198,\"currency\":\"USDT\",\"doneAmountOnChain\":\"98.2\",\"fromAddress\":\"0xBD612a3f30dcA67bF60a39Fd0D35e39B7aB80774\",\"goodsName\":\"Wallet Deposit\",\"merchantTradeNo\":\"01kss83byksw7h7k60n957e50e\",\"orderAmount\":\"98.2\",\"originalOrderId\":\"\",\"payerId\":0,\"productName\":\"Wallet Deposit\",\"productType\":\"\",\"terminalType\":\"APP\",\"tradeType\":\"APP\",\"transactionId\":\"\",\"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 addressPaymentWebhook. 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 address payment order status or fund transfer status changes (bizType is PAY_ADDRESS or TRANSFER_ADDRESS).

​
Notes

​
Trigger Scenarios

  • Order status changes from created to payment completed
  • Order status changes from created to expired
  • User pays a sufficient amount within the validity period, but on-chain confirmation is incomplete at expiration, so the order enters PROCESS
  • Before an order finishes (expired or completed), each successful payment credits the merchant payment account; when cumulative payments reach the order amount within the validity period, the order is marked completed
  • After order completion, new payments to the order address are confirmed and credited to the merchant payment account
  • After order completion, new payments to a convert payment order address are detected

​
Message Structure

FieldTypeDescription
bizTypestringNotification category; see table below
bizIdstringOrder ID
bizStatusstringBusiness status; see tables below
client_idstringMerchant client_id that created the order (common in TRANSFER_ADDRESS and similar scenarios)
datastringBusiness payload as a JSON string; structure varies by bizType

​
bizType Enumeration

ValueDescription
PAY_ADDRESSOrder status change notification
TRANSFER_ADDRESSOrder fund transfer notification

​
bizStatus Values (bizType=PAY_ADDRESS)

ValueDescription
PAY_SUCCESSPayment succeeded
PAY_ERRORPayment error
PAY_CLOSEOrder expired and closed
PAY_EXPIRED_IN_PROCESSUser paid ≥ order amount within the validity period, but unconfirmed on-chain payments remain; order enters PROCESS
Convert address payment orders may also use statuses such as PAY_EXPIRED_IN_EXCHANGE_FLUCTUATION (as returned in the callback).

​
bizStatus Values (bizType=TRANSFER_ADDRESS)

ValueDescription
TRANSFERRED_ADDRESS_IN_TERMNon-convert: successful payment credited to merchant payment account within the validity period
TRANSFERRED_ADDRESS_DELAYNon-convert: delayed payment credited after the validity period
CONVERT_ADDRESS_PAY_DELAYConvert: delayed arrival notified but not credited to merchant payment account
TRANSFERRED_ADDRESS_BLOCKFunds received by Gate but held due to risk; not credited

​
data Fields (bizType=PAY_ADDRESS, non-convert)

FieldTypeDescription
merchantTradeNostringMerchant trade number
productTypestringgoodsType at order creation
productNamestringgoodsName at order creation
tradeTypestringterminalType at order creation
goodsNamestringGoods name
terminalTypestringTerminal type
currencystringOrder currency
orderAmountstringOrder amount
underpaidAmountstringRemaining unpaid amount after payment completes
payerIdint64Payer UID
createTimeint64Order creation time (milliseconds)
transactionIdstringTransaction ID
waitAmountOnChainstringAmount awaiting on-chain confirmation within the validity period
doneAmountOnChainstringAmount confirmed on-chain within the validity period
channelIdstringChannel identifier
chainstringBlockchain network
addressstringCollection address
fromAddressstringPayer address
clientIdstringMerchant client_id embedded in data (may appear together with top-level client_id)
originalOrderIdstringRelated original order ID (convert and similar scenarios; empty string if none)

​
data Fields (bizType=PAY_ADDRESS, convert)

In addition to fields above, convert orders may include:
FieldTypeDescription
totalFeestringOrder amount
payCurrencystringPayment currency
payAmountstringRequired payment amount
ratestringExchange rate
transferAmountstringAmount transferred to merchant; often empty in status-change notifications
overPaystringAmount paid above the order requirement; non-zero only on payment success

​
data Fields (bizType=TRANSFER_ADDRESS)

FieldTypeDescription
merchantTradeNostringMerchant trade number
productTypestringgoodsType at order creation
productNamestringgoodsName at order creation
tradeTypestringterminalType at order creation
goodsNamestringGoods name
terminalTypestringTerminal type
currencystringOrder currency
orderAmountstringOrder amount
payerIdint64Payer UID
createTimeint64Order creation time (milliseconds)
transactionIdstringTransaction ID
transferAmountstringAmount transferred to merchant (credited amount)
channelIdstringChannel identifier
chainstringBlockchain network
addressstringCollection address
txHash / tx_hashstringOn-chain transaction hash (parse compatibly)

​
Callback Examples

​
Order status change (bizType=PAY_ADDRESS, payment success)

{
  "bizType": "PAY_ADDRESS",
  "bizId": "79553671353466882",
  "bizStatus": "PAY_SUCCESS",
  "client_id": "cuqrgOWUjWusqagz",
  "data": "{\"address\":\"0xa4EE143921a6Fb307c620506Be533A3e6c0edE12\",\"chain\":\"BSC\",\"channelId\":\"\",\"clientId\":\"cuqrgOWUjWusqagz\",\"createTime\":1780037563198,\"currency\":\"USDT\",\"doneAmountOnChain\":\"98.2\",\"fromAddress\":\"0xBD612a3f30dcA67bF60a39Fd0D35e39B7aB80774\",\"goodsName\":\"Wallet Deposit\",\"merchantTradeNo\":\"01kss83byksw7h7k60n957e50e\",\"orderAmount\":\"98.2\",\"originalOrderId\":\"\",\"payerId\":0,\"productName\":\"Wallet Deposit\",\"productType\":\"\",\"terminalType\":\"APP\",\"tradeType\":\"APP\",\"transactionId\":\"\",\"waitAmountOnChain\":\"0\"}"
}

​
Order status change (bizType=PAY_ADDRESS, convert)

{
  "bizType": "PAY_ADDRESS",
  "bizId": "46301072319320064",
  "bizStatus": "PAY_EXPIRED_IN_EXCHANGE_FLUCTUATION",
  "client_id": "ygMRT5SdrGpiISVV",
  "data": "{\"merchantTradeNo\":\"938402023010600017\",\"productType\":\"\",\"productName\":\"USDT_PAY_WMHH_TEST\",\"tradeType\":\"MINIAPP\",\"goodsName\":\"USDT_PAY_WMHH_TEST\",\"terminalType\":\"MINIAPP\",\"currency\":\"USDT\",\"totalFee\":\"2.1\",\"orderAmount\":\"2.1\",\"payCurrency\":\"WMHH\",\"payAmount\":\"0.2142\",\"rate\":\"0.1\",\"payerId\":10002,\"createTime\":1673000635873,\"transactionId\":\"\",\"waitAmountOnChain\":\"0\",\"doneAmountOnChain\":\"0.2142\",\"transferAmount\":\"\",\"overPay\":\"0\"}"
}

​
Fund transfer (bizType=TRANSFER_ADDRESS)

{
  "bizType": "TRANSFER_ADDRESS",
  "bizId": "79553671353466882",
  "bizStatus": "TRANSFERRED_ADDRESS_IN_TERM",
  "client_id": "cuqrgOWUjWusqagz",
  "data": "{\"address\":\"0xa4EE143921a6Fb307c620506Be533A3e6c0edE12\",\"chain\":\"BSC\",\"channelId\":\"\",\"clientId\":\"cuqrgOWUjWusqagz\",\"createTime\":1780037563198,\"currency\":\"USDT\",\"fromAddress\":\"0xBD612a3f30dcA67bF60a39Fd0D35e39B7aB80774\",\"goodsName\":\"\",\"merchantTradeNo\":\"01kss83byksw7h7k60n957e50e\",\"orderAmount\":\"98.2\",\"payerId\":0,\"productName\":\"Wallet Deposit\",\"productType\":\"\",\"terminalType\":\"APP\",\"tradeType\":\"APP\",\"transactionId\":\"79553755105198106\",\"transferAmount\":\"98.2\",\"tx_hash\":\"0xaddbe7f0f9c3ce0aac7d897266393dff31f9bf1741915691467436efc07dbe0e\"}"
}

Body

application/json
​
bizType
enum<string>
required

Notification category: PAY_ADDRESS for order status change; TRANSFER_ADDRESS for fund transfer.

Available options:
PAY_ADDRESS,
TRANSFER_ADDRESS
​
bizId
string
required

Order ID.

​
bizStatus
string
required

Business status; varies by bizType. For PAY_ADDRESS: PAY_SUCCESS, PAY_ERROR, PAY_CLOSE, PAY_EXPIRED_IN_PROCESS, and similar. For TRANSFER_ADDRESS: TRANSFERRED_ADDRESS_IN_TERM, TRANSFERRED_ADDRESS_DELAY, CONVERT_ADDRESS_PAY_DELAY, TRANSFERRED_ADDRESS_BLOCK.

​
data
string
required

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

​
client_id
string

Merchant client_id that created the order.

​
addressPaymentData
object

Parsed data object. Fields differ for non-convert vs convert orders and for PAY_ADDRESS vs TRANSFER_ADDRESS.

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