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
POST /v1/pay/notify?access_token=ACCESS_TOKENPrepend the base URL for your application's service region to the API path. See Service Regions and API Addresses.
Request Parameters - Query
| Field | Type | Default | Required | Description |
|---|---|---|---|---|
| access_token | string | Yes | API call credential |
Request Parameters - Body
| Field | Type | Default | Required | Description |
|---|---|---|---|---|
| env | number | Yes | Environment configuration 0-production environment, 1-test environment | |
| game_id | string | Yes | Game id | |
| user_id | string | Yes | User id placing the order | |
| sud_trade_no | string | Yes | SUD business order number | |
| product_id | string | Yes | Product id | |
| product_name | string | Yes | Product name | |
| quantity | number | Yes | Purchase quantity | |
| unit_price | number | Yes | Product unit price (cents) | |
| currency | string | Yes | Currency: CNY | |
| status | string | Yes | Status, 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_type | number | No | Payment method: 1-WeChat Pay, 2-Alipay, 3-Apple Pay | |
| transaction_id | string | No | Third-party payment transaction number (WeChat/Alipay etc. serial number) | |
| attach | string | No | Pass-through data |
Return Value
The returned JSON data packet
| Field | Type | Description |
|---|---|---|
| errcode | int32 | Error code |
| errmsg | string | Error 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
{
"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
{
"errcode": 0,
"errmsg": "ok"
}