tencent cloud

Tencent Cloud Super App as a Service

API List

Download
Focus Mode
Font Size
Last updated: 2026-10-21 11:42:14

API list

Common instructions

Common request headers

The following request headers are common parameters for Super App as a Service (SAS) calling superapp services, and are not listed repeatedly in the request parameters of each API:
Parameter
Required
Type
Description
Example value
TC-ApplicationID
Yes
string
The superapp ID on SAS.
app-abo181jy4f
TC-BackendConfigID
Yes
string
Backend configuration ID of the SAS accessing the superapp, used to distinguish environments.
appserver-1
TC-PackageName
Yes
string
The superapp package name on SAS.
com.tencent.demo
TC-Signature
Yes
string
The request signature of the SAS. It is calculated and generated based on TC-Timestamp. For details, seeSuper App as a Service Signature and Verification.
8ce14c68e234e1581fee873c478897c7
TC-Timestamp
Yes
string
Timestamp (in milliseconds).
1787375938382
TC-TraceID
Yes
string
Trace ID for distributed tracing.
eae6bf0943eb463d9120ac0d54366e4b]
Note:
For requests from the SAS to the superapp, the TC-Timestamp in the request header is in milliseconds. This aligns with our customers' standards, as our current customers exclusively use milliseconds.
Conversely, for callback requests from the superapp to the SAS, the TC-Timestamp is in seconds. This is to ensure compatibility for scenarios migrating from WeChat mini programs. This parameter is passed through to the Pay-Timestamp on the mini program side, thus adhering to WeChat's standard. However, the SAS signature verification also supports milliseconds. If the superapp chooses to use milliseconds, the mini program side must be updated accordingly.

1. Mini program login APIs

1.1 Check whether the user exists

Path: /user/checkUser
Method: POST
API description:
This API is used to check whether a user exists based on the superapp user ID.

Request parameters

Header parameters:
Parameter
Required
Type
Description
Example value
TC-OpenId
Yes
string
The unique identifier of the user within the mini-program. The value must be encrypted using AES-ECB mode and then hex-encoded. Encryption key is the SecretKey in Configuration Management .
8d45e4881656d8fb4f97a442423093a5db9ec5691f6e8b17f895ab0fd935c0e7
TC-MiniAppID
Yes
string
The unique identifier of the mini-program within the superapp. The value must be encrypted using AES-ECB mode and then hex-encoded. Encryption key is the SecretKey in Configuration Management .
8dc9708f26a1f5157e66c27892c78a88440d324a986a67fa7acb4d29511c7d18
Body parameters:
Parameter
Required
Type
Description
Example value
userId
Yes
string
Anonymized user ID, set by the superapp via the SDK as the unique identifier of the logged-in user.
test_user_id_001

Response parameters

Parameter
Required
Type
Description
Example value
returnCode
Yes
string
Response code, 0 indicates success.
0
returnMessage
No
string
Response information.
OK
Data
Yes
Boolean
Indicates whether the user exists.
true
requestId
Yes
string
Request trace ID.
fd203616014e4ca8935f08a913ecfcb4

Request example

{"userId":"test_user_id_001"}

Response example

{"returnCode":"0","returnMessage":"OK","requestId":"fd203616014e4ca8935f08a913ecfcb4","data":true}

1.2 Get temporary code of user information

Path: /user/getUserInfoTemporaryCode
Method: POST
API description:
This API is used to get a temporary credential for the user's mobile number or email based on the type.

Request parameters

Body parameters:
Parameter
Required
Type
Description
Example value
type
Yes
string
The type of information. Valid values: email, phone.
phone
userId
Yes
string
Anonymized user ID, set by the superapp via the SDK as the unique identifier of the logged-in user.
test_user_id_001

Response parameters

Parameter
Required
Type
Description
Example value
returnCode
Yes
string
Response code, 0 indicates success.
0
returnMessage
No
string
Response information.
OK
data
Yes
object
Response data.
-
data.data
Yes
string
Masked phone number or email returned based on the query type. For example: 158****82850
158****82850/mur****g@tencent.com
data.code
Yes
string
Temporary credential code got for the phone number or email.
d3fc1f12b00b439491082a5fad20c45f
requestId
Yes
string
Request trace ID.
fd203616014e4ca8935f08a913ecfcb4

Request example

{"userId":"test_user_id_001","type":"phone"}

Response example

{"returnCode":"0","returnMessage":"OK","requestId":"be25983db858414e9eac988ad3e07531","data":{"code":"6b8e77d997c146328cb7b5b7251581f6","data":"158****2850"}}

1.3 Get user email

Path: /user/getUserEmail
Method: POST
API description:
This API is used to get the user's email based on the temporary credential code.

Request parameters

Body parameters:
Parameter
Required
Type
Description
Example value
temporaryCode
Yes
string
Temporary credential code.
5ee7263392e441f782ec1bba85e88fbe
userId
Yes
string
Anonymized user ID, set by the superapp via the SDK as the unique identifier of the logged-in user.
test_user_id_001

Response parameters

Parameter
Required
Type
Description
Example value
returnCode
Yes
string
Response code, 0 indicates success.
0
returnMessage
No
string
Response information.
OK
data
Yes
string
User email information, a Base64 string after being encrypted using AES CBC (using the first 16 bytes of the key as the IV). The secret key is referenced in the Configuration Management .
4bhhBZj4WpfhVc0U66AAbrZi5vIajBZ7abBH96xgric
requestId
Yes
string
Request trace ID.
fd203616014e4ca8935f08a913ecfcb4

Request example

{"temporaryCode":"5ee7263392e441f782ec1bba85e88fbe","userId":"test_user_id_001"}

Response example

{"returnCode":"0","returnMessage":"OK","requestId":"aa12162189324f789796a738ddf1eb0f","data":"4bhhBZj4WpfhVc0U66AAbrZi5vIajBZ7abBH96xgric="}

1.4 Get user’s mobile number

Path: /user/getUserPhoneNumber
Method: POST
API description:
This API is used to get the user's mobile number based on the temporary credential code.

Request parameters

Body parameters:
Parameter
Required
Type
Description
Example value
temporaryCode
Yes
string
Temporary credential code.
5ee7263392e441f782ec1bba85e88fbe
userId
Yes
string
Anonymized user ID, set by the superapp via the SDK as the unique identifier of the logged-in user.
test_user_id_001

Response parameters

Parameter
Required
Type
Description
Example value
returnCode
Yes
string
Response code, 0 indicates success.
0
returnMessage
No
string
Response information.
OK
data
Yes
string
The Base64-encoded ciphertext of the user's phone number object. The plaintext is a JSON string, encrypted with AES-CBC (the first 16 bytes of the key are used as the IV). The encryption key is the SecretKey inConfiguration Management .
EOc8Hi03A4y60YkmUMNqtQ
requestId
Yes
string
Request trace ID.
fd203616014e4ca8935f08a913ecfcb4
Phone number object:
Parameter
Required
Type
Description
Example value
countryCode
Yes
string
The country or region calling code, in digits only, without the plus sign (+). 1 to 3 characters.
86
purePhoneNumber
Yes
string
The phone number with the country or region calling code removed, in digits only. 4 to 15 characters.
13820080808
phoneNumber
Yes
string
The formatted phone number for display, including the calling code and separators. You can display this value directly in mini programs or front-end pages. 4 to 40 characters in total, of which 4 to 15 are digits.
+86 138 2008 0808



Request example

{"temporaryCode":"26707436c5324e79997d66698231fe4d","userId":"test_user_id_001"}

Response example

{"returnCode":"0","returnMessage":"OK","requestId":"adadc87a140f40a2b1657a1eb996d550","data":"EOc8Hi03A4y60YkmUMNqtQ=="}

1.5 Get user’s nickname

Path: /user/getUserNick
Method: POST
API description:
This API is used to get the user's nickname.

Request parameters

Body parameters:
Parameter
Required
Type
Description
Example value
userId
Yes
string
Anonymized user ID, set by the superapp via the SDK as the unique identifier of the logged-in user.
test_user_id_001

Response parameters

Parameter
Required
Type
Description
Example value
returnCode
Yes
string
Response code, 0 indicates success.
0
returnMessage
No
string
Response information.
OK
data
Yes
string
User’s nickname.
test nick
requestId
Yes
string
Request trace ID.
fd203616014e4ca8935f08a913ecfcb4

Request example

{"userId":"test_user_id_001"}

Response example

{"returnCode":"0","returnMessage":"OK","requestId":"a58ffe1dc53f461fa3c5fb109781631a","data":"test nick"}

1.6 Get user’s profile photo

Path: /user/getUserAvatar
Method: POST
API description:
This API is used to get the user profile photo.

Request parameters

Body parameters:
Parameter
Required
Type
Description
Example value
userId
Yes
string
Anonymized user ID, set by the superapp via the SDK as the unique identifier of the logged-in user.
test_user_id_001

Response parameters

Parameter
Required
Type
Description
Example value
returnCode
Yes
string
Response code, 0 indicates success.
0
returnMessage
No
string
Response information.
OK
data
Yes
string
URL of the user’s profile photo.
requestId
Yes
string
Request trace ID.
fd203616014e4ca8935f08a913ecfcb4

Request example

{"userId":"test_user_id_001"}

Response example

{"returnCode":"0","returnMessage":"OK","requestId":"8c7ff430d4de419ca2b0e90b3260c5b3","data":"https://example-test.com/image/avatar/test_user.jpg"}

1.7 Receive subscription messages

Path: /message/send
Method: POST
API description:
This API is used to receive user-subscribed messages pushed from Super App as a Service (SAS).

Request parameters

Body parameters:
Parameter
Required
Type
Description
Example value
accountId
Yes
string
The ID of the user to whom the message belongs (same as userId).
test_user_id_001
messageId
Yes
string
The unique ID of the message.
a75a19fc0aa64e4171f8e856e0b16927
content
Yes
string
Message content.
Pay time:2026-07-16 15:04:00
dataTime
Yes
int
Timestamp of the message sending time (in seconds).
1784189857
templateId
Yes
string
The ID of the message template.
mti_test_template_001
mnpId
Yes
string
Mini program appid.
mp_test_001
mnpName
Yes
string
Mini program name.
Daily Coffee
templateTitle
Yes
string
Template title.
Order Notify
state
Yes
string
The type of mini program to navigate to: developer for the development version, trial for the Preview, formal for the official version. Defaults to the official version.
formal
page
No
string
The page to navigate to after the user taps the message card. It must be a page within the current mini program and supports parameters (for example, index?foo=bar). If not provided, the template will not have a navigation link.
index?foo=bar
mnpIcon
Yes
string
Mini program icon.
https://example-test.com/image/icon/coffee.png

Response parameters

Parameter
Required
Type
Description
Example value
returnCode
Yes
string
Response code, 0 indicates success.
0
returnMessage
No
string
Response information.
OK
data
Yes
Boolean
Processing result.
true
requestId
Yes
string
Request trace ID.
fd203616014e4ca8935f08a913ecfcb4

Request example

{"messageId":"a75a19fc0aa64e4171f8e856e0b16927","accountId":"test_user_id_001","templateId":"mti_test_template_001","content":"Remarks:Membership upgrade offers 30% off\\nTravel date:2026-08-08 11:00:00\\nService content:Upgrade Reminder","dataTime":1784189857,"mnpId":"mp_test_001","mnpName":"Daily Coffee","mnpIcon":"https://example-test.com/image/icon/coffee.png","templateTitle":"Order Notify","state":"formal","page":""}

Response example

{"returnCode":"0","returnMessage":"OK","requestId":"98524a23d9ff4ed8b5e41cfec22b5ad8","data":true}

2. Mini program payment APIs

2.1 Create a mini program order

Path: /v3/pay/transactions/jsapi
Method: POST
API description:
This API is used to create a mini program order.

Request parameters

Header parameters:
Parameter
Required
Type
Description
Example value
TC-Payment-Callback
Yes
string
The callback URL of a successful or failed payment.
https://example.com/callback
TC-MerchantID
Yes
string
The merchant ID bound to the mini program’s superapp on SAS.
mi59a93ddccc
TC-UserID
Yes
string
Superapp user login ID.
test_user_id_001
TC-TradeType
Yes
string
Transaction type: JSAPI for mini program payments.
JSAPI
TC-Platform-UserID
Yes
string
The user openid on SAS.
oe49fc39b7eb17872cctaQq28560
TC-ApplicationID
Yes
string
The superapp ID on SAS.
app-abo181jy4f
TC-Authorization
Yes
string
The signature authentication information. For more information, see Signature and Verification.
WECHATPAY2-SHA256-RSA2048 mchid="mi59a93ddccc",nonce_str="e2f473eb9550bef157882dd1acdd63ed",signature="oT82oRCkZ5S/FxamuAiEKKKZRN/y0e+h7NMXg4a8pgvRm7Cy0QYBTI9chBphXc/iktDNNbZ36LrOHEidk13/td6Xij76tgor9FspZLB3Sx5393eL8A9bvYbCRuUeGFofJGkT1liW7JWdsPCyYF8HsgleW9cRfOolzKKhg7fGk3JH4/QxbWkGGQO9qP5FyrDnTj9K4xrslJsIbtC1eNG40xPA8p5P6zmSS6Q1ISLe/bm8QFcDJHAJUn/MTJWjHDxr00BbjMjUQl5oObkA+G6Q3DCaquYJlp8TDkEluG4Pffrd3inXl+98ZKlD6uiKufoJYk5dwU8Po2dIQjfXWQStWg==
Body parameters:
Parameter
Required
Type
Description
Example value
appid
Yes
string
Merchant's mini program appid, the unique identifier for the merchant on Super App as a Service (SAS). Ensure this mini program appid is bound to the merchant ID.
mp5ip444wt995zdp
description
Yes
string
Product information description, which should be accurately provided and cannot exceed 127 characters.
Tropical Citrus Iced Energy
out_trade_no
Yes
string
Internal order number in the merchant system, must be 6-32 characters long, can only include numbers, uppercase and lowercase letters, _-|*, and must be unique within the same merchant ID.
f49b3e588f1fec899b68
time_expire
Yes
string
The payment end time, which is the last time the user can complete the payment for this order, not the order closing time. After this time, the user will not be able to pay for the order. Format requirements: The payment end time shall follow the standard format: YYYY-MM-DDTHH:mm:ss+TIMEZONE. YYYY-MM-DD represents the date; T separates the date and time; HH:mm:ss represents the time; TIMEZONE represents the time zone (e.g., +08:00 corresponds to UTC+8).
2026-10-30T18:30:00+08:00
attach
No
string
Custom data packet provided by the merchant when creating the order, not visible to the user, used to store merchant custom information related to the order, with a total length limit of 128 characters. This field will be returned to the merchant in the order query API and payment success callback notification.
{"appid":"mp_test_001"}
amount
Yes
object
Order amount.
-
amount.total
Yes
string
Original order amount. It supports up to 12 integer digits and up to 2 decimal places. Only digits and a maximum of one decimal point are allowed. Thousand separators, currency symbols, and negative numbers are not supported. Valid examples: "0.5", "10.5", "100.55", "1000", "10000.00".
1600.00
amount.currency
Yes
string
Currency type, a three-letter code compliant with ISO 4217.
USD
payer
Yes
object
Payer information.
-
payer.openid
Yes
string
User openid on SAS.
o6bd1c45d56c17841qEDgWR88700
detail
Yes
object
Product information.
-
detail.cost_price
No
string
Original order price. It supports up to 12 integer digits and up to 2 decimal places. Only digits and a maximum of one decimal point are allowed. Thousand separators, currency symbols, and negative numbers are not supported. Valid examples: "0.5", "10.5", "100.55", "1000", "10000.00".
1600.00
detail.goods_detail
Yes
array[object]
Product list.
-
detail.goods_detail.merchant_goods_id
Yes
string
Product code provide by the merchant, composed of one or more of the following: Half-width uppercase and lowercase letters, numbers, hyphens, and underscores.
6a798208b6370b456c50fb5f
detail.goods_detail.goods_name
No
string
Actual product name.
Earl Grey Milk Tea
detail.goods_detail.quantity
Yes
int
Quantity of products purchased by the user.
1
detail.goods_detail.unit_price
Yes
string
Unit price. It supports up to 12 integer digits and up to 2 decimal places. Only digits and a maximum of one decimal point are allowed. Thousand separators, currency symbols, and negative numbers are not supported. Valid examples: "0.5", "10.5", "100.55", "1000", "10000.00".
1600.00
mchid
Yes
string
Merchant ID.
mp5ip444wt995zdp

Response parameters

Parameter
Type
Required
Description
Example value
returnCode
string
Yes
Response code, 0 indicates success.
0
returnMessage
string
No
Response information.
OK
data
object
Yes
Response data.
-
data.prepayId
string
Yes
Superapp order ID.
pip1787320103622n1mjc6qgytpith9yg9pb
requestId
string
Yes
Request trace ID.
fd203616014e4ca8935f08a913ecfcb4

Request example

{"appid":"mp_test_001","description":"Tropical Citrus Iced Energy","out_trade_no":"f49b3e588f1fec899b68","time_expire":"2035-10-30T18:30:00+07:00","attach":"{\\"appid\\":\\"mp_test_001\\"}","amount":{"total":"1600","currency":"USD"},"payer":{"openid":"o6bd1c45d56c17841qEDgWR88700"},"detail":{"cost_price":"1600","goods_detail":[{"merchant_goods_id":"1","goods_name":"Tropical Citrus Iced Energy","quantity":1,"unit_price":"1600"}]},"notify_url":"https://example-test.com/callback/pay/mp_test_001","mchid":"mi_test_merchant_001"}

Response example

{"returnCode":"0","returnMessage":"OK","requestId":"1a89d73986dd4f889bd82fdd622b8505","data":{"prepayId":"pip_test_prepay_001"}}

2.2 Mini program order payment callback

After a user successfully completes a standard payment, the superapp payment system will send an asynchronous callback notification via a POST request. This notification is sent to the specific URL provided by the merchant in the TC-Payment-Callback header during the initial /v3/pay/transactions/jsapi request. This serves to notify the merchant's backend that the payment has been successfully completed.
Path: The value of the TC-Payment-Callback header passed in the /v3/pay/transactions/jsapi request.
Method: POST
API description:
Mini program order payment callback.

Request parameters

Header parameters:
Parameter
Required
Type
Description
Example value
TC-Callback-Serial
Yes
string
The merchant serial number, and the merchant payment public key ID on the superapp's payment (Merchant serial number, merchant certificate).
7510596630
TC-Signature
Yes
string
5228b3d0b157a66568ada815a8d8eff2
TC-Timestamp
Yes
string
Timestamp (in seconds).
1787320108
TC-Callback-Nonce
Yes
string
-
vnmlsv2818mgy1jv
TC-Callback-Signature
Yes
string
For more information, see Signature and Verification.
nPzashzhDbjJ2i6+E9yGOiV0vCGoEr54mLATaom60JKOuQSEYBHoFUQuU+IfrL1NNCUqJRNDQc7C3RxyFRJvOCJSG8uyQpDW4de+EM72KEVLC8mbv92mdlFhsC/dlwhIuWIbpUdXxXHZvpSs3ZOTBPnxQqpCNcmYOUrFlU+LqrspPfBo3DdKvoQ7AZM0Wl5rfWdwgNryPDH7Gu/HpiG6qZPbDiybZCce4fxjTFZA0DHuvw0MU+nWMQYSaQIH7FI1nmNNzqHb/1O6tODV548Rvaph2km1T6/FwJP0xj5JdiPuWUZFsQtpJDMCXUgBjA/zs1tU/Si/pk7nhf/Kg2/o8Q==
TC-ApplicationID
Yes
string
TC-ApplicationID in the request header when creating an order.
app-abo181jy4f
TC-BackendConfigID
Yes
string
TC-BackendConfigID in the request header when creating an order.
appserver-1
Body parameters:
Parameter
Required
Type
Description
Example value
id
Yes
string
Unique identifier for the callback notification.
ixg0t157h5kt7pjz
create_time
Yes
string
Notification creation time. Format requirements: The payment end time shall follow the standard format: YYYY-MM-DDTHH:mm:ss+TIMEZONE. YYYY-MM-DD represents the date; T separates the date and time; HH:mm:ss represents the time; TIMEZONE represents the time zone (e.g., +08:00 corresponds to UTC+8). Example: 2015-05-20T13:29:35+08:00 represents 13:29:35 on May 20, 2015 (UTC+8).
2026-08-21T21:48:28+08:00
event_type
Yes
string
The superapp's payment callback notification types. Payment success - TRANSACTION.SUCCESS. Payment failure - TRANSACTION.PAYERROR.
TRANSACTION.SUCCESS
resource_type
Yes
string
Type of notification data, fixed as encrypt-resource.
encrypt-resource
summary
Yes
string
Summary of the callback content from the superapp's payment.
Pay success
transaction_id
No
string
Superapp payment transaction ID.
tx2026082121482836425181pu94tn0w
pay_mode
No
string
Payment method (for example, Wallet).
Wallet
out_trade_no
Yes
string
Merchant order number.
f49b3e588f1fec899b68
resource
Yes
object
Notification resource data.
-
resource.algorithm
Yes
string
Encryption algorithm type for the callback data ciphertext. It is currently AEAD_AES_256_GCM. Developers need to use the same type of data for decryption.
AEAD_AES_256_GCM
resource.ciphertext
Yes
string
Data ciphertext: The Base64-encoded callback data ciphertext. The merchant is required to decode it using Base64 and decrypt it with the APIV3 key.
dc2GfDp5+5xq8qchDN67Xfv84OBgjJ+N/X99mUo/5LdU0m8i2Ai9JFG9iIq0pIu/XLxzMjg4x3+TDJpxjwCQdDGZgO2gLlDNUFqUddP8jJGyXJ32msC3wAAwQ9bzROEi4ECJr1Y7yWnKnC372IIe0BXev7BTP6D2Iq5Trz1oNqz02Vsn8K7aW7dcX64vXoMAM/S4BBq8PRs2xxy6hCcAU+9eyiYsvvl3ZTjVw+9hVLGgS21yRrN31kwzDHsH6ALnp3Gje0ywTXxyodDilQV+XcJRDCqEq2TNIvrGmjey723cSQcarJuuA1sZSIDSKhBdOYAR/1W5LNE8tcpURqM0mLWN1yZsdMBKrw28ZSXo5f7wKLA0ScdlDJB7/7d5+NQf6x2tIFDnPirKpnIOqk7tOVgar/LQLyzxAvBOLqohzXEw4q3Dgc3wlyo4sLx8mAJtP4+744o7UW4mpQBhlSnMP92aEdHInZ1JvPYni4+XZAMyDKenjDqI5Q/ctpMhkILmBQDpxP4NBW4R82Uqm2opyYsAnNwhl/iKnqs+K19r3dy+9VDg/y/o9+MdkmQXuwMgWHuHoCFsFdZ3GJSeWYOJbfwX3d/WlOvpvs0LwGsak3k2dXhsv+v9yR1EAg8pyeQ6WLnf
resource.associated_data
No
string
Additional data for decryption, this field may be empty.
-
resource.original_type
Yes
string
Original callback type: The object type before encryption, which is transaction.
transaction
resource.nonce
Yes
string
Random string involved in decryption.
yfYEe1uRgrmC
Decrypted structure of resource.ciphertext data:
Parameter
Type
Required
Description
Example value
transaction_id
string
No
Superapp payment transaction ID.
tx2026082121482836425181pu94tn0w
mch_id
string
Yes
Merchant ID.
mi59a93ddccc
out_trade_no
string
Yes
Merchant order number.
f49b3e588f1fec899b68
appid
string
Yes
Merchant mini program appid.
mp5ip444wt995zdp
trade_state
string
Yes
The transaction status. Valid values: SUCCESS: Payment succeeded; REFUND: Refunded; NOTPAY: Unpaid; CLOSED: Closed; REVOKED: Revoked; USERPAYING: User paying; PAYERROR: Payment failed.
SUCCESS
trade_state_desc
string
Yes
Description of the transaction status.
SUCCESS
trade_type
string
Yes
Transaction type, fixed value: JSAPI.
JSAPI
bank_type
string
Yes
User’s payment method, format: bankCode_type (e.g., ICBC_DEBIT). Non-bank payments are unified as OTHERS.
Wallet
success_time
string
Yes
Payment completion time.
2026-07-16T17:44:53+08:00
payer
object
Yes
Payer information.
-
payer.openid
string
Yes
The user ID on SAS.
o6bd1c45d56c17841qEDgWR88700
attach
string
No
Pass-through data provided during order placement.
{"appid":"mp_test_001"}
amount
object
Yes
Order amount information. See table below.
-
amount:
Parameter
Type
Required
Description
Example value
total
string
Yes
Total order amount.
1600.00
payer_total
string
Yes
Amount paid by the user.
1600.00
currency
string
Yes
Currency.
USD
payer_currency
string
Yes
The currency used by the user for the payment.
USD

Response parameters

Parameter
Type
Required
Description
Example value
returnCode
string
Yes
Response code, 0 indicates success.
0
returnMessage
string
No
Response information.
OK
data
Boolean
Yes
Indicates whether the merchant notification was successful.
true
requestId
string
Yes
Request trace ID.
fd203616014e4ca8935f08a913ecfcb4

Request example

{"id":"notify_001","create_time":"2026-07-16T17:44:53+08:00","resource_type":"encrypt-resource","event_type":"TRANSACTION.SUCCESS","transaction_id":"tx_test_001","summary":"Pay success","pay_mode":"Wallet","out_trade_no":"f49b3e588f1fec899b68","resource":{"original_type":"transaction","algorithm":"AEAD_AES_256_GCM","ciphertext":"encrypted_data_base64...","associated_data":"","nonce":"random_nonce_001"}}

Response example

{"returnCode":"0","returnMessage":"success","requestId":"f071f8025c63482db14500b23c536577","data":"ok"}

2.3 Queries orders by the order number

Path: /v3/pay/transactions/out-trade-no/{out_trade_no}
Method: GET
API description:
This API is used to query orders by the merchant order number.

Request parameters

Header parameters:
Parameter
Required
Type
Description
Example value
TC-Authorization
Yes
string
The signature authentication information. For more information, see Signature and Verification.
WECHATPAY2-SHA256-RSA2048 mchid="mi59a93ddccc",nonce_str="a60b588603",signature="D2euMbDqrigI2NwP+uADgyjyH8by4hi1Y0ze9vNBMIJs6jy98ktvXg7j7F/fyAvEM63iVTE7WRHAZ4T9n3vGaCcAakYGljL503wO4gHIYudqAeZnv/DenJjEDJysV50jeF6NV1fvFNAKsGMoq8afpKFDx08KSR5clOqpRt4FQ6aKxpNQrMIdV52ZBnnQUqbST/BqchYWeTk+ccBp/0lHqo046S0QXvkMwW6X155g4UxwCVIae9zFi/4AANBNCnvRrn6DS31zc9AXvljMdnnJ4RWDw4SuGIJATK/lQNawwPBOxbZYWhjuRIctmv8FyMS2zjyjEm2GEF4chfm8lm4Yeg==
Path parameters:
Parameter
Required
Type
Description
Example value
out_trade_no
Yes
string
Merchant order number.
f49b3e588f1fec899b68
Query parameters:
Parameter
Required
Type
Description
Example value
mchid
Yes
string
Merchant ID, provided when the merchant places the order.
mi59a93ddccc

Response parameters

Parameter
Required
Type
Description
Example value
returnCode
Yes
string
Response code, 0 indicates success.
0
returnMessage
No
string
Response information.
OK
data
Yes
object
Response data.
-
data.app_id
Yes
string
The mini program appid, provided when the merchant places the order.
mp5ip444wt995zdp
data.mchid
Yes
string
Merchant ID, provided when the merchant places the order.
mi59a93ddccc
data.out_trade_no
Yes
string
Merchant order number, provided when the merchant places the order.
f49b3e588f1fec899b68
data.transaction_id
Yes
string
Superapp payment transaction ID.
tx2026082121482836425181pu94tn0w
data.trade_type
No
string
Returns the transaction type of the current order. Valid values: JSAPI: Mini program payment.
JSAPI
data.trade_state
Yes
string
The transaction status. Valid values: SUCCESS: Payment succeeded; REFUND: Refunded; NOTPAY: Unpaid; CLOSED: Closed; REVOKED: Revoked; USERPAYING: User paying; PAYERROR: Payment failed.
SUCCESS
data.trade_state_desc
Yes
string
A detailed description of the transaction status.
SUCCESS
data.bank_type
No
string
Description of the user's payment method, returned after successful payment. Format: bank code_specific type (DEBIT debit card/CREDIT credit card).
Wallet
data.attach
No
string
Custom data packet passed by the merchant when creating the order.
{\\"orderId\\":\\"6a885722038b71eee0fcddd6\\"}
data.success_time
No
string
The time when the user completes the payment. It is returned after the order is successfully paid. Format requirements: The payment end time shall follow the standard format: YYYY-MM-DDTHH:mm:ss+TIMEZONE. YYYY-MM-DD represents the date; T separates the date and time; HH:mm:ss represents the time; TIMEZONE represents the time zone (e.g., +08:00 corresponds to UTC+8). Example: 2015-05-20T13:29:35+08:00 represents 13:29:35 on May 20, 2015 (UTC+8).
2026-07-16T17:44:53+08:00
data.payer
No
object
Payer information of the order. It is returned after the order is successfully paid. It is the superapp user ID.
u7zwkxp5tz4kfa5hlz4jb53769jdkrkg
data.amount
No
object
Order amount information.
-
data.amount.total
No
string
Total order amount.
1600.00
data.amount.payer_total
No
string
Amount paid by the user.
1600.00
data.amount.currency
No
string
Currency type.
USD
data.amount.payer_currency
No
string
The currency used by the user for the payment.
USD
requestId
Yes
string
Request trace ID.
fd203616014e4ca8935f08a913ecfcb4

Request example

GET /v3/pay/transactions/out-trade-no/test_order_001?mchid=mi_test_merchant_001

Response example

{"returnCode":"0","returnMessage":"OK","requestId":"f6f5b4aea35a449cb259459a0dc60d7b","data":{"app_id":"mp_test_001","mch_id":"mi_test_merchant_001","out_trade_no":"test_order_001","transaction_id":"tx_test_001","trade_type":"JSAPI","trade_state":"SUCCESS","trade_state_desc":"SUCCESS","bank_type":"Wallet","attach":"{\\"appid\\":\\"mp_test_001\\"}","success_time":"2026-07-16T17:44:53+08:00","payer":"test_user_id_001","amount":{"payer_total":"1600","total":"1600","currency":"USD","payer_currency":"USD"}}}



2.4 Close an order

Orders that are in an unpaid status can be closed using this API when payment is no longer required. Common scenarios for closing an order include:
The user submits a request to cancel the order in the merchant system, and the merchant needs to close the order.
The order has timed out without payment (exceeding the payment time set by the merchant system or the time_expire payment deadline set when placing the order), and the merchant needs to close the order.
Path: /v3/pay/transactions/out-trade-no/{out_trade_no}/close
Method: POST
API description:
This API is used to close an order by the merchant order number.

Request parameters

Header parameters:
Parameter
Required
Type
Description
Example value
TC-Authorization
Yes
string
The signature authentication information. For more information, see Signature and Verification.
WECHATPAY2-SHA256-RSA2048 mchid="mi59a93ddccc",nonce_str="a60b588603",signature="D2euMbDqrigI2NwP+uADgyjyH8by4hi1Y0ze9vNBMIJs6jy98ktvXg7j7F/fyAvEM63iVTE7WRHAZ4T9n3vGaCcAakYGljL503wO4gHIYudqAeZnv/DenJjEDJysV50jeF6NV1fvFNAKsGMoq8afpKFDx08KSR5clOqpRt4FQ6aKxpNQrMIdV52ZBnnQUqbST/BqchYWeTk+ccBp/0lHqo046S0QXvkMwW6X155g4UxwCVIae9zFi/4AANBNCnvRrn6DS31zc9AXvljMdnnJ4RWDw4SuGIJATK/lQNawwPBOxbZYWhjuRIctmv8FyMS2zjyjEm2GEF4chfm8lm4Yeg==
Path parameters:
Parameter
Required
Type
Description
Example value
out_trade_no
Yes
string
Merchant order number.
f49b3e588f1fec899b68
Body parameters:
Parameter
Type
Required
Description
Example value
mchid
string
Yes
Merchant ID, provided when the merchant places the order.
mi59a93ddccc

Response parameters

Parameter
Type
Required
Description
Example value
returnCode
string
Yes
Response code, 0 indicates success.
0
returnMessage
string
No
Response information.
OK
data
string
Yes
Response data, OK indicates success.
OK
requestId
string
Yes
Request trace ID.
fd203616014e4ca8935f08a913ecfcb4

Request example

{"mchid":"mi_test_merchant_001"}

Response example

{"returnCode":"0","returnMessage":"OK","requestId":"e82df47154eb40408e66f8b6a9693e68","data":"ok"}

3. Mini game virtual payment APIs

3.1 Create a virtual payment order in the mini game

Path:/requestMidasPaymentGameItem
Method: POST
API description:
This API is used to create a virtual payment order in the mini game.

Request parameters

Header parameters:
Parameter
Required
Type
Description
Example value
TC-Payment-Callback
Yes
string
The callback URL of a successful or failed payment.
https://example.com/callback
TC-UserID
Yes
string
Superapp user login ID.
test_user_id_001
TC-MerchantID
Yes
string
The merchant ID bound to the mini program’s superapp on SAS.
mi59a93ddccc
TC-Platform-UserID
Yes
string
The user openid on SAS.
o6bd1c45d56c17841qEDgWR88700
Body parameters:
Parameter
Required
Type
Description
Example value
signData
Yes
string
For specific payment parameters, see signData below. The data must be passed in JSON format.
{"mode":"goods","buyQuantity":1,"currencyType":"USD","productId":"p100054665","outTradeNo":"2095e112-319a-4dda-b319-1c3ea09333a8","goodsPrice":"4.00","attach":"1234..."}
paySig
Yes
string
Virtual payment signature. For more information, see the paySig signature.The URI value is fixed to requestMidasPaymentGameItem.
6fcdc6fe88d064b22fcf4c73f34f8076436d8343e4724769032df3363be11ac7
appId
Yes
string
The superapp ID on SAS.
app-abo181jy4f
miniAppId
Yes
string
The mini game appid on SAS.
mgqvdu8w5asxh9wg
goodsName
Yes
string
Game item name.
Doraemon
orderSource
Yes
int
Order source. Fixed value: 1.
1
event
Yes
string
Fixed value: minigame_game_pay_goods_deliver_notify.
minigame_game_pay_goods_deliver_notify
signData:
Parameter
Required
Type
Description
Example value
model
Yes
string
Fixed value: goods.
goods
offerId
Yes
string
The merchant ID bound to the mini program’s superapp on SAS.
mi59a93ddccc
buyQuantity
Yes
int
Purchase quantity.
1
currencyType
Yes
string
Currency type, a three-letter code compliant with ISO 4217.
USD
productId
Yes
string
Virtual item ID.
psdsuyhds87787sds
goodsPrice
Yes
string
Item unit price. It supports up to 12 integer digits and up to 2 decimal places. Only digits and a maximum of one decimal point are allowed. Thousand separators, currency symbols, and negative numbers are not supported. Valid examples: "0.5", "10.5", "100.55", "1000", "10000.00".
4.00
outTradeNo
Yes
string
Internal order number in the merchant system, must be 6-64 characters long, can only include numbers, uppercase and lowercase letters, _-|*, and must be unique within the same merchant ID.
2095e112-319a-4dda-b319-1c3ea09333a8
attach
No
string
Will be passed through and returned in payment callback.
{"appid":"mp_test_001"}

Response parameters

Parameter
Type
Required
Description
Example value
returnCode
string
Yes
Response code, 0 indicates success.
0
returnMessage
string
No
Response information.
OK
data
object
Yes
Response data.
-
data.prepayId
string
Yes
Superapp order ID.
pim17873098978027ioaenena3h8pf1nmus2
requestId
string
Yes
Request trace ID.
fd203616014e4ca8935f08a913ecfcb4

Request example

{"signData":"{\\"mode\\":\\"goods\\",\\"offerId\\":\\"mi1b105d3f77d52ccb87e84561f452a7\\",\\"buyQuantity\\":1,\\"currencyType\\":\\"USD\\",\\"productId\\":\\"5\\",\\"outTradeNo\\":\\"8d41176a-66cd-40a2-9772-b4824f2b610b\\",\\"goodsPrice\\":"180",\\"attach\\":\\"1234...\\"}","paySig":"2c4d07267bf6ee0db3605f631f62dac148f45916b71ce041b520814002190d0d","appId":"app-59dkvj9ybo","miniAppId":"mgbg212tfnbir19g","goodsName":"Conventional missile","orderSource":1,"event":"minigame_game_pay_goods_deliver_notify"}

Response example

{"returnCode":"0","returnMessage":"OK","requestId":"616e28f0bcbe4f13b9dca405f05a7aa1","data":{"prepayId":"pim_test_prepay_game_001"}}

3.2 Mini game payment callback

When a user successfully pays for an order using the regular payment function, the superapp will send a callback notification via a POST request to the TC-Payment-Callback described in the section 3.1, informing the merchant that the user has completed the payment.
Path: TC-Payment-Callback, described in the section 3.1
Method: POST
API description:
Mini game payment callback.

Request parameters

Header parameters:
Parameter
Required
Type
Description
Example value
TC-ApplicationID
Yes
string
The superapp ID on SAS.
app-abo181jy4f
TC-BackendConfigID
Yes
string
Backend configuration ID of the SAS accessing the superapp, used to distinguish environments. TC-BackendConfigID in the request header when creating an order.
appserver-1
TC-Signature
Yes
string
The signature for invoking signature verification on SAS. SeeSuper App as a Service Signature and Verification.
dc8bac73413d8c69c1bc5be856ee9cf1
TC-Timestamp
Yes
string
Timestamp (in seconds).
1787320102
Body parameters:
Parameter
Required
Type
Description
Example value
eventType
Yes
string
Message type. Payment success - TRANSACTION.SUCCESS. Payment failure - TRANSACTION.PAYERROR.
TRANSACTION.SUCCESS
event
Yes
string
The event when creating an order.
minigame_game_pay_goods_deliver_notify
payModel
No
string
Payment methods: Wallet, bankcard, third party
Wallet
payload
Yes
string
Detailed content in JSON format. See the payload table below. (All message content is formatted as JSON for unified signature verification.)
{"OpenId":"o8197e6f8ac817871vxypNK57520","OutTradeNo":"2095e112-319a-4dda-b319-1c3ea09333a8","GoodsInfo":{"ProductId":"p100054665","Quantity":1,"OrigPrice":"4.00","ActualPrice":"4.00","attach":"1234...","OrderSource":1},"PayInfo":{"MchOrderNo":"miea24116372bf17c1e4f9f3b80d6690","TransactionId":"tx202608211858236904429mabkfue6y","PaidTime":0}}
payEventSig
Yes
string
For more information, see PayEventSig signature.Event value: minigame_game_pay_goods_deliver_notify.
minigame_game_pay_goods_deliver_notify
transactionId
No
string
Superapp payment transaction ID.
tx202608211858236904429mabkfue6y
outTradeNo
Yes
string
Merchant order number.
2095e112-319a-4dda-b319-1c3ea09333a8
payload:
Parameter
Required
Type
Description
Example value
OpenId
Yes
string
The user openid on SAS.
o8197e6f8ac817871vxypNK57520
OutTradeNo
Yes
string
Merchant order number.
2095e112-319a-4dda-b319-1c3ea09333a8
GoodsInfo
Yes
object
The virtual item info.
-
PayInfo
Yes
object
Payment information.
-
GoodsInfo:
Parameter
Required
Type
Description
Example value
ProductId
Yes
string
Game item ID.
p100054665
Quantity
Yes
int
Quantity of game items purchased.
1
OrigPrice
Yes
string
Original price.
4.00
ActualPrice
Yes
string
Actual paid price.
4.00
Attach
Yes
string
Pass-through data.
{"appid":"mp_test_001"}
OrderSource
Yes
int
Order source.
1
PayInfo:
Parameter
Type
Required
Description
Example value
MchOrderNo
string
Yes
Merchant ID, provided when the merchant places the order.
mi59a93ddccc
PaidTime
int
No
Payment timestamp (in seconds).
1787355501
TransactionId
string
No
Superapp payment transaction ID.
tx20260822073818768117gzxdrh38bs

Response parameters

Parameter
Required
Type
Description
Example value
returnCode
Yes
string
Response code, 0 indicates success.
0
returnMessage
No
string
Response information.
OK
data
Yes
string
Response data, OK indicates success.
OK
requestId
Yes
string
Request trace ID.
fd203616014e4ca8935f08a913ecfcb4

Request example

{"eventType":"TRANSACTION.SUCCESS","event":"minigame_game_pay_goods_deliver_notify","transactionId":"tx202607212009049123827s9eoclex4","payMode":"Wallet","payload":"{\\"OpenId\\":\\"offc2718804217846IVfjea10186\\",\\"OutTradeNo\\":\\"c8ec5d52-7231-406c-a97f-7b839ebb0b7e\\",\\"GoodsInfo\\":{\\"ProductId\\":\\"7\\",\\"Quantity\\":1,\\"OrigPrice\\":"300",\\"ActualPrice\\":\\"300\\",\\"Attach\\":\\"1234...\\",\\"OrderSource\\":1},\\"MchOrderNo\\":\\"pim1784635740007lfbkvvn6e0vjyfc6wfj3\\",\\"TransactionId\\":\\"tx202607212009049123827s9eoclex4\\"}","payEventSig":"e5c8efa45983997e8ac375c6fbade15dc29c6bc58a0dd41ca93fbe9feaf781ba","outTradeNo":"c8ec5d52-7231-406c-a97f-7b839ebb0b7e"}

Response example

{"returnCode":"0","returnMessage":"success","requestId":"ee3d604b988545fd951db7360bedc93e","data":"ok"}

4. Mini program virtual payment APIs

4.1 Create a virtual payment order in the mini program

Path:/requestVirtualPayment
Method: POST
API description:
This API is used to create a virtual payment order in the mini program.

Request parameters

Header parameters:
Parameter
Required
Type
Description
Example value
TC-Payment-Callback
Yes
string
The callback URL of a successful or failed payment.
https://example.com/callback
TC-UserID
Yes
string
Superapp user login ID.
o6bd1c45d56c17841qEDgWR88700
TC-MerchantID
Yes
string
The merchant ID bound to the mini program’s superapp on SAS.
mi59a93ddccc
TC-Platform-UserID
Yes
string
The user openid on SAS.
test_user_id_001
Body parameters:
Parameter
Required
Type
Description
Example value
signData
Yes
string
Original payment string. For specific payment parameters, see signData below. The data must be passed in JSON format.
{"mode":"goods","offerId":"mi59a93ddccc","buyQuantity":1,"currencyType":"USD","productId":"p1012930293","goodsPrice":"2500.00","outTradeNo":"9e9652f5-322c-403e-9074-1b28d1421ac7","attach":""}
paySig
Yes
string
Virtual payment signature. For more information, see the paySig signature.The URI value is fixed to requestVirtualPayment.
c698ee16f162ccc6fa88154808607f6fd6c597e958cabef6ec36c861ee8c1dff
appId
Yes
string
The superapp ID on SAS.
app-abo181jy4f
miniAppId
Yes
string
The mini program appid on SAS.
mprz285jdlprq69o
goodsName
Yes
string
Game item name.
Doraemon
orderSource
Yes
int
Order source. The fixed value is 10, indicating the order is placed within a Mini Program short drama.
10
event
Yes
string
When OrderSource=10, it is fixed as: xpay_goods_deliver_notify.
xpay_goods_deliver_notify
signData:
Parameter
Required
Type
Description
Example value
model
Yes
string
Fixed value: goods.
goods
offerId
Yes
string
The merchant ID bound to the mini program’s superapp on SAS.
mi59a93ddccc
buyQuantity
Yes
int
Purchase quantity.
1
currencyType
Yes
string
Currency type, a three-letter code compliant with ISO 4217.
USD
productId
Yes
string
Virtual item ID.
p1012930293
goodsPrice
Yes
string
Item unit price. It supports up to 12 integer digits and up to 2 decimal places. Only digits and a maximum of one decimal point are allowed. Thousand separators, currency symbols, and negative numbers are not supported. Valid examples: "0.5", "10.5", "100.55", "1000", "10000.00".
2500.00
outTradeNo
Yes
string
Internal order number in the merchant system, must be 6-64 characters long, can only include numbers, uppercase and lowercase letters, _-|*, and must be unique within the same merchant ID.
9e9652f5-322c-403e-9074-1b28d1421ac7
attach
No
string
Will be passed through and returned in payment callback.
{"appid":"mp_test_001"}

Response parameters

Parameter
Type
Required
Description
Example value
returnCode
string
Yes
Response code, 0 indicates success.
0
returnMessage
string
No
Response information.
OK
data
object
Yes
Response data.
-
data.prepayId
string
Yes
Superapp order ID.
pip1787320103622n1mjc6qgytpith9yg9pb
requestId
string
Yes
Request trace ID.
fd203616014e4ca8935f08a913ecfcb4

Request example

{"signData":"{\\"mode\\":\\"goods\\",\\"offerId\\":\\"mi1b105d3f77d52ccb87e84561f452a7\\",\\"buyQuantity\\":1,\\"currencyType\\":\\"USD\\",\\"productId\\":\\"1\\",\\"goodsPrice\\":250,\\"outTradeNo\\":\\"231a2ffe-93b3-4679-a7b8-46c2e75d2bb1\\",\\"attach\\":\\"\\"}","paySig":"60f0254ff7fe96a20c27aa385412badc967c7dfdf2b7f062752763bab36d750f","appId":"app-59dkvj9ybo","miniAppId":"mp9sq1zu3lgiwqkd","goodsName":"Doraemon","orderSource":"10","event":"xpay_goods_deliver_notify"}

Response example

{"returnCode":"0","returnMessage":"OK","requestId":"29004d42c5cd49819047fa95133183e0","data":{"prepayId":"pim_test_prepay_mnp_001"}}

4.2 Mini program virtual payment callback

When a user successfully pays for an order using the regular payment function, the superapp will send a callback notification via a POST request to the TC-Payment-Callback described in the section 4.1, informing the merchant that the user has completed the payment.
Path: TC-Payment-Callback, described in the section 4.1
Method: POST
API description:
Mini program virtual payment callback.

Request parameters

Header parameters:
Parameter
Required
Type
Description
Example value
TC-ApplicationID
Yes
string
The superapp ID on SAS.
app-abo181jy4f
TC-BackendConfigID
Yes
string
Backend configuration ID of the SAS accessing the superapp, used to distinguish environments. TC-BackendConfigID in the request header when creating an order.
appserver-1
TC-Signature
Yes
string
The signature for invoking signature verification on SAS. SeeSuper App as a Service Signature and Verification.
dc8bac73413d8c69c1bc5be856ee9cf1
TC-Timestamp
Yes
string
Timestamp (in seconds).
1787320102
Body parameters:
Parameter
Required
Type
Description
Example value
eventType
Yes
string
Message type. Payment success - TRANSACTION.SUCCESS. Payment failure - TRANSACTION.PAYERROR.
TRANSACTION.SUCCESS
event
Yes
string
Event type. The event when creating an order.
xpay_goods_deliver_notify
payMode
No
string
Payment methods: Wallet, bankcard, third party
Wallet
payload
Yes
string
Detailed content in JSON format. See the Payload table below. (All message content is formatted as JSON for unified signature verification.)
{"OpenId":"o79a2ea7091c17872ReYfcR16301","OutTradeNo":"b2f1935d-9740-4dc0-80da-49dccfabe69d","GoodsInfo":{"ProductId":"p1012930293","Quantity":10,"OrigPrice":"2000.00","ActualPrice":"2000.00","Attach":"","OrderSource":10},"PayInfo":{"MchOrderNo":"pim1787308704013qtemk6ko0a8bpwzqvgmo","TransactionId":"tx20260821183830589477ux2dkk8p22","PaidTime":1787308710}}","payEventSig":"9404cf6615826e5ee8ffdbd4c63a388d9b323a3b288870b533f576856ba82c36","outTradeNo":"b2f1935d-9740-4dc0-80da-49dccfabe69d"}
payEventSig
Yes
string
For more information, see
xpay_goods_deliver_notify
transactionId
No
string
Superapp payment transaction ID.
tx20260821183830589477ux2dkk8p22
outTradeNo
Yes
string
Merchant order number.
b2f1935d-9740-4dc0-80da-49dccfabe69d
payload:
Parameter
Required
Type
Description
Example value
OpenId
Yes
string
The user ID on SAS. It is TC-Platform-UserID in the header when placing an order.
o6bd1c45d56c17841qEDgWR88700
OutTradeNo
Yes
string
Order number.
b2f1935d-9740-4dc0-80da-49dccfabe69d
GoodsInfo
Yes
object
The virtual item info.
-
PayInfo
Yes
object
Payment information.
-
GoodsInfo:
Parameter
Required
Type
Description
Example value
ProductId
Yes
string
Game item ID.
p1012930293
Quantity
Yes
int
Quantity of game items purchased.
1
OrigPrice
Yes
string
Original price.
2000.00
ActualPrice
Yes
string
Actual paid price.
2000.00
Attach
Yes
string
Pass-through data.
{"appid":"mp_test_001"}
OrderSource
Yes
int
Order source. Valid values: 1: In-game.
10
PayInfo:
Parameter
Required
Type
Description
Example value
MchOrderNo
Yes
string
Merchant ID, provided when the merchant places the order.
b2f1935d-9740-4dc0-80da-49dccfabe69d
PaidTime
No
number
Payment timestamp (in seconds).
1787308710
TransactionId
No
string
Superapp payment transaction ID.
tx20260821183830589477ux2dkk8p22

Response parameters

Parameter
Type
Required
Description
Example value
returnCode
string
Yes
Response code, 0 indicates success.
0
returnMessage
string
No
Response information.
OK
data
string
Yes
Response data, OK indicates success.
OK
requestId
string
Yes
Request trace ID.
fd203616014e4ca8935f08a913ecfcb4

Request example

{"eventType":"TRANSACTION.SUCCESS","event":"xpay_goods_deliver_notify","transactionId":"tx20260721200041158935ihgcnxynly","payMode":"Wallet","payload":"{\\"OpenId\\":\\"o6bd1c45d56c17841qEDgWR88700\\",\\"OutTradeNo\\":\\"28f7a5cc-4427-4b0c-bf26-228e7de19d76\\",\\"GoodsInfo\\":{\\"ProductId\\":\\"1\\",\\"Quantity\\":25,\\"OrigPrice\\":"6250",\\"ActualPrice\\":\\"6250\\",\\"attach\\":\\"\\",\\"OrderSource\\":10},\\"PayInfo\\":{\\"MchOrderNo\\":\\"pim1784635237083gn2uin6pm4ai87adyk83\\",\\"TransactionId\\":\\"tx20260721200041158935ihgcnxynly\\",\\"PaidTime\\":1784635241}}","payEventSig":"a1df35b720a4f09d44eb540a222c195ce1e4b784b987e153b9b55679f41755a1","outTradeNo":"28f7a5cc-4427-4b0c-bf26-228e7de19d76"}

Response example

{"returnCode":"0","returnMessage":"success","requestId":"6a0f4155fdb041fbb0f08381424d3966","data":"ok"}

5. Refund APIs

5.1 Standard payment refund

5.1.1 Initiate refund request

Path: /spay/refund/refunds
Method: POST
API description: This API is used to initiate a refund request for a completed standard payment order.

Request parameters

Header parameters:
Parameter
Required
Type
Description
Example value
TC-Payment-Callback
Yes
string
Refund result callback URL.
https://example.com/callback
TC-Authorization
Yes
string
The signature authentication information. For more information, see Signature and Verification.
WECHATPAY2-SHA256-RSA2048 mchid="mi59a93ddccc",nonce_str="327fd493426a3511ee5b058da5b55581",signature="cwlDykNGE4NE9xiSV7OyrHAFPWQQgiMQ0f6W0yZU6OzXXd47W+YydGIAR67mmeDRWKuW5c32qBuEIgs30Nofp8+l1Gyn48RDWBX4HI7UMZ34i8tehpamcrkrscxV2PvF2j1aEXw91SYCGyUrhnnTdFad53RVI+LXlrxGVUKjss7XGb484//CDCVh4LjaGYtlqFt2+owR5ZBxdWWfBorCEkgMDRHlRXBwgLA35qzdmPzx+6BcHADuTtrp83v2rI0i8yOuWR/k15N4gEF8PqMF2FcwN/U9JViDA9NtsiXoddtOirBChTtlFaakwIjguQYCuiUj/aJHgkeR/XPQKZjMWg==",timestamp="1787317409",serial_no="7510596630"
Body parameters:
Parameter
Required
Type
Description
Example value
transaction_id
No
string
Transaction ID on the superapp (Either this or out_trade_no required.)
tx20260821203742618148dhiip3n4oj
out_trade_no
No
string
Merchant order number, either this or transaction_id required.
f49b3e588f1fec899b68
out_refund_no
Yes
string
Unique refund order number per merchant.
test_order_001-REF001
reason
No
string
Refund reason.

refund_method
No
string
Refund method: Original, bankcard, wallet.
ORIGINAL
channel
No
string
Refund channel: Original, balance.
ORIGINAL
refund_source
No
string
Refund origin. Valid values: 1: Customer service; 2 User; 3 Others.
1
amount
Yes
object
Refund amount details.
-
amount.refund
Yes
string
Total refund amount.
1600.00
amount.total
Yes
string
Original order amount. It supports up to 12 integer digits and up to 2 decimal places. Only digits and a maximum of one decimal point are allowed. Thousand separators, currency symbols, and negative numbers are not supported. Valid examples: "0.5"、"10.5"、"100.55"、"1000"、"10000.00".
1600.00
amount.currency
Yes
string
Currency, e.g., USD.
USD
goods_detail
No
array
Refunded product details.
-
goods_detail[].merchant_goods_id
Yes
string
Merchant's product code.
yn48RDWBX4HI7UMZ
goods_detail[].goods_name
No
string
Product name.
Goods
goods_detail[].unit_price
Yes
string
Unit price. It supports up to 12 integer digits and up to 2 decimal places. Only digits and a maximum of one decimal point are allowed. Thousand separators, currency symbols, and negative numbers are not supported. Valid examples: "0.5", "10.5", "100.55", "1000", "10000.00".
1600.00
goods_detail[].refund_amount
Yes
string
Total refund amount. It supports up to 12 integer digits and up to 2 decimal places. Only digits and a maximum of one decimal point are allowed. Thousand separators, currency symbols, and negative numbers are not supported. Valid examples: "0.5", "10.5", "100.55", "1000", "10000.00".
1600.00
goods_detail[].refund_quantity
Yes
int
Number of items refunded.
1
notify_url
Yes
string
Refund result notification URL.
https://example-test.com/callback/pay/mp_test_001
merchant_id
Yes
string
Merchant ID.
mi59a93ddccc

Response parameters:

Parameter
Required
Type
Description
Example value
returnCode
Yes
string
Response code, 0 indicates success.
0
returnMessage
No
string
Response information.
OK
data
Yes
object
Refund response data.
-
data.refund_id
Yes
string
Platform refund ID.
rn1787317410603a5t42r5re5nf0mj7xg29
data.out_refund_no
Yes
string
Merchant refund number.
REF-20260821-130329-fcd729-0-173397
data.transaction_id
Yes
string
Superapp payment transaction ID.
tx20260821203742618148dhiip3n4oj
data.out_trade_no
Yes
string
Merchant order number.
MP17873158523768884953d
data.channel
Yes
string
Refund channels.
ORIGINAL
data.user_received_account
No
string
Account that receives the refund.
-
data.success_time
No
string
Refund success time.
-
data.create_time
Yes
string
Refund creation time.
2026-08-21T21:03:30+08:00"
data.status
Yes
string
Refund status. Valid values: PROCESSING (the refund is being processed), SUCCESS (the refund succeeded), CLOSED (the refund is closed), ABNORMAL (an error occurred during the refund).
PROCESSING
data.amount
Yes
object
Refund amount details.
-
data.amount.total
Yes
string
Total order amount.
1600.00
data.amount.refund
Yes
string
Total refund amount.
1600.00
data.amount.payer_total
Yes
string
Amount paid by the user.
1600.00
data.amount.payer_refund
Yes
string
Payer's refund amount.
1600.00
data.amount.currency
Yes
string
Currency.
USD
data.amount.refund_fee
No
string
Handling fee.
0.00
requestId
Yes
string
Request trace ID.
fd203616014e4ca8935f08a913ecfcb4

Request example

{"out_trade_no":"test_order_001","out_refund_no":"test_order_001-REF001","reason":"","notify_url":"https://example-test.com/callback/refund/mp_test_001","amount":{"refund":"1600","total":"1600","currency":"USD"},"goods_detail":[{"merchant_goods_id":"1","goods_name":"Tropical Citrus Iced Energy","unit_price":"1600","refund_amount":"1600","refund_quantity":1}],"merchant_id":"mi_test_merchant_001"}

Response example

{"returnCode":"0","returnMessage":"OK","requestId":"6be7f9b106fe476c9be1ded444bf41ed","data":{"refund_id":"rn_test_refund_001","out_refund_no":"test_order_001-REF001","transaction_id":"tx_test_001","out_trade_no":"test_order_001","channel":"ORIGINAL","user_received_account":"","create_time":"2026-07-21T15:28:05+08:00","status":"PROCESSING","amount":{"total":1600,"refund":1600,"payer_total":1600,"payer_refund":1600,"currency":"USD","refund_fee":0}}}

5.1.2 Query the refund

Path: /spay/refund/refunds/{out_refund_no}
Method: GET
API description: This API is used to query the refund details by merchant refund number.

Request parameters

Header parameters:
Parameter
Required
Type
Description
Example value
TC-Authorization
Yes
string
The signature authentication information. For more information, see Signature and Verification.
WECHATPAY2-SHA256-RSA2048 mchid="mi59a93ddccc",nonce_str="c7fceaba38",signature="eG/9G6H3uFtxtnpNE+al3yHNkPZl3comAJJNJxbfvm3L3m3ESWxXgB2qO+2P1fhxjwodzd5KGNVjS0fPudT1nw0hjSofrfwfy72TkUEj+a1jfjzb95DN62ObSPt7dqPRGj0pvUF5it+pvk30zrgNxuuveAb6nzJaD1tKN+oU9f3Zw2kjj4guVYCEqAX3byGG38f0/9I873zIs55XIDhfyucUiyhGgZD9t9WxKB+do95J7P4nmS+xm3WGNFOoZ6lxj+6OPOcyCmbcTZihEFrSNKOQBcyTJh3BbWGfcBaBxk+Gbf48Cabi32Pgpxn6hHmtNyaPhRyWjgLqB+eo05o3/g==",timestamp="1787317412",serial_no="7510596630"
Path parameters:
Parameter
Required
Type
Description
Example value
out_refund_no
Yes
string
Merchant refund number.
test_order_001-REF001

Response parameters

Parameter
Required
Type
Description
Example value
returnCode
Yes
string
Response code, 0 indicates success.
0
returnMessage
No
string
Response information.
OK
data
No
object
Refund detail data.
-
data.refund_id
Yes
string
Platform refund ID.
rn1787317410603a5t42r5re5nf0mj7xg29
data.out_refund_no
Yes
string
Merchant refund number.
REF-20260821-130329-fcd729-0-173397
data.transaction_id
Yes
string
Superapp payment transaction ID.
tx20260821203742618148dhiip3n4oj
data.out_trade_no
Yes
string
Merchant order number.
MP17873158523768884953d
data.channel
Yes
string
Refund channels.
ORIGINAL
data.user_received_account
No
string
Account that receives the refund.
-
data.success_time
No
string
Refund success time.
2026-08-21T21:03:35+08:00
data.create_time
Yes
string
Refund creation time.
2026-08-21T21:03:30+08:00
data.status
Yes
string
Refund status. Valid values: PROCESSING (the refund is being processed), SUCCESS (the refund succeeded), CLOSED (the refund is closed), ABNORMAL (an error occurred during the refund).
SUCCESS
data.amount
Yes
object
Refund amount details.
-
data.amount.total
Yes
string
Total order amount.
1600.00
data.amount.refund
Yes
string
Total refund amount.
1600.00
data.amount.payer_total
Yes
string
Amount paid by the user.
1600.00
data.amount.payer_refund
No
string
Payer's refund amount.
1600.00
data.amount.currency
Yes
string
Currency.
USD
data.amount.refund_fee
No
string
Handling fee.
0.00
requestId
Yes
string
Request trace ID.
fd203616014e4ca8935f08a913ecfcb4

Request example

GET /spay/refund/refunds/test_order_001-REF001

Response example

{"returnCode":"0","returnMessage":"OK","requestId":"7a3a18df41594da98e46ad9d70e918a1","data":{"refund_id":"rn_test_refund_001","out_refund_no":"test_order_001-REF001","transaction_id":"tx_test_001","out_trade_no":"test_order_001","channel":"ORIGINAL","user_received_account":"","success_time":"2026-07-21T20:12:56+08:00","create_time":"2026-07-21T20:11:25+08:00","status":"SUCCESS","amount":{"total":"1600","refund":"1600","payer_total":"1600","payer_refund":"1600","currency":"USD","refund_fee":0}}}

5.1.3 Standard payment refund callback

After the refund review is complete, the superapp sends a notification via a POST request to the URL specified in the TC-Payment-Callback TC-Payment-Callback header in the refund request.
Path: Value of the TC-Payment-Callback request header used when you apply for a refund via the API in section 5.2.1.
Method: POST

Request parameters

Header parameters:
Parameter
Required
Type
Description
Example value
TC-Callback-Serial
Yes
string
The serial number of the superapp payment certificate used for verification.
B9B3EFE9E10EC481569ACAC46C5B8B52EEA2F2CE
TC-Callback-Signature
Yes
string
The signature generated by the superapp, used by the merchant for verification.
SVj3Gm2AdEu2/3E0jRaHa+7G4HdvtyyuHTlv9F4jx+N+tmBdLUJCRIQQ34spT8fp3DU1oY2fUkOiYH8z4nO/vtZrhTslhNfBuaRVVxLKjFuMKNTOYDZ8IDRgJDkryxYY/7DljMuKpzR125N4+1qn+gr+Ia0maGNwlIdyg19A16qaA0jHTliKfD+prtjGYxHm/5gPIeMEskTa6TJdyfwFPTsfeXc8n6l7v5AtEJ2zqOAWXnfKK9dIwi8z4JSmdiWDgU5O5AbKxH0ycUEecyUtjipK2cDKH/2zvLlBchyrDzUyFoq5OJq9hz1U3jBL1Tc+D7lv+vK05uhYwgaU8Fyf9g==
TC-Timestamp
Yes
string
Timestamp (in seconds).
1787309129
TC-Callback-Nonce
Yes
string
Random string for verification.
PAWO6qFR7ILP
TC-Signature
Yes
string
The signature for invoking signature verification on SAS. SeeSuper App as a Service Signature and Verification.
4f7b89a2b94208e7f6903b497960eb7c
TC-ApplicationID
Yes
string
The superapp ID on SAS.
app-abo181jy4f
TC-BackendConfigID
Yes
string
Backend configuration ID of the SAS accessing the superapp, used to distinguish environments. TC-BackendConfigID in the request header when creating an order.
appserver-1
Body parameters:
Parameter
Required
Type
Description
Example value
id
Yes
string
Unique notification ID.
youx36thyawcwqh5
create_time
Yes
string
Notification creation time, RFC3339 format.
2026-08-21T18:45:29+08:00
event_type
Yes
string
REFUND.SUCCESS / REFUND.CLOSED / REFUND.ABNORMAL
REFUND.SUCCESS
resource_type
Yes
string
Fixed value: encrypt-resource.
encrypt-resource
summary
Yes
string
Notification summary.
Pay success
out_refund_no
Yes
string
Merchant refund number.
test_order_001-REF001
resource
Yes
object
Encrypted notification data.
-
resource.algorithm
Yes
string
Fixed value: AEAD_AES_256_GCM.
AEAD_AES_256_GCM
resource.original_type
Yes
string
Fixed value: refund.
refund
resource.ciphertext
Yes
string
Base64-encoded encrypted data. It must be decrypted using the API v3 key.
bg+uF4Or3anFuYGGzZgab3AuGX5KXqO+O+SGPJpycz+V4mWPYYwhPsJ75wzxfFHQ0fOAnbKHEmV42JDFP4TZXjxmervyRH/8CZRiPAyoTdbVPGOQ3cUqfSzQwubkomhRHRti1IzjiLBoGffMMXk4qiTNXcLvhqXtbAH92vdKRW4phvNvJo/z7ABlGEd37wr7EP5eFx89pqzv0+AUx7eBMJW95NJ3DJoQ7FGeVp0AyZa8PvzJbhvr9cZBCyoZZTmesWduiry5QF6T4OzDQmlWQotMlXY7kceEqsaB9CIJE+Xbx9nuckrf+8bOA3KWSQ1hM7D6VXLKTMi0bf27mFEN0uTPh6/iq5AWMfIaS4VY8lc+V08nDXlBxkoCgpeAp9GY8muob2Cwel2Cmf/TWnlkGVmazozK3ey6/DmlqTqNA+47LxT9yB6QDGqzmXBQ3ii6IXtLg5L5CgLIJl1gOt5UIfPseXgC7s0pErbxXmq8lkbS6sOZiVcxAhPKZjY8V0TQrtYLNAMWWZt/AYbohHWCPuB/z16sA2TIg17HHglRR1tc6z0YkZaZ5DWv7X/GcZtyZ8ZZ3lTvK8TlVW7g1K3GMWZuGM0=
resource.associated_data
No
string
Additional data for decryption.
-
resource.nonce
Yes
string
Random string for decryption.
PAWO6qFR7ILP
Decrypted structure of resource.ciphertext data:
Parameter
Required
Type
Description
Example value
mch_id
Yes
string
Merchant ID.
mi59a93ddccc
transaction_id
Yes
string
Superapp payment transaction ID.
tx_test_001
out_trade_no
Yes
string
Merchant order number.
f49b3e588f1fec899b68
refund_id
Yes
string
Platform refund ID.
rn_test_refund_001
out_refund_no
Yes
string
Merchant refund number.
test_order_001-REF001
refund_status
Yes
string
Refund status. Valid values: SUCCESS; CLOSED; ABNORMAL.
SUCCESS
success_time
No
string
Refund success time (returned only if SUCCESS).
2026-07-16T17:44:53+08:00
user_received_account
No
string
Account that receives the refund.
-
amount
Yes
object
Refund amount details.
-
amount.total
Yes
string
Total order amount.
1600.00
amount.refund
Yes
string
Total refund amount.
1600.00
amount.payer_total
Yes
string
Amount paid by the user.
1600.00
amount.payer_refund
Yes
string
Payer's refund amount.
1600.00
amount.currency
Yes
string
Currency.
USD

Response parameters

Parameter
Type
Required
Description
Example value
returnCode
string
Yes
Response code, 0 indicates success.
0
returnMessage
string
No
Response information.
OK
data
string
Yes
Response data, OK indicates success.
OK
requestId
string
Yes
Request trace ID.
fd203616014e4ca8935f08a913ecfcb4

Request example

{"id":"xot956537fkiaem2","create_time":"2026-07-21T20:12:57+08:00","resource_type":"encrypt-resource","event_type":"REFUND.SUCCESS","summary":"REFUND.SUCCESS","out_refund_no":"796be7e45d47b27b23e7-REF1416","resource":{"original_type":"refund","algorithm":"AEAD_AES_256_GCM","ciphertext":"N9v6vk+uRTppTbAxXYdZktZqfga8pA4OzoNukU0+wbHzhl7NWtQzDQs/F3G/xVvBCzW3koZZ2JUKkVKnF+v7+lUSEC11NEAltrdQk9AcSjR9IXnsLaTw8wT1t1R0NhU1hyBgR+bdA4J68kHEkva/WrhFhCG0OiBbabORJ/KUXO4OV4E936J3X+ecY7w+yos5wgWVgTdU/HAVJLyfkfzqzkY+DoP6BoPTJwA+Q0lMbUf+KQpeF0AYvyzvR+Jarzvs+7ehHlobdKUigKAjz2UhQfqUVmDgldMYVa1I5FFYHDkTmbI9MnZZTOW22f62TvotBwTNPhdDNCFJ13b8rAA6EWdAn4MQoqz4HpghYP2IRVJHs3Xl3NSEu5l3r2YtrvEQIUOYH73cGVUMngUyMR8B/105PkaetReNCl4BHL275sh0c1NhHv7Cy5CyeiTgDgz8bKcmMlyLl/Fm4geqdDBqILRCDSjTzmVDByPFZPDrcmkr53BiwPKWsU8CF5k4g/alr4rgnzaCyPtxF5mXDpQK59LrLMG+JsUKsESN6cXMoRTn0vEzzgQeo360A2w58g6Ni7NRBT6x4s7LYpUPC2CC9AVZtUI=","associated_data":"","nonce":"FdFteTZt9T8b"}

Response example


{"returnCode":"0","returnMessage":"success","requestId":"6974f497beb2418b8707d6036cac589f","data":"ok"}

5.2 Virtual payment refunds

5.2.1 Initiate refund request

Path: /vpay/refund/refunds
Method: POST
API description: This API is used to initiate a refund request for a completed payment order in a mini program or mini game.

Request parameters

Header parameters:
Parameter
Required
Type
Description
Example value
TC-Payment-Callback
Yes
string
Refund result callback URL.
https://example.com/callback
TC-MerchantID
Yes
string
The merchant ID bound to the mini program’s superapp on SAS.
mi59a93ddccc
Query parameters:
Parameter
Required
Type
Description
Example value
pay_sig
Yes
string
Virtual payment signature. For more information, see the paySig signature., uri=/vpay/refund/refunds
60f0254ff7fe96a20c27aa385412badc967c7dfdf2b7f062752763bab36d
Body parameters:
Parameter
Required
Type
Description
Example value
openid
No
string
User openid who placed the order.
o6bd1c45d56c17841qEDgWR88700
transaction_id
No
string
Transaction ID on the superapp (Either this or out_trade_no required.)
tx_test_001
out_trade_no
No
string
Merchant order number, either this or transaction_id required.
f49b3e588f1fec899b68
out_refund_no
Yes
string
Merchant refund number.
test_order_001-REF001
reason
No
string
Refund reason.

req_from
No
string
Refund origin. Valid values: 1: Customer service; 2 User; 3 Others.
2
amount
Yes
object
Refund amount details.
-
amount.refund
Yes
string
Total refund amount. It supports up to 12 integer digits and up to 2 decimal places. Only digits and a maximum of one decimal point are allowed. Thousand separators, currency symbols, and negative numbers are not supported. Valid examples: "0.5", "10.5", "100.55", "1000", "10000.00".
1600.00
amount.total
Yes
string
Original order amount. It supports up to 12 integer digits and up to 2 decimal places. Only digits and a maximum of one decimal point are allowed. Thousand separators, currency symbols, and negative numbers are not supported. Valid examples: "0.5", "10.5", "100.55", "1000", "10000.00".
1600.00
amount.currency
Yes
string
Currency.
USD
merchant_id
Yes
string
Merchant ID.
mi_test_merchant_001

Response data

Parameter
Required
Type
Description
Example value
returnCode
Yes
string
Response code, 0 indicates success.
0
returnMessage
No
string
Response information.
OK
data
Yes
object
Refund response data.
-
data.refund_id
Yes
string
Platform refund ID.
rn17873102825245ly856vr5s7jq5uj9kco
data.out_refund_no
Yes
string
Merchant refund number.
2095e112-319a-4dda-b319-1c3ea09333a8-REF2269
data.transaction_id
Yes
string
Superapp payment transaction ID.
tx202608211858236904429mabkfue6y
data.out_trade_no
Yes
string
Merchant order number.
2095e112
data.channel
No
string
Refund channels.
ORIGINAL
data.user_received_account
No
string
Account that receives the refund.
-
data.success_time
No
string
Refund success time.
2026-08-21T19:04:45+08:00
data.create_time
Yes
string
Refund creation time.
2026-08-21T19:04:42+08:00
data.status
Yes
string
Refund status. Valid values: PROCESSING (the refund is being processed), SUCCESS (the refund succeeded), CLOSED (the refund is closed), ABNORMAL (an error occurred during the refund).
SUCCESS
data.amount
Yes
object
Refund amount details.
-
data.amount.total
Yes
string
Total order amount.
1600.00
data.amount.refund
Yes
string
Total refund amount.
1600.00
data.amount.payer_total
Yes
string
Amount paid by the user.
1600.00
data.amount.payer_refund
Yes
string
Payer's refund amount.
1600.00
data.amount.currency
Yes
string
Currency.
USD
data.amount.refund_fee
No
string
Handling fee.
0.00
requestId
Yes
string
Request trace ID.
fd203616014e4ca8935f08a913ecfcb4

Request example

{"out_trade_no":"test-mnp-order-001","out_refund_no":"test-mnp-order-001-REF001","reason":"","notify_url":"https://example-test.com/callback/refund/mp_test_001","amount":{"refund":"250","total":"6250","currency":"USD"},"req_from":"2","openid":"test_openid_001","merchant_id":"mi_test_merchant_001"}

Response example

{"returnCode":"0","returnMessage":"OK","requestId":"901f09e3f88c4af8a016bde5df5f7f14","data":{"refund_id":"rn_test_vrefund_001","out_refund_no":"test-mnp-order-001-REF001","transaction_id":"tx_test_mnp_001","out_trade_no":"test-mnp-order-001","channel":"ORIGINAL","user_received_account":"","create_time":"2026-07-21T13:13:17+08:00","status":"PROCESSING","amount":{"total":"250.00","refund":"250.00","payer_total":"250.00","payer_refund":"250.00","currency":"USD","refund_fee":"0.00"}}}

5.2.2 Virtual payment refund callback

Path: The value of the TC-Payment-Callback request header used when you apply for a refund via the API in section 5.2.1.
Method: POST

Request parameters

Header parameters:
Parameter
Required
Type
Description
Example value
TC-Timestamp
Yes
string
Timestamp (in seconds).
1787320108
TC-Signature
Yes
string
The signature for invoking signature verification on SAS. SeeSuper App as a Service Signature and Verification.
9c2c715eaad1505e05598dd48a1a2776
TC-ApplicationID
Yes
string
The superapp ID on SAS.
app-abo181jy4f
TC-BackendConfigID
Yes
string
Backend configuration ID of the SAS accessing the superapp, used to distinguish environments. TC-BackendConfigID in the request header when creating an order.
appserver-1
Body parameters:
Parameter
Required
Type
Description
Example value
eventType
Yes
string
Refund status. Valid values: SUCCESS; CLOSED; ABNORMAL.
REFUND.SUCCESS
event
Yes
string
Event identifier, same as eventType.
REFUND.SUCCESS
payload
Yes
string
JSON string containing refund notification data.
{"mch_id":"miea24116372bf17c1e4f9f3b80d6690","transaction_id":"tx20260821183929769285y7pgsczocb","out_trade_no":"870f6efe-ee6e-4502-9539-ec567a27e6be","refund_id":"rn1787309110345vmyihmgkjzdzackvqblf","out_refund_no":"870f6efe-ee6e-4502-9539-ec567a27e6be-REF2266","refund_status":"SUCCESS","success_time":"2026-08-21T18:45:25+08:00","user_received_account":"","amount":{"total":"2000.00","refund":"400.00","payer_total":"2000.00","payer_refund":"400.00","currency":"USD"}}
payEventSig
Yes
string
Payment signature. The pseudo-code of the signature algorithm is as follows: pay_event_sig = to_hex(hmac_sha256(app_key, event + '&' + payload)).
a88ea01994a13232a9de27262cc6825eb7240f97051c01852d8468ba01539c0b
outRefundNo
Yes
string
Merchant refund number.
870f6efe-ee6e-4502-9539-ec567a27e6be-REF226
Parsed payload data structure:
Parameter
Required
Type
Description
Example value
mch_id
Yes
string
Merchant ID.
mi59a93ddccc
transaction_id
Yes
string
Superapp payment transaction ID.
tx_test_001
out_trade_no
Yes
string
Merchant order number.
f49b3e588f1fec899b68
refund_id
Yes
string
Platform refund ID.
rn_test_refund_001
out_refund_no
Yes
string
Merchant refund number.
test_order_001-REF001
refund_status
Yes
string
Refund status. Valid values: SUCCESS; CLOSED; ABNORMAL.
SUCCESS
success_time
No
string
Refund success time.
2026-07-16T17:44:53+08:00
user_received_account
No
string
Account that receives the refund.
-
amount
Yes
object
Refund amount details.
-
amount.total
Yes
string
Total refund amount.
1600.00
amount.currency
Yes
string
Currency.
USD

Response parameters

Parameter
Required
Type
Description
Example value
returnCode
Yes
string
Response code, 0 indicates success.
0
returnMessage
Yes
string
Response information.
OK
data
Yes
string
Response data, OK indicates success.
OK
requestId
Yes
string
Request trace ID.
fd203616014e4ca8935f08a913ecfcb4

5.2.3 Queries virtual payment refunds

Path: /vpay/refund/refunds/query
Method: POST
API description:
This API is used to query the virtual payment refunds.
Request parameters
Query parameters:
Parameter
Required
Type
Description
Example value
pay_sig
Yes
string
Virtual payment signature. For more information, see the paySig signature., uri=/vpay/refund/refunds/query
60f0254ff7fe96a20c27aa385412badc967c7dfdf2b7f062752763bab36d
Body parameters:
Parameter
Required
Type
Description
Example value
out_refund_no
Yes
string
Merchant refund number.
test_order_001-REF001
Response parameters
Parameter
Required
Type
Description
Example value
returnCode
Yes
string
Response code, 0 indicates success.
0
returnMessage
No
string
Response information.
OK
data
Yes
object
Refund detail data.
-
data.refund_id
Yes
string
Platform refund ID.
rn1787302243015e3quk4ra5hrn8n3n9y5l
data.out_refund_no
Yes
string
Merchant refund number.
REF-20260821-085040-4f76d4-0-626393
data.transaction_id
Yes
string
Superapp payment transaction ID.
tx20260819155006145828vlxcyjo81t
data.out_trade_no
Yes
string
Merchant order number.
MP1787125797858c797c4d1
data.channel
Yes
string
Refund channels.
ORIGINAL
data.user_received_account
No
string
Account that receives the refund.
-
data.success_time
No
string
Refund success time.
2026-08-21T16:50:45+08:00
data.create_time
Yes
string
Refund creation time.
2026-08-21T16:50:43+08:00
data.status
Yes
string
Refund status. Valid values: PROCESSING, SUCCESS, CLOSED, ABNORMAL.
SUCCESS
data.amount
Yes
object
Refund amount details.
-
data.amount.total
Yes
string
Total order amount.
1600.00
data.amount.refund
Yes
string
Total refund amount.
1600.00
data.amount.payer_total
Yes
string
Amount paid by the user.
1600.00
data.amount.payer_refund
Yes
string
Payer's refund amount.
1600.00
data.amount.currency
Yes
string
Currency.
USD
data.amount.refund_fee
No
string
Handling fee.
0.00
requestId
Yes
string
Request trace ID.
fd203616014e4ca8935f08a913ecfcb4

Request example

POST /vpay/refund/refunds/query?pay_sig=test_sig_value
{"out_refund_no":"test-mnp-order-001-REF001"}

Response example

{"returnCode":"0","returnMessage":"OK","requestId":"3f07346621694d01b246a545a5c77a00","data":{"refund_id":"rn_test_vrefund_001","out_refund_no":"test-mnp-order-001-REF001","transaction_id":"tx_test_mnp_001","out_trade_no":"test-mnp-order-001","channel":"ORIGINAL","user_received_account":"","success_time":"2026-07-21T20:16:25+08:00","create_time":"2026-07-21T20:14:29+08:00","status":"SUCCESS","amount":{"total":"6250","refund":"250","payer_total":"6250","payer_refund":"250","currency":"USD","refund_fee":0}}}





Help and Support

Was this page helpful?

Help us improve! Rate your documentation experience in 5 mins.

Feedback