Skip to content

Payment Result Callback ​

This API must be called on the server side. Never call it directly from the frontend (APP client, web page, mini game, etc.) to avoid the risk of credential leakage.

API Description ​

API English name pay.notify

Description Once the payment result is final (payment succeeded, or failed and closed), the APP server calls this API to sync the payment result to SUD.

Note: This API requires secondary encryption and signing of server-to-server communication: request parameters must be encrypted and signed, and responses must be signature-verified and decrypted. This effectively prevents data tampering and leakage.

Call Method ​

HTTPS Call ​

http
POST /v1/pay/notify?access_token=ACCESS_TOKEN

Prepend the base URL for your application's service region to the API path. See Service Regions and API Addresses.

Request Parameters - Query ​

FieldTypeDefaultRequiredDescription
access_tokenstringYesAPI call credential

Request Parameters - Body ​

FieldTypeDefaultRequiredDescription
envnumberYesEnvironment configuration 0-production environment, 1-test environment
game_idstringYesGame id
user_idstringYesUser id placing the order
sud_trade_nostringYesSUD business order number
product_idstringYesProduct id
product_namestringYesProduct name
quantitynumberYesPurchase quantity
unit_pricenumberYesProduct unit price (cents)
currencystringYesCurrency: CNY
statusstringYesStatus, enum: PAID-payment succeeded, CLOSED-closed. Only terminal states need to be reported; the in-progress state (PAYING) does not. This API only syncs payment stage status; for refund status use pay.refundNotify
pay_typenumberNoPayment method: 1-WeChat Pay, 2-Alipay, 3-Apple Pay
transaction_idstringNoThird-party payment transaction number (WeChat/Alipay etc. serial number)
attachstringNoPass-through data

Return Value ​

The returned JSON data packet

FieldTypeDescription
errcodeint32Error code
errmsgstringError message

Call Example ​

Note: The request example below shows the business data before encryption; what is actually sent is the ciphertext with signature headers, and the response example shows the business data after signature verification and decryption. See Server API Signature and Encryption for the packaging and signing rules.

Request Data Example ​

json
{
  "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"
}

Response Data Example ​

json
{
  "errcode": 0,
  "errmsg": "ok"
}