Unresolved Payment Notification

{
  "bizType": "PAY_UNRESOLVED",
  "bizId": "100916",
  "bizStatus": "UNRESOLVED_PENDING",
  "data": {
    "accountId": 10002,
    "exceptionId": "123",
    "orderType": "acquiring_type",
    "errorType": "address_risk_address",
    "originalOrderId": "355450733498011648",
    "originalMerchantTradeNo": "M202603120001",
    "expectedAmount": "10.0",
    "expectedChainCurrency": [
      {
        "chain": "TRX",
        "currencies": [
          "USDT"
        ]
      }
    ],
    "actualAmount": "1.0",
    "actualCurrency": "USDT",
    "actualChain": "TRX",
    "customerName": "",
    "toAddress": "TExampleAddressxxxxxxxxxxxxxxxxxx",
    "fromAddress": "TFromAddressxxxxxxxxxxxxxxxxxxxx",
    "hash": "0xabc",
    "updateTime": 1740000000000
  }
}

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

WEBHOOK

unresolvedPayWebhook

{
  "bizType": "PAY_UNRESOLVED",
  "bizId": "100916",
  "bizStatus": "UNRESOLVED_PENDING",
  "data": {
    "accountId": 10002,
    "exceptionId": "123",
    "orderType": "acquiring_type",
    "errorType": "address_risk_address",
    "originalOrderId": "355450733498011648",
    "originalMerchantTradeNo": "M202603120001",
    "expectedAmount": "10.0",
    "expectedChainCurrency": [
      {
        "chain": "TRX",
        "currencies": [
          "USDT"
        ]
      }
    ],
    "actualAmount": "1.0",
    "actualCurrency": "USDT",
    "actualChain": "TRX",
    "customerName": "",
    "toAddress": "TExampleAddressxxxxxxxxxxxxxxxxxx",
    "fromAddress": "TFromAddressxxxxxxxxxxxxxxxxxxxx",
    "hash": "0xabc",
    "updateTime": 1740000000000
  }
}

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

Overview

This page documents webhook unresolvedPayWebhook. The full schema, parameters, and examples are rendered from the linked OpenAPI or webhook definition above.

Notes

This page describes a callback payload sent by GatePay, not a merchant-initiated request.
Verify the signature first, then apply idempotent processing before updating business state.
For callback guidance organized by business flow, read this page together with the Notification guide.
For shared signing rules, see /api-reference/version/100/en/common/securityAndSignature.

Message Structure

Field	Type	Description
`bizType`	string	Always `PAY_UNRESOLVED`
`bizId`	string	Business ID
`bizStatus`	string	Business status, e.g. `UNRESOLVED_PENDING`
`data`	object	Unresolved payment details object

data Field Reference

Field	Type	Description
`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.
`exceptionId`	string	Unresolved payment ID
`orderType`	string	Order type: `acquiring_type` (acquiring); `payee_type` (payee QR code)
`errorType`	string	Error reason code
`originalOrderId`	string	Original Gate Pay order ID (empty for payee QR scenarios)
`originalMerchantTradeNo`	string	Associated original merchant order number (empty for payee QR scenarios)
`expectedAmount`	string	Expected order amount (empty for payee QR scenarios)
`expectedChainCurrency`	array	Expected chain and currencies
`actualAmount`	string	Actual order amount
`actualCurrency`	string	Actual order currency
`actualChain`	string	Actual blockchain network
`customerName`	string	Customer name (empty for acquiring scenarios)
`toAddress`	string	Recipient address
`fromAddress`	string	Sender address
`hash`	string	Transaction hash
`updateTime`	int64	Event timestamp in milliseconds

Callback Example

{
  "bizType": "PAY_UNRESOLVED",
  "bizId": "100916",
  "bizStatus": "UNRESOLVED_PENDING",
  "data": {
    "accountId": 10002,
    "exceptionId": "100916",
    "orderType": "payee_type",
    "errorType": "fix_error_currency",
    "originalOrderId": "",
    "originalMerchantTradeNo": "",
    "expectedAmount": "",
    "expectedChainCurrency": [
      {
        "chain": "MATIC",
        "currencies": ["USDT"]
      }
    ],
    "actualAmount": "0.12",
    "actualCurrency": "USDC",
    "actualChain": "ARBEVM",
    "customerName": "channelId2293698068",
    "toAddress": "0x49D24D32b9ed2fc9e7AEd8a08976615988db4f6A",
    "fromAddress": "0x144Ff55c1a8C80C893b6272a87C228fc601E4de4",
    "hash": "0x76a445961ae0e6fea1197a73b59494ec4939f178639ae0683f6949a57f47fbc0",
    "updateTime": 1780036391365
  }
}

Body

application/json

Unresolved payment webhook payload

bizType

enum<string>

Business type; always PAY_UNRESOLVED.

Available options:

PAY_UNRESOLVED

bizId

string

Business ID (e.g. identifier linked to the exception; actual payload may vary).

bizStatus

enum<string>

Business status, e.g. UNRESOLVED_PENDING (pending; actual payload may vary).

Available options:

UNRESOLVED_PENDING

data

object

Unresolved payment details. Some fields may be empty depending on acquiring vs payee QR scenarios; see each field description.

Show child attributes

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

Result code; SUCCESS means success.

returnMessage

string | null

Message; may be empty on success.

⌘I

Common

Balance

Institution

Payment

OTC

Convert

Payout

Gift Card

Subscription

Reconciliation

Notifications

Unresolved Payment Notification

Overview

Notes

Message Structure

data Field Reference

Callback Example

Body

Response

​Overview

​Notes

​Message Structure

​data Field Reference

​Callback Example

Body

Response

Overview

Notes

Message Structure

data Field Reference

Callback Example