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
When order status changes, GatePay sends an asynchronous notification to the merchant callback URL. Typical events include payment success, timeout, and order cancellation.
For the current-version callback guide with business-specific breakdowns, refer first to Notification. This page is retained as the API Reference notification overview.
Retry mechanism
GatePay retries failed notifications at: 15s, 30s, 3min, 10min, 20min, 30min, 60min, 3hr, 6hr.
Signature verification
You must verify the signature for every callback you receive.
Message structure
| Field | Description |
|---|
| bizType | Business type |
| bizId | Business ID |
| bizStatus | Business status |
| client_id | Application ClientId |
| data | Business data in JSON format |
Message JSON example
{
"bizType": "PAY",
"bizId": "order_123456",
"bizStatus": "PAY_SUCCESS",
"client_id": "your_client_id",
"data": "{...}"
}
bizType enum
| bizType | Description |
|---|
| PAY | Payment |
| PAY_REFUND | Payment refund |
| PAY_BATCH | Batch payment |
| TRANSFER_ADDRESS | Address transfer |
| PAY_GIFT_BATCH | Gift batch payment |
| WITHDRAW | Withdrawal |
| PAY_ADDRESS | Address payment |
| PAY_FIXED_ADDRESS | Fixed address payment |
bizStatus enum
| bizStatus | Description |
|---|
| PAY_SUCCESS | Payment successful |
| PAY_ERROR | Payment failed |
| PAY_CLOSE | Payment closed |
| PAY_BLOCK | Payment blocked |
| REFUND_SUCCESS | Refund successful |
| REFUND_PROCESS | Refund in process |
| REFUND_REJECTED | Refund rejected |
| PAY_EXPIRED_IN_PROCESS | Payment expired while processing |
| TRANSFERRED_ADDRESS_IN_TERM | Address transferred within term |
| TRANSFERRED_ADDRESS_DELAY | Address transfer delayed |
| CONVERT_ADDRESS_PAY_DELAY | Converted address payment delayed |
| TRANSFERRED_ADDRESS_BLOCK | Address transfer blocked |
| PAID | Paid |
Data structure by bizType
PAY and TRANSFER_ADDRESS fields
| Field | Type | Description |
|---|
| merchantTradeNo | string | Merchant order number |
| orderId | string | GatePay order ID |
| amount | string | Payment amount |
| currency | string | Currency type |
| status | string | Order status |
| payTime | string | Payment completion time |
| remark | string | Remark |
refundInfo type
| Field | Type | Description |
|---|
| refundId | string | Refund ID |
| refundRequestId | string | Merchant refund request ID |
| refundAmount | string | Refund amount |
| refundCurrency | string | Refund currency |
| refundStatus | string | Refund status |
| refundTime | string | Refund completion time |
batchItemList type
| Field | Type | Description |
|---|
| itemId | string | Item ID |
| amount | string | Amount |
| currency | string | Currency |
| status | string | Item status |
Callback JSON examples
PAY callback (payment success)
{
"bizType": "PAY",
"bizId": "pay_order_001",
"bizStatus": "PAY_SUCCESS",
"client_id": "client_123",
"data": "{\"merchantTradeNo\":\"M001\",\"orderId\":\"G001\",\"amount\":\"100.00\",\"currency\":\"USDT\",\"status\":\"PAID\",\"payTime\":\"1673613945000\"}"
}
PAY_REFUND callback (refund success)
{
"bizType": "PAY_REFUND",
"bizId": "refund_001",
"bizStatus": "REFUND_SUCCESS",
"client_id": "client_123",
"data": "{\"merchantTradeNo\":\"M001\",\"refundId\":\"R001\",\"refundRequestId\":\"RR001\",\"refundAmount\":\"50.00\",\"refundStatus\":\"SUCCESS\",\"refundTime\":\"1673614000000\"}"
}
TRANSFER_ADDRESS callback
{
"bizType": "TRANSFER_ADDRESS",
"bizId": "transfer_001",
"bizStatus": "TRANSFERRED_ADDRESS_IN_TERM",
"client_id": "client_123",
"data": "{\"merchantTradeNo\":\"M002\",\"orderId\":\"T001\",\"amount\":\"200.00\",\"currency\":\"USDT\",\"status\":\"TRANSFERRED\"}"
}
OTC-specific callback notes
For this OTC document set, callback notifications may include OTC business payloads routed through the merchant callback URL.
Common OTC callback states include:
| bizStatus | Description |
|---|
RECHARGE_SUCCESS | OTC on-ramp succeeded |
RECHARGE_FAIL | OTC on-ramp failed |
WITHDRAW_DISPATCHED | OTC off-ramp payout has been dispatched |
WITHDRAW_SUCCESS | OTC off-ramp completed successfully |
WITHDRAW_FAIL | OTC off-ramp failed |
{
"bizType": "OTC",
"bizId": "2016768770965639168",
"bizStatus": "WITHDRAW_DISPATCHED",
"clientId": "merchant_client_id",
"data": "{\"orderId\":\"2016768770965639168\",\"clientOrderId\":\"7490324045\",\"type\":\"SELL\",\"fiatCurrency\":\"USD\",\"fiatAmount\":\"9800\",\"cryptoCurrency\":\"USDT\",\"cryptoAmount\":\"10000\"}"
}
