tencent cloud

Tencent Cloud Super App as a Service

DocumentationTencent Cloud Super App as a ServiceCode Integration GuideSuperapp ServerAPI List

API List

Download
Focus Mode
Font Size
Last updated: 2026-08-18 10:43:09

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:
Header
Description
TC-ApplicationID
The superapp ID on SAS.
TC-BackendConfigID
Backend configuration ID of the SAS accessing the superapp, used to distinguish environments.
TC-PackageName
The superapp package name on SAS.
TC-Signature
Request signature of the SAS. For signature verification, see Super App as a Service Signature and Verification.
TC-Timestamp
Timestamp (in seconds).
TC-TraceID
Trace ID for distributed tracing.

1. Mini program login APIs

1.1 Checks 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 headers

Request header
Description
Remark
Example
TC-OpenId
openid string, the unique identifier of the user under the mini program.
Encrypted using AES ECB mode and hex-encoded. The key is the SecretKey in Configuration Management .
8d45e4881656d8fb4f97a442423093a5db9ec5691f6e8b17f895ab0fd935c0e7
TC-MiniAppID
MiniAppID string, the unique identifier of the mini program under the superapp.
Encrypted using AES ECB mode and hex-encoded. The key is the SecretKey in Configuration Management .
8dc9708f26a1f5157e66c27892c78a88440d324a986a67fa7acb4d29511c7d18

Request parameters

Name
Type
Required
Description
userId
string
Yes
Anonymized user ID, set by the superapp via the SDK as the unique identifier of the logged-in user.

Response data

Name
Type
Required
Description
returnCode
string
Yes
Response code, 0 indicates success.
returnMessage
string
No
Response information.
data
Boolean
Yes
Indicates whether the user exists.
requestId
string
Yes
Request trace ID.

Request example

{"userId":"test_user_id_001"}

Response example

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

1.2 Gets 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

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

Response data

Name
Type
Required
Description
returnCode
string
Yes
Response code, 0 indicates success.
returnMessage
string
No
Response information.
data
object
Yes
Response data.
data.data
string
Yes
Masked phone number or email returned based on the query type. For example: 158*2850，mu*ng@tencent.com.
data.code
string
Yes
Temporary credential code got for the phone number or email.
requestId
string
Yes
Request trace ID.

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 Gets 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

Name
Type
Required
Description
temporaryCode
string
Yes
Temporary credential code.
userId
string
Yes
Anonymized user ID, set by the superapp via the SDK as the unique identifier of the logged-in user.

Response data

Name
Type
Required
Description
returnCode
string
Yes
Response code, 0 indicates success.
returnMessage
string
No
Response information.
data
string
Yes
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 .
requestId
string
Yes
Request trace ID.

Request example

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

Response example

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

1.4 Gets 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

Name
Type
Required
Description
temporaryCode
string
Yes
Temporary credential code.
userId
string
Yes
Anonymized user ID, set by the superapp via the SDK as the unique identifier of the logged-in user.

Response data

Name
Type
Required
Description
returnCode
string
Yes
Response code, 0 indicates success.
returnMessage
string
No
Response information.
data
string
Yes
User mobile number, 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 .
requestId
string
Yes
Request trace ID.

Request example

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

Response example

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

1.5 Gets user’s nickname

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

Request parameters

Name
Type
Required
Description
userId
string
Yes
Anonymized user ID, set by the superapp via the SDK as the unique identifier of the logged-in user.

Response data

Name
Type
Required
Description
returnCode
string
Yes
Response code, 0 indicates success.
returnMessage
string
No
Response information.
data
string
Yes
User’s nickname.
requestId
string
Yes
Request trace ID.

Request example

{"userId":"test_user_id_001"}

Response example

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

1.6 Gets user’s profile photo

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

Request parameters

Name
Type
Required
Description
userId
string
Yes
Anonymized user ID, set by the superapp via the SDK as the unique identifier of the logged-in user.

Response data

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

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 Receives 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

Name
Type
Required
Description
accountId
string
Yes
The ID of the user to whom the message belongs (same as userId).
messageId
string
Yes
The unique ID of the message.
content
string
Yes
Message content.
dataTime
int
Yes
Timestamp of the message sending time (in seconds).
templateId
string
Yes
The ID of the message template.
mnpId
string
Yes
Mini program appid.
mnpName
string
Yes
Mini program name.
templateTitle
string
Yes
Template title.
state
string
Yes
The type of mini program to navigate to. Valid values: developer: Development version; trial: Preview; formal: Official version. Default value: formal.
page
string
No
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 this parameter is left empty, no navigation occurs.
mnpIcon
string
Yes
Mini program icon.

Response data

Name
Type
Required
Description
returnCode
string
Yes
Response code, 0 indicates success.
returnMessage
string
No
Response information.
data
bool
Yes
Processing result.
requestId
string
Yes
Request trace ID.

Request example

{"messageId":"a75a19fc0aa64e4171f8e856e0b16927","accountId":"test_user_id_001","templateId":"mti_test_template_001","content":"Pay time:2026-07-16 15:04:00","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 Creates 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

Headers
Parameter
Description
TC-Payment-Callback
The callback URL of a successful or failed payment.
TC-MerchantID
The merchant ID bound to the mini program’s superapp on SAS.
TC-UserID
Superapp user login ID.
TC-TradeType
Transaction type: JSAPI for mini program payments.
TC-Platform-UserID
The user openid on SAS.
TC-ApplicationID
The superapp ID on SAS.
TC-Authorization
The signature authentication information. For more information, see Signature and Verification.
Body
Name
Type
Required
Description
appid
string
Yes
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.
description
string
Yes
Product information description, which should be accurately provided and cannot exceed 127 characters.
out_trade_no
string
Yes
Internal order number in the merchant system, must be 10-64 characters long, can only include numbers, uppercase and lowercase letters, _-|*, and must be unique within the same merchant ID.
time_expire
string
Yes
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).
attach
string
No
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.
amount
object
Yes
Order amount.
amount.total
int
Yes
Total order amount, integer (in cents).
amount.currency
string
No
Currency type, a three-letter code compliant with ISO 4217.
payer
object
Yes
Payer information.
payer.openid
string
Yes
User openid on SAS.
detail
object
Yes
Product information.
detail.cost_price
int
No
Original price of the order.
detail.goods_detail
array[object]
Yes
Product list.
detail.goods_detail.merchant_goods_id
string
Yes
Product code provide by the merchant, composed of one or more of the following: Half-width uppercase and lowercase letters, numbers, hyphens, and underscores.
detail.goods_detail.goods_name
string
No
Actual product name.
detail.goods_detail.quantity
int
Yes
Quantity of products purchased by the user.
detail.goods_detail.unit_price
int
Yes
The unit price of the product, integer (in cents).
mchid
string
Yes
Merchant ID.

Response data

Name
Type
Required
Description
returnCode
string
Yes
Response code, 0 indicates success.
returnMessage
string
No
Response information.
data
object
Yes
Response data.
data.prepayId
string
Yes
Unique order ID.
requestId
string
Yes
Request trace ID.

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

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 2.1, informing the merchant that the user has completed the payment.
Path: TC-Payment-Callback, described in the section 2.1
Method: POST
API description:
Mini program order payment callback.

Request parameters

Headers
Parameter
Description
TC-Callback-Serial
The merchant serial number, and the merchant payment public key ID on the superapp's payment (Merchant serial number, merchant certificate).
TC-Signature
TC-Timestamp
Timestamp (in seconds).
TC-Callback-Nonce
-
TC-Callback-Signature
For more information, see Signature and Verification.
TC-ApplicationID
TC-ApplicationID in the request header when creating an order.
TC-BackendConfigID
TC-BackendConfigID in the request header when creating an order.
Body
Name
Type
Required
Description
id
string
Yes
Unique identifier for the callback notification.
create_time
string
Yes
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).
event_type
string
Yes
The superapp's payment callback notification types. Payment success - TRANSACTION.SUCCESS. Payment failure - TRANSACTION.PAYERROR.
resource_type
string
Yes
Type of notification data, fixed as encrypt-resource.
summary
string
Yes
Summary of the callback content from the superapp's payment.
transaction_id
string
No
Superapp payment transaction ID.
pay_mode
string
No
Payment method (for example, Wallet).
out_trade_no
string
Yes
Merchant order number.
resource
object
Yes
Notification resource data.
resource.algorithm
string
Yes
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.
resource.ciphertext
string
Yes
Data ciphertext: The Base64-encoded callback data ciphertext. The merchant is required to decode it using Base64 and decrypt it with the API key.
resource.associated_data
string
No
Additional data for decryption, this field may be empty.
resource.original_type
string
Yes
Original callback type: The object type before encryption, which is transaction.
resource.nonce
string
Yes
Random string involved in decryption.
Decrypted structure of resource.ciphertext data:
Name
Type
Required
Description
transaction_id
string
No
Superapp payment transaction ID.
mch_id
string
Yes
Merchant ID.
out_trade_no
string
Yes
Merchant order number.
appid
string
Yes
Merchant mini program appid.
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.
trade_state_desc
string
Yes
Description of the transaction status.
trade_type
string
Yes
Transaction type, fixed value: JSAPI.
bank_type
string
Yes
User’s payment method, format: bankCode_type (e.g., ICBC_DEBIT). Non-bank payments are unified as OTHERS.
success_time
string
Yes
Payment completion time.
payer
string
Yes
Identifier of the user who made the payment.
attach
string
No
Pass-through data provided during order placement.
amount
object
Yes
Order amount information. See table below.
Amount field description:
Name
Type
Required
Description
total
string
Yes
Total order amount (in cents).
payer_total
string
Yes
The actual amount paid by the user (in cents).
currency
string
Yes
Currency.
payer_currency
string
Yes
The currency used by the user for the payment.

Response data

Name
Type
Required
Description
returnCode
string
Yes
Response code, 0 indicates success.
returnMessage
string
No
Response information.
data
Boolean
Yes
Indicates if the order was closed successfully.
requestId
string
Yes
Request trace ID.

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

Headers
Parameter
Description
TC-Authorization
The signature authentication information. For more information, see Signature and Verification.
Path
Parameter
Description
Required
Description
out_trade_no
Merchant order number.
Yes
-
Query
Parameter
Description
Required
Description
mchid
Merchant ID, provided when the merchant places the order.
Yes
-

Response data

Name
Type
Required
Description
returnCode
string
Yes
Response code, 0 indicates success.
returnMessage
string
No
Response information.
data
object
Yes
Response data.
data.app_id
string
Yes
The mini program appid, provided when the merchant places the order.
data.mchid
string
Yes
Merchant ID, provided when the merchant places the order.
data.out_trade_no
string
Yes
Merchant order number, provided when the merchant places the order.
data.transaction_id
string
No
Superapp payment transaction ID.
data.trade_type
string
No
Returns the transaction type of the current order. Valid values: JSAPI: Mini program payment.
data.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.
data.trade_state_desc
string
Yes
A detailed description of the transaction status.
data.bank_type
string
No
Description of the user's payment method, returned after successful payment. Format: bank code_specific type (DEBIT debit card/CREDIT credit card).
data.attach
string
No
Custom data packet passed by the merchant when creating the order.
data.success_time
string
No
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).
data.payer
object
No
Payer information of the order. It is returned after the order is successfully paid. It is the superapp user ID.
data.amount
object
No
Order amount information.
data.amount.total
string
No
Total order amount.
data.amount.payer_total
string
No
Actual payment amount.
data.amount.currency
string
No
Currency type.
data.amount.payer_currency
string
No
The currency used by the user for the payment.
requestId
string
Yes
Request trace ID.

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 Closes 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

Headers
Parameter
Description
TC-Authorization
The signature authentication information. For more information, see Signature and Verification.
Path
Parameter
Type
Description
Required
Description
out_trade_no
string
Merchant order number.
Yes
-
Body
Parameter
Type
Description
Required
Description
mchid
string
Merchant ID, provided when the merchant places the order.
Yes
-

Response data

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

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 Creates 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

Headers
Parameter
Description
TC-Payment-Callback
The callback URL of a successful or failed payment.
TC-UserID
Superapp user login ID.
TC-MerchantID
The merchant ID bound to the mini program’s superapp on SAS.
TC-Platform-UserID
The user openid on SAS.
body:
Parameter
Type
Description
Required
Remark
signData
string
Original payment string.
Yes
For specific payment parameters, see signData below. The data must be passed in JSON format. '{"mode":"goods","offerId":"123","buyQuantity":1,"env":0,"currencyType":"USD","productId":"testproductId","goodsPrice":10,"outTradeNo":"xxxxxx","attach":"testdata"}'
paySig
string
Payment signature.
Yes
Virtual payment signature. For more information, see the paySig signature.The uri value is fixed to requestMidasPaymentGameItem.
appId
string
The superapp ID on SAS.
Yes
-
miniAppId
string
The mini game appid on SAS.
Yes
-
goodsName
string
Game item name.
Yes
-
orderSource
int
Order source.
Yes
Fixed value: 10.
event
string
Event type.
Yes
Fixed value: minigame_game_pay_goods_deliver_notify.
signData
Parameter
Type
Description
Required
Remark
model
string
Payment type.
Yes
Fixed value: goods.
offerId
string
The merchant ID bound to the mini program’s superapp on SAS.
Yes
-
buyQuantity
int
Purchase quantity.
Yes
Purchase quantity.
currencyType
string
Currency.
Yes
Currency type, a three-letter code compliant with ISO 4217.
productId
string
Virtual item ID.
Yes
Virtual item ID.
goodsPrice
int
Item unit price.
Yes
Item unit price (in cents).
outTradeNo
string
Merchant order number.
Yes
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.
attach
string
Pass-through parameter.
No
Will be passed through and returned in payment callback.

Response data

Name
Type
Required
Description
returnCode
string
Yes
Response code, 0 indicates success.
returnMessage
string
No
Response information.
data
object
Yes
Response data.
data.prepayId
string
Yes
Unique order ID.
requestId
string
Yes
Request trace ID.

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:
Parameter
Description
TC-ApplicationID
The superapp ID on SAS.
TC-BackendConfigID
Backend configuration ID of the SAS accessing the superapp, used to distinguish environments. TC-BackendConfigID in the request header when creating an order.
TC-Signature
The signature for invoking signature verification on SAS. SeeSuper App as a Service Signature and Verification.
TC-Timestamp
Timestamp (in seconds).
body:
Parameter
Type
Required
Description
EventType
string
Yes
Message type. Payment success - TRANSACTION.SUCCESS. Payment failure - TRANSACTION.PAYERROR.
event
string
Yes
The event when creating an order.
payModel
string
No
Payment methods: Wallet, bankcard, third party
payload
string
Yes
Detailed content in JSON format. See the Payload table below. (All message content is formatted as JSON for unified signature verification.)
payEventSig
string
Yes
For more information, see PayEventSig signature.The value of event is the event passed when creating the order in section 3.1.
transactionId
string
No
Superapp payment transaction ID.
outTradeNo
string
Yes
Merchant order number.
Payload
Parameter
Type
Description
Required
OpenId
string
The openid.
Yes
OutTradeNo
string
Merchant order number.
Yes
GoodsInfo
object
The virtual item info.
Yes
PayInfo
object
Payment information.
Yes
GoodsInfo
Parameter
Type
Description
Required
ProductId
string
Game item ID.
Yes
Quantity
number
Quantity of game items purchased.
Yes
OrigPrice
number
Original game item price (in cents).
Yes
ActualPrice
string
Actual paid price (in cents).
Yes
Attach
string
Pass-through data.
Yes
OrderSource
number
Order source.
Yes
PayInfo
Parameter
Type
Description
Required
MchOrderNo
string
Merchant ID, provided when the merchant places the order.
Yes
PaidTime
number
Payment timestamp, in seconds.
No
TransactionId
string
Superapp payment transaction ID.
No

Response data

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

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 Creates 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

Headers
Parameter
Description
TC-Payment-Callback
The callback URL of a successful or failed payment.
TC-UserID
Superapp user login ID.
TC-MerchantID
The merchant ID bound to the mini program’s superapp on SAS.
TC-Platform-UserID
The user openid on SAS.
body
Parameter
Type
Description
Required
signData
string
Original payment string. For specific payment parameters, see signData below. The data must be passed in JSON format. '{"offerId":"123","buyQuantity":1,"env":0,"currencyType":"USD","productId":"testproductId","goodsPrice":10,"outTradeNo":"xxxxxx","attach":"testdata"}'
Yes
paySig
string
Virtual payment signature. For more information, see the paySig signature.The uri value is fixed to requestVirtualPayment.
Yes
appId
string
The superapp ID on SAS.
Yes
miniAppId
string
The mini program appid on SAS.
Yes
goodsName
string
Game item name.
Yes
orderSource
int
Order source 10: an order placed within a mini program short drama.
Yes
event
string
When OrderSource=10, it is fixed as: xpay_goods_deliver_notify.
Yes
signData：
Parameter
Type
Description
Required
Description
model
string
Payment type.
Yes
Fixed value: goods.
offerId
string
The merchant ID bound to the mini program’s superapp on SAS.
Yes
-
buyQuantity
int
Purchase quantity.
Yes
Purchase quantity.
currencyType
string
Currency.
Yes
Currency type, a three-letter code compliant with ISO 4217.
productId
string
Virtual item ID.
Yes
Virtual item ID.
goodsPrice
int
Item unit price.
Yes
Item unit price (in cents).
outTradeNo
string
Merchant order number.
Yes
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.
attach
string
Pass-through parameter.
No
Will be passed through and returned in payment callback.

Response data

Name
Type
Required
Description
returnCode
string
Yes
Response code, 0 indicates success.
returnMessage
string
No
Response information.
data
object
Yes
Response data.
data.prepayId
string
Yes
Unique order ID.
requestId
string
Yes
Request trace ID.

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

Parameter
Type
Description
Required
eventType
string
Message type. Payment success - TRANSACTION.SUCCESS. Payment failure - TRANSACTION.PAYERROR.
Yes
event
string
Event type. The event when creating an order.
Yes
payMode
string
Payment methods: Wallet, bankcard, third party
No
payload
string
Detailed content in JSON format. See the Payload table below. (All message content is formatted as JSON for unified signature verification.)
Yes
payEventSig
string
For more information, see PayEventSig signature.The value of event is the event passed when creating the order in section 4.1.
Yes
transactionId
string
Superapp payment transaction ID.
No
outTradeNo
string
Merchant order number.
Yes
payload
Parameter
Type
Description
Required
OpenId
string
The user ID on SAS. It is TC-Platform-UserID in the header when placing an order.
Yes
OutTradeNo
string
Order number.
Yes
GoodsInfo
object
The virtual item info.
Yes
PayInfo
object
Payment information.
Yes
GoodsInfo
Parameter
Type
Description
Required
ProductId
string
Game item ID.
Yes
Quantity
number
Quantity of game items purchased.
Yes
OrigPrice
number
Original game item price (in cents).
Yes
ActualPrice
string
Actual paid price (in cents).
Yes
Attach
string
Pass-through data.
Yes
OrderSource
number
Order source. Valid values: 1: In-game.
Yes
PayInfo
Parameter
Type
Description
Required
MchOrderNo
string
Merchant ID, provided when the merchant places the order.
Yes
PaidTime
number
Payment timestamp, in seconds.
No
TransactionId
string
Superapp payment transaction ID.
No

Response data

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

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 Initiates 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
Headers
Parameter
Type
Description
TC-Payment-Callback
string
Refund result callback URL.
TC-Authorization
string
The signature authentication information. For more information, see Signature and Verification.
Body
Parameter
Type
Required
Description
transaction_id
string
No
Transaction ID on the superapp (Either this or out_trade_no must be provided.)
out_trade_no
string
No
Merchant order number, either this or transaction_id required.
out_refund_no
string
Yes
Unique refund order number per merchant.
reason
string
No
Refund reason.
refund_method
string
No
Refund method: Original, bankcard, wallet.
channel
string
No
Refund channel: Original, balance.
refund_source
string
No
Refund origin. Valid values: 1: Customer service; 2 User; 3 Others.
amount
object
Yes
Refund amount details.
amount.refund
int64
Yes
Refund amount (in cents).
amount.total
int64
Yes
Total order amount (in cents).
amount.currency
string
Yes
Currency, e.g., USD.
goods_detail
array
No
Refunded product details.
goods_detail[].merchant_goods_id
string
Yes
Merchant's product code.
goods_detail[].goods_name
string
No
Product name.
goods_detail[].unit_price
int64
Yes
Product unit price (in cents).
goods_detail[].refund_amount
int64
Yes
Product refund amount (in cents).
goods_detail[].refund_quantity
int
Yes
Number of items refunded.
notify_url
string
Yes
Refund result notification URL.
merchant_id
string
Yes
Merchant ID.
Response data
Name
Type
Required
Description
returnCode
string
Yes
Response code, 0 indicates success.
returnMessage
string
No
Response information.
data
object
Yes
Refund response data.
data.refund_id
string
Yes
Platform refund ID.
data.out_refund_no
string
Yes
Merchant refund number.
data.transaction_id
string
Yes
Superapp payment transaction ID.
data.out_trade_no
string
Yes
Merchant order number.
data.channel
string
Yes
Refund channels.
data.user_received_account
string
Yes
Account that receives the refund.
data.success_time
string
No
Refund success time.
data.create_time
string
Yes
Refund creation time.
data.status
string
Yes
Refund status. Valid values: Success, closed, abnormal.
data.amount
object
Yes
Refund amount details.
data.amount.total
int64
Yes
Total order amount (in cents).
data.amount.refund
int64
Yes
Refund amount (in cents).
data.amount.payer_total
int64
Yes
Amount paid by user (in cents).
data.amount.payer_refund
int64
Yes
Refund amount for the user (in cents).
data.amount.currency
string
Yes
Currency.
data.amount.refund_fee
int64
Yes
Refund fee (in cents).
requestId
string
Yes
Request trace ID.

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 Queries 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
Headers
Parameter
Description
TC-Authorization
The signature authentication information. For more information, see Signature and Verification.
Path
Parameter
Type
Description
Required
Description
out_refund_no
string
Merchant refund number.
Yes
-
Response data
Name
Type
Required
Description
returnCode
string
Yes
Response code, 0 indicates success.
returnMessage
string
No
Response information.
data
object
Yes
Refund detail data.
data.refund_id
string
Yes
Platform refund ID.
data.out_refund_no
string
Yes
Merchant refund number.
data.transaction_id
string
Yes
Superapp payment transaction ID.
data.out_trade_no
string
Yes
Merchant order number.
data.channel
string
Yes
Refund channels.
data.user_received_account
string
Yes
Account that receives the refund.
data.success_time
string
No
Refund success time.
data.create_time
string
Yes
Refund creation time.
data.status
string
Yes
Refund status. Valid values: Success, closed, abnormal.
data.amount
object
Yes
Refund amount details.
data.amount.total
int64
Yes
Total order amount (in cents).
data.amount.refund
int64
Yes
Refund amount (in cents).
data.amount.payer_total
int64
Yes
Amount paid by user (in cents).
data.amount.payer_refund
int64
Yes
Refund amount for the user (in cents).
data.amount.currency
string
Yes
Currency.
data.amount.refund_fee
int64
Yes
Refund fee (in cents).
requestId
string
Yes
Request trace ID.

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 when you apply for a refund via the API in section 5.1.1.
Path： Value of the TC-Payment-Callback header in the refund request.
Method： POST
Request parameters
Headers
Parameter
Description
TC-Callback-Serial
Superapp merchant certificate serial number.
TC-Callback-Signature
Signature value for verification.
TC-Timestamp
Timestamp (in seconds).
TC-Callback-Nonce
Random string for verification.
TC-Signature
The signature for invoking signature verification on SAS. SeeSuper App as a Service Signature and Verification.
TC-ApplicationID
The superapp ID on SAS.
TC-BackendConfigID
Backend configuration ID of the SAS accessing the superapp, used to distinguish environments. TC-BackendConfigID in the request header when creating an order.
Body
Name
Type
Required
Description
id
string
Yes
Unique notification ID.
create_time
string
Yes
Notification creation time, RFC3339 format.
event_type
string
Yes
REFUND.SUCCESS / REFUND.CLOSED / REFUND.ABNORMAL
resource_type
string
Yes
Fixed value: encrypt-resource.
summary
string
Yes
Notification summary.
out_refund_no
string
Yes
Merchant refund number.
resource
object
Yes
Encrypted notification data.
resource.algorithm
string
Yes
Fixed value: AEAD_AES_256_GCM.
resource.original_type
string
Yes
Fixed value: refund.
resource.ciphertext
string
Yes
Base64-encoded encrypted data, decrypt with symmetric key.
resource.associated_data
string
No
Additional data for decryption.
resource.nonce
string
Yes
Random string for decryption.
Decrypted structure of resource.ciphertext data:
Name
Type
Required
Description
mch_id
string
Yes
Merchant ID.
transaction_id
string
Yes
Superapp payment transaction ID.
out_trade_no
string
Yes
Merchant order number.
refund_id
string
Yes
Platform refund ID.
out_refund_no
string
Yes
Merchant refund number.
refund_status
string
Yes
Refund status. Valid values: Success, closed, abnormal.
success_time
string
No
Refund success time (returned only if SUCCESS).
user_received_account
string
Yes
Account that receives the refund.
amount
object
Yes
Refund amount details.
amount.total
string
Yes
Total order amount (in cents).
amount.refund
string
Yes
Refund amount (in cents).
amount.payer_total
string
Yes
Amount paid by user (in cents).
amount.payer_refund
string
Yes
Refund amount for the user (in cents).
amount.currency
string
Yes
Currency.
Response data
Name
Type
Required
Description
returnCode
string
Yes
Response code, 0 indicates success.
returnMessage
string
No
Response information.
data
string
Yes
Response data, OK indicates success.
requestId
string
Yes
Request trace ID.

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 Request a refund

Path： /vpay/refund/refunds
Method： POST
API description: Initiates a refund request for a completed payment order in a mini program or mini game.
Request parameters
Headers
Parameter
Description
TC-Payment-Callback
Refund result callback URL.
TC-MerchantID
The merchant ID bound to the mini program’s superapp on SAS.
Query Parameters
Parameter
Type
Description
Required
Description
pay_sig
string
Virtual payment signatures.
Yes
Virtual payment signature. For more information, see the paySig signature.，uri=/vpay/refund/refunds
Body
Parameter
Type
Required
Description
openid
string
No
User openid who placed the order.
transaction_id
string
No
Transaction ID on the superapp (Either this or out_trade_no must be provided.)
out_trade_no
string
No
Merchant order number, either this or transaction_id required.
out_refund_no
string
Yes
Merchant refund number.
reason
string
No
Refund reason.
req_from
string
No
Refund origin. Valid values: 1: Customer service; 2 User; 3 Others.
amount
object
Yes
Refund amount details.
amount.refund
int64
Yes
Refund amount (in cents).
amount.total
int64
Yes
Total order amount (in cents).
amount.currency
string
Yes
Currency.
notify_url
string
Yes
Refund result notification URL.
merchant_id
string
Yes
Merchant ID.
Response data
Name
Type
Required
Description
returnCode
string
Yes
Response code, 0 indicates success.
returnMessage
string
No
Response information.
data
object
Yes
Refund response data.
data.refund_id
string
Yes
Platform refund ID.
data.out_refund_no
string
Yes
Merchant refund number.
data.transaction_id
string
Yes
Superapp payment transaction ID.
data.out_trade_no
string
Yes
Merchant order number.
data.channel
string
Yes
Refund channels.
data.user_received_account
string
Yes
Account that receives the refund.
data.success_time
string
No
Refund success time.
data.create_time
string
Yes
Refund creation time.
data.status
string
Yes
Refund status. Valid values: Success, closed, abnormal.
data.amount
object
Yes
Refund amount details.
data.amount.total
int64
Yes
Total order amount (in cents).
data.amount.refund
int64
Yes
Refund amount (in cents).
data.amount.payer_total
int64
Yes
Amount paid by user (in cents).
data.amount.payer_refund
int64
Yes
Refund amount for the user (in cents).
data.amount.currency
string
Yes
Currency.
data.amount.refund_fee
int64
Yes
Refund fee (in cents).
requestId
string
Yes
Request trace ID.

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,"refund":250,"payer_total":250,"payer_refund":250,"currency":"USD","refund_fee":0}}}

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
Headers
Parameter
Description
TC-Timestamp
Timestamp (in seconds).
TC-Signature
The signature for invoking signature verification on SAS. SeeSuper App as a Service Signature and Verification.
TC-ApplicationID
The superapp ID on SAS.
TC-BackendConfigID
Backend configuration ID of the SAS accessing the superapp, used to distinguish environments. TC-BackendConfigID in the request header when creating an order.
Body
Name
Type
Required
Description
eventType
string
Yes
Refund status. Valid values: Success, closed, abnormal.
event
string
Yes
Event identifier, same as eventType.
payload
string
Yes
JSON string containing refund notification data.
payEventSig
string
Yes
Payment signature. The pseudo-code of the signature algorithm is as follows: pay_event_sig = to_hex(hmac_sha256(app_key, event + '&' + payload)).
outRefundNo
string
Yes
Merchant refund number.
Parsed payload data structure:
Name
Type
Required
Description
mch_id
string
Yes
Merchant ID.
transaction_id
string
Yes
Superapp payment transaction ID.
out_trade_no
string
Yes
Merchant order number.
refund_id
string
Yes
Platform refund ID.
out_refund_no
string
Yes
Merchant refund number.
refund_status
string
Yes
Refund status. Valid values: Success, closed, abnormal.
success_time
string
No
Refund success time.
user_received_account
string
Yes
Account that receives the refund.
amount
object
Yes
Refund amount details.
Response data
Name
Type
Required
Description
returnCode
string
Yes
Response code, 0 indicates success.
returnMessage
string
No
Response information.
data
string
Yes
Response data, OK indicates success.
requestId
string
Yes
Request trace ID.

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
Type
Description
Required
Description
pay_sig
string
Virtual payment signature. For more information, see the paySig signature.，uri=/vpay/refund/refunds/query
Yes
-
Body
Parameter
Type
Required
Description
out_refund_no
string
Yes
Merchant refund number.
Response data
Name
Type
Required
Description
returnCode
string
Yes
Response code, 0 indicates success.
returnMessage
string
No
Response information.
data
object
Yes
Refund detail data.
data.refund_id
string
Yes
Platform refund ID.
data.out_refund_no
string
Yes
Merchant refund number.
data.transaction_id
string
Yes
Superapp payment transaction ID.
data.out_trade_no
string
Yes
Merchant order number.
data.channel
string
Yes
Refund channels.
data.user_received_account
string
Yes
Account that receives the refund.
data.success_time
string
No
Refund success time.
data.create_time
string
Yes
Refund creation time.
data.status
string
Yes
Refund status. Valid values: Success, closed, abnormal.
data.amount
object
Yes
Refund amount details.
data.amount.total
int64
Yes
Total order amount (in cents).
data.amount.refund
int64
Yes
Refund amount (in cents).
data.amount.payer_total
int64
Yes
Amount paid by user (in cents).
data.amount.payer_refund
int64
Yes
Refund amount for the user (in cents).
data.amount.currency
string
Yes
Currency.
data.amount.refund_fee
int64
Yes
Refund fee (in cents).
requestId
string
Yes
Request trace ID.

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}}}



Previous Topic: Super App as a Service Signature and VerificationNext Topic: GUID Generation Rules

Help and Support

Was this page helpful?

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

Feedback

Search
    Enter keywords to search documentation