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

# Gate Payment Status Notification

> Applies to orders placed through hosted checkout, client launch, and similar flows where the user pays with a Gate payment account. `bizType` is always `PAY`.

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). You may also call `/v1/pay/order/query` to reconcile order status.

## Overview

This page documents `webhook gatePaymentWebhook`. 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 Gate payment order status changes (`bizType` is `PAY`).

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

* When the order status changes (payment success, payment timeout, cancellation, closure, and similar events), GatePay sends a notification to the **callback URL** configured at merchant registration
* If delivery fails, see retry rules in [Notifications Overview](/api-reference/version/100/en/common/asyncNotification).

**Scope**: Orders placed through hosted checkout, web or in-app launch, and similar flows where the user pays with a **Gate payment account** (`bizType` is `PAY`). See [Payments](/essentials/version/100/en/inflow/payment/payment) for integration guidance.

## Message Structure

| Field       | Type   | Description                                                                                        |
| ----------- | ------ | -------------------------------------------------------------------------------------------------- |
| `bizType`   | string | Always `PAY`                                                                                       |
| `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

```json theme={null}
{
  "bizType": "PAY",
  "bizId": "79553572569350157",
  "bizStatus": "PAY_SUCCESS",
  "data": "{\"channelId\":\"\",\"createTime\":1780037371613,\"currency\":\"USDT\",\"doneAmountOnChain\":\"0\",\"goodsName\":\"KM/ORDER-63FDE37F - PUBG Mobile UC Global ( Special Offer ) - PUBG 1800 UC x 1\",\"merchantTradeNo\":\"6a1936fb6ac6f72b7a817576\",\"orderAmount\":\"21.88\",\"payerId\":16839589,\"productName\":\"KM/ORDER-63FDE37F - PUBG Mobile UC Global ( Special Offer ) - PUBG 1800 UC x 1\",\"productType\":\"\",\"terminalType\":\"WEB\",\"tradeType\":\"WEB\",\"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                                             |
| `orderAmount`       | string | Order amount (payment amount when Gate Pay succeeds)       |
| `totalFee`          | string | Order amount (may appear together with `orderAmount`)      |
| `expectCurrency`    | string | Merchant expected settlement currency                      |
| `actualCurrency`    | string | Actual settlement currency                                 |
| `actualAmount`      | string | Amount in `actualCurrency`                                 |
| `payerId`           | int64  | Payer UID                                                  |
| `createTime`        | int64  | Order creation time (milliseconds)                         |
| `transactionId`     | string | Platform transaction ID (may be omitted in some callbacks) |
| `channelId`         | string | Customer name / channel identifier                         |
| `doneAmountOnChain` | string | On-chain confirmed amount                                  |
| `waitAmountOnChain` | string | On-chain amount awaiting confirmation                      |

## Callback Example

### Payment success (`bizStatus=PAY_SUCCESS`)

```json theme={null}
{
  "bizType": "PAY",
  "bizId": "79553572569350157",
  "bizStatus": "PAY_SUCCESS",
  "data": "{\"channelId\":\"\",\"createTime\":1780037371613,\"currency\":\"USDT\",\"doneAmountOnChain\":\"0\",\"goodsName\":\"KM/ORDER-63FDE37F - PUBG Mobile UC Global ( Special Offer ) - PUBG 1800 UC x 1\",\"merchantTradeNo\":\"6a1936fb6ac6f72b7a817576\",\"orderAmount\":\"21.88\",\"payerId\":16839589,\"productName\":\"KM/ORDER-63FDE37F - PUBG Mobile UC Global ( Special Offer ) - PUBG 1800 UC x 1\",\"productType\":\"\",\"terminalType\":\"WEB\",\"tradeType\":\"WEB\",\"waitAmountOnChain\":\"0\"}"
}
```

### Order closed (`bizStatus=PAY_CLOSE`)

```json theme={null}
{
  "bizType": "PAY",
  "bizId": "79553572569350157",
  "bizStatus": "PAY_CLOSE",
  "data": "{\"channelId\":\"\",\"createTime\":1780037371613,\"currency\":\"USDT\",\"doneAmountOnChain\":\"0\",\"goodsName\":\"KM/ORDER-63FDE37F\",\"merchantTradeNo\":\"6a1936fb6ac6f72b7a817576\",\"orderAmount\":\"21.88\",\"payerId\":0,\"productName\":\"KM/ORDER-63FDE37F\",\"productType\":\"\",\"terminalType\":\"WEB\",\"tradeType\":\"WEB\",\"waitAmountOnChain\":\"0\"}"
}
```

### Payment error (`bizStatus=PAY_ERROR`)

```json theme={null}
{
  "bizType": "PAY",
  "bizId": "79553572569350157",
  "bizStatus": "PAY_ERROR",
  "data": "{\"channelId\":\"\",\"createTime\":1780037371613,\"currency\":\"USDT\",\"doneAmountOnChain\":\"0\",\"goodsName\":\"KM/ORDER-63FDE37F\",\"merchantTradeNo\":\"6a1936fb6ac6f72b7a817576\",\"orderAmount\":\"21.88\",\"payerId\":16839589,\"productName\":\"KM/ORDER-63FDE37F\",\"productType\":\"\",\"terminalType\":\"WEB\",\"tradeType\":\"WEB\",\"waitAmountOnChain\":\"0\"}"
}
```


## OpenAPI

````yaml /api-reference/version/100/en/openapi/gate-payment-callback-openapi.json webhook gatePaymentWebhook
openapi: 3.1.0
info:
  title: GatePay Gate Payment Callback API
  version: 1.0.0
  description: >-
    Asynchronous notifications for Gate payment orders (hosted checkout, in-app
    launch, and other flows paid through a Gate payment account). When the
    prepaid order status changes, GatePay sends a notification to the merchant
    callback URL; `data` is a JSON string.
servers:
  - url: https://openplatform.gateapi.io
    description: Production
security: []
paths: {}

````