Skip to content

Query Order Status ​

This is a callback API implemented by the APP server and provided to SUD to call. SUD queries the order status of the APP server through this API.

API Description ​

API English name pay.orderQuery

Description Query order status. SUD OP SVR queries the payment status and details of a specified order from the APP server through this callback API.

Note: This API requires secondary encryption and signing of server-to-server communication: the callback request must be signature-verified before any business logic runs. This effectively prevents data tampering and leakage.

Call Method ​

HTTPS Call ​

http
POST <APP custom callback URL>

Request Parameters - Body ​

FieldTypeDefaultRequiredDescription
sud_trade_nostringYesSUD business order number

Return Value ​

The returned JSON data packet

FieldTypeDescription
errcodeint32Error code
errmsgstringError message
envnumberEnvironment configuration 0-production environment, 1-test environment
game_idstringGame id
user_idstringUser id placing the order
sud_trade_nostringSUD business order number
product_idstringProduct id
product_namestringProduct name
quantitynumberPurchase quantity
unit_pricenumberProduct unit price (cents)
currencystringCurrency: CNY
statusstringStatus, enum: PAYING-paying, PAID-payment succeeded, CLOSED-closed, REFUND-transferred to refund. Returns the order's current overall status, which may fall in either the payment or refund stage
pay_typenumberPayment method: 1-WeChat Pay, 2-Alipay, 3-Apple Pay
transaction_idstringThird-party payment transaction number (WeChat/Alipay etc. serial number)
attachstringPass-through data

Call Example ​

Note: The request example below shows the business data after decryption; what actually arrives is ciphertext with signature headers, which must be verified and decrypted before parsing. The response example shows the business data before encryption; the actual response must be encrypted first and the ciphertext then signed. See Callback Signature and Encryption for the full rules.

Request Data Example ​

json
{
  "sud_trade_no": "sud_20231024123456"
}

Response Data Example ​

json
{
  "errcode": 0,
  "errmsg": "ok",
  "env": 0,
  "game_id": "game_1001",
  "user_id": "user_293847",
  "sud_trade_no": "sud_20231024123456",
  "product_id": "item_001",
  "product_name": "100 Coins",
  "quantity": 1,
  "unit_price": 600,
  "currency": "CNY",
  "status": "PAID",
  "pay_type": 1,
  "transaction_id": "420000123420231024567890",
  "attach": "custom_passthrough_data"
}

Polling Policy ​

SUD OP SVR polls this API at the following intervals after the order is created, as a fallback for obtaining the payment result:

ItemRequirement
Polling intervals (seconds)5, 30, 60, 180, 300, 600, 1800
Stop conditionStop polling once PAID, CLOSED, or REFUND (order moved to refund) is returned
Query methodPOST request carrying only sud_trade_no; read-only, side-effect free, and safe to repeat

Notes for the APP SVR:

  1. This API is a read-only query. Repeated calls with the same sud_trade_no must return consistent results and must not trigger delivery, charging, or any other business action.
  2. Once a terminal state (PAID, CLOSED, REFUND) has been returned, subsequent queries must keep returning that same terminal state and must not fall back to PAYING; otherwise SUD OP's polling and order-closing decisions are delayed.
  3. If the user has opened the checkout page but has not finished paying, return PAYING; do not return an empty response or an error code.