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

# Address Payment Status Notification

> In address payment scenarios, GatePay delivers `PAY_ADDRESS` (order status change) and `TRANSFER_ADDRESS` (order fund transfer) notifications to the merchant callback URL.

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

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

* 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

* 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

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

## 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                  |
| `TRANSFERRED_ADDRESS_BLOCK`   | Funds received by Gate but held due to risk; not credited                                       |

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

| 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                                                                           |
| `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 | Related 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:

| Field            | Type   | Description                                                                |
| ---------------- | ------ | -------------------------------------------------------------------------- |
| `totalFee`       | string | Order amount                                                               |
| `payCurrency`    | string | Payment currency                                                           |
| `payAmount`      | string | Required payment amount                                                    |
| `rate`           | string | Exchange rate                                                              |
| `transferAmount` | string | Amount transferred to merchant; often empty in status-change notifications |
| `overPay`        | string | Amount paid above the order requirement; non-zero only on payment success  |

## data Fields (`bizType=TRANSFER_ADDRESS`)

| 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                                   |
| `orderAmount`        | string | Order amount                                     |
| `payerId`            | int64  | Payer UID                                        |
| `createTime`         | int64  | Order creation time (milliseconds)               |
| `transactionId`      | string | Transaction ID                                   |
| `transferAmount`     | string | Amount transferred to merchant (credited amount) |
| `channelId`          | string | Channel identifier                               |
| `chain`              | string | Blockchain network                               |
| `address`            | string | Collection address                               |
| `txHash` / `tx_hash` | string | On-chain transaction hash (parse compatibly)     |

## Callback Examples

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

```json theme={null}
{
  "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)

```json theme={null}
{
  "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`)

```json theme={null}
{
  "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\"}"
}
```


## OpenAPI

````yaml /api-reference/version/100/en/openapi/address-payment-callback-openapi.json webhook addressPaymentWebhook
openapi: 3.1.0
info:
  title: GatePay Address Payment Callback API
  version: 1.0.0
  description: >-
    Callbacks for address payment order status changes and fund transfers.
    GatePay sends asynchronous POST notifications to the merchant-configured
    callback URL; `data` is a JSON string. Verify the signature before
    processing.
servers:
  - url: https://openplatform.gateapi.io
    description: Production
security: []
paths: {}

````