Address Payment Status Notification

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

{
  "returnCode": "SUCCESS",
  "returnMessage": ""
}

WEBHOOK

addressPaymentWebhook

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

{
  "returnCode": "SUCCESS",
  "returnMessage": ""
}

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, TRANSFER_ADDRESS, or CHAIN_ADDRESS).

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

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 balance 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 balance account
After order completion, new payments to a convert payment order address are detected
In dynamic address payment scenarios, on-chain deposit lifecycle events such as transaction sync, compliance verification, and confirmation (CHAIN_ADDRESS)

Message Structure

Field	Type	Description
`bizType`	string	Notification category; see table below
`bizId`	string	Order ID
`bizStatus`	string	Business status; see tables below
`client_id`	string	Merchant `client_id` that created the order (common in `TRANSFER_ADDRESS` and similar scenarios)
`data`	string	Business payload as a JSON string; structure varies by `bizType`

bizType Enumeration

Value	Description
`PAY_ADDRESS`	Order status change notification
`TRANSFER_ADDRESS`	Order fund transfer notification
`CHAIN_ADDRESS`	On-chain transaction and verification status notification (sync, compliance passed, confirmed)

bizStatus Values (`bizType=PAY_ADDRESS`)

Value	Description
`PAY_SUCCESS`	Payment succeeded
`PAY_ERROR`	Payment error
`PAY_CLOSE`	Order expired and closed
`PAY_EXPIRED_IN_PROCESS`	User 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`)

Value	Description
`TRANSFERRED_ADDRESS_IN_TERM`	Non-convert: successful payment credited to merchant balance account within the validity period
`TRANSFERRED_ADDRESS_DELAY`	Non-convert: delayed payment credited after the validity period
`CONVERT_ADDRESS_PAY_DELAY`	Convert: delayed arrival notified but not credited to merchant balance account

bizStatus Values (`bizType=CHAIN_ADDRESS`)

Value	Description
`PAY_PASSED`	On-chain transaction compliance verification passed
`PAY_CONFIRMING`	On-chain transaction sync started
`PAY_DONE`	On-chain transaction confirmed

These statuses only record the on-chain transaction and verification process and cannot be treated as order terminal states.

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

Field	Type	Description
`merchantTradeNo`	string	Merchant trade number
`originalMerchantTradeNo`	string	Associated original merchant order number (populated for supplementary-order, convert, and similar scenarios)
`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
`orderAmount`	string	Order amount
`underpaidAmount`	string	Remaining unpaid amount after payment completes
`payerId`	int64	Payer UID
`createTime`	int64	Order creation time (milliseconds)
`transactionId`	string	Transaction ID
`waitAmountOnChain`	string	Amount awaiting on-chain confirmation within the validity period
`doneAmountOnChain`	string	Amount confirmed on-chain within the validity period
`channelId`	string	Channel identifier
`chain`	string	Blockchain network
`address`	string	Collection address
`fromAddress`	string	Payer address
`clientId`	string	Merchant `client_id` embedded in `data` (may appear together with top-level `client_id`)
`originalOrderId`	string	Associated original Gate Pay order number (populated for supplementary-order, convert, and similar scenarios)
`accountId`	int64	Account ID that owns the order. Returns the merchant or institution’s own account ID when the merchant or institution initiates the order; returns the sub-account ID when the institution initiates on behalf of a sub-account.

data Fields (`bizType=PAY_ADDRESS`, convert)

In addition to fields above, convert orders may include:

Field	Type	Description
`totalFee`	string	Order amount
`payCurrency`	string	Payment currency
`payAmount`	string	Required payment amount
`rate`	string	Exchange rate
`transferAmount`	string	User’s actual payment amount; often empty in status-change notifications
`overPay`	string	Amount paid above the order requirement; non-zero only on payment success
`accountId`	int64	Account ID that owns the order. Returns the merchant or institution’s own account ID when the merchant or institution initiates the order; returns the sub-account ID when the institution initiates on behalf of a sub-account.

data Fields (`bizType=TRANSFER_ADDRESS`)

Field	Type	Description
`merchantTradeNo`	string	Merchant trade number
`originalMerchantTradeNo`	string	Associated original merchant order number (populated for supplementary-order, convert, and similar scenarios)
`originalOrderId`	string	Associated original Gate Pay order number (populated for supplementary-order, convert, and similar scenarios)
`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
`orderAmount`	string	Order amount
`payerId`	int64	Payer UID
`createTime`	int64	Order creation time (milliseconds)
`transactionId`	string	Transaction ID
`transferAmount`	string	User’s actual payment amount
`channelId`	string	Channel identifier
`chain`	string	Blockchain network
`address`	string	Collection address
`txHash` / `tx_hash`	string	On-chain transaction hash (parse compatibly)
`accountId`	int64	Account ID that owns the order. Returns the merchant or institution’s own account ID when the merchant or institution initiates the order; returns the sub-account ID when the institution initiates on behalf of a sub-account.

data Fields (`bizType=CHAIN_ADDRESS`)

Field	Type	Description
`merchantTradeNo`	string	Merchant trade number
`productType`	string	`goodsType` at order creation
`productName`	string	`goodsName` at order creation
`clientId`	string	Merchant `client_id`
`tradeType`	string	`terminalType` at order creation
`goodsName`	string	Goods name
`terminalType`	string	Terminal type
`currency`	string	Order currency
`orderAmount`	number	Order amount
`payerId`	int64	Payer UID
`createTime`	int64	Order creation time (milliseconds)
`transferAmount`	number	On-chain received amount
`txHash`	string	On-chain transaction hash
`channelId`	string	Channel identifier
`chain`	string	Blockchain network
`address`	string	Collection address
`fromAddress`	string	Payer address
`passedTime`	int64	On-chain transaction compliance verification passed time (milliseconds); returned when `bizStatus=PAY_PASSED`
`confirmingTime`	int64	On-chain transaction sync start time (milliseconds); returned when `bizStatus=PAY_CONFIRMING`
`doneTime`	int64	On-chain transaction confirmed time (milliseconds); returned when `bizStatus=PAY_DONE`
`accountId`	int64	Account ID that owns the order. Returns the merchant or institution’s own account ID when the merchant or institution initiates the order; returns the sub-account ID when the institution initiates on behalf of a sub-account.

Callback Examples

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

{
  "bizType": "PAY_ADDRESS",
  "bizId": "79553671353466882",
  "bizStatus": "PAY_SUCCESS",
  "client_id": "cuqrgOWUjWusqagz",
  "data": "{\"accountId\":10002,\"address\":\"0xa4EE143921a6Fb307c620506Be533A3e6c0edE12\",\"chain\":\"BSC\",\"channelId\":\"\",\"clientId\":\"cuqrgOWUjWusqagz\",\"createTime\":1780037563198,\"currency\":\"USDT\",\"doneAmountOnChain\":\"98.2\",\"fromAddress\":\"0xBD612a3f30dcA67bF60a39Fd0D35e39B7aB80774\",\"goodsName\":\"Wallet Deposit\",\"merchantTradeNo\":\"01kss83byksw7h7k60n957e50e\",\"orderAmount\":\"98.2\",\"originalMerchantTradeNo\":\"\",\"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": "{\"accountId\":10002,\"merchantTradeNo\":\"938402023010600017\",\"originalMerchantTradeNo\":\"\",\"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": "{\"accountId\":10002,\"address\":\"0xa4EE143921a6Fb307c620506Be533A3e6c0edE12\",\"chain\":\"BSC\",\"channelId\":\"\",\"clientId\":\"cuqrgOWUjWusqagz\",\"createTime\":1780037563198,\"currency\":\"USDT\",\"fromAddress\":\"0xBD612a3f30dcA67bF60a39Fd0D35e39B7aB80774\",\"goodsName\":\"\",\"merchantTradeNo\":\"01kss83byksw7h7k60n957e50e\",\"orderAmount\":\"98.2\",\"originalMerchantTradeNo\":\"\",\"originalOrderId\":\"\",\"payerId\":0,\"productName\":\"Wallet Deposit\",\"productType\":\"\",\"terminalType\":\"APP\",\"tradeType\":\"APP\",\"transactionId\":\"79553755105198106\",\"transferAmount\":\"98.2\",\"tx_hash\":\"0xaddbe7f0f9c3ce0aac7d897266393dff31f9bf1741915691467436efc07dbe0e\"}"
}

On-chain transaction and verification status (`bizType=CHAIN_ADDRESS`)

{
  "bizType": "CHAIN_ADDRESS",
  "bizId": "79553671353466882",
  "bizStatus": "PAY_PASSED",
  "client_id": "cuqrgOWUjWusqagz",
  "data": "{\"accountId\":10002,\"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\",\"transferAmount\":98.2,\"txHash\":\"0xaddbe7f0f9c3ce0aac7d897266393dff31f9bf1741915691467436efc07dbe0e\",\"passedTime\":1780037570000}"
}

Body

application/json

bizType

enum<string>

required

Notification category: PAY_ADDRESS for order status change; TRANSFER_ADDRESS for fund transfer; CHAIN_ADDRESS for on-chain transaction and verification status.

Available options:

PAY_ADDRESS,

TRANSFER_ADDRESS,

CHAIN_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. For CHAIN_ADDRESS: PAY_PASSED (on-chain transaction compliance verification passed), PAY_CONFIRMING (on-chain transaction sync started), PAY_DONE (on-chain transaction confirmed).

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 vs CHAIN_ADDRESS.

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.

Sub-account Verification Result Notification

Fixed Address Payment Status Notification

⌘I

Common

Balance

Institution

Payment

OTC

Convert

Payout

Gift Card

Subscription

Reconciliation

Notifications

Address Payment Status Notification

Overview

Notes

Trigger Scenarios

Message Structure

bizType Enumeration

bizStatus Values (`bizType=PAY_ADDRESS`)

bizStatus Values (`bizType=TRANSFER_ADDRESS`)

bizStatus Values (`bizType=CHAIN_ADDRESS`)

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

data Fields (`bizType=PAY_ADDRESS`, convert)

data Fields (`bizType=TRANSFER_ADDRESS`)

data Fields (`bizType=CHAIN_ADDRESS`)

Callback Examples

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

Order status change (`bizType=PAY_ADDRESS`, convert)

Fund transfer (`bizType=TRANSFER_ADDRESS`)

On-chain transaction and verification status (`bizType=CHAIN_ADDRESS`)

Body

Response

​Overview

​Notes

​Trigger Scenarios

​Message Structure

​bizType Enumeration

​bizStatus Values (bizType=PAY_ADDRESS)

​bizStatus Values (bizType=TRANSFER_ADDRESS)

​bizStatus Values (bizType=CHAIN_ADDRESS)

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

​data Fields (bizType=PAY_ADDRESS, convert)

​data Fields (bizType=TRANSFER_ADDRESS)

​data Fields (bizType=CHAIN_ADDRESS)

​Callback Examples

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

​Order status change (bizType=PAY_ADDRESS, convert)

​Fund transfer (bizType=TRANSFER_ADDRESS)

​On-chain transaction and verification status (bizType=CHAIN_ADDRESS)

Body

Response

Overview

Notes

Trigger Scenarios

Message Structure

bizType Enumeration

bizStatus Values (`bizType=PAY_ADDRESS`)

bizStatus Values (`bizType=TRANSFER_ADDRESS`)

bizStatus Values (`bizType=CHAIN_ADDRESS`)

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

data Fields (`bizType=PAY_ADDRESS`, convert)

data Fields (`bizType=TRANSFER_ADDRESS`)

data Fields (`bizType=CHAIN_ADDRESS`)

Callback Examples

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

Order status change (`bizType=PAY_ADDRESS`, convert)

Fund transfer (`bizType=TRANSFER_ADDRESS`)

On-chain transaction and verification status (`bizType=CHAIN_ADDRESS`)