tencent cloud

Tencent Cloud Super App as a Service

DocumentationTencent Cloud Super App as a ServiceCode Integration GuideSuperapp ServerAPI List

API List

PDF
Focus Mode
Font Size
Last updated: 2026-04-29 11:34:06

1. Mini program login APIs

1.1 Check whether the user exists

Path: /user/checkUser
Method: POST
API description:
Checks if the user exists based on the superapp's user ID.

Request header information (unique to this API)

Request header
Description
Description
Example
TC-OpenId
User's unique OpenId within the mini program.
8d45e4881656d8fb4f97a442423093a5db9ec5691f6e8b17f895ab0fd935c0e7
TC-MiniAppID
Unique MiniAppID under the app.
8dc9708f26a1f5157e66c27892c78a88440d324a986a67fa7acb4d29511c7d18

Request parameters

Body
Name
Type
Required
Description
userId
string
True
The anonymized user ID, which is generated by the superapp using the SDK and is used to temporarily request the generation of an anonymized openid from the superapp's server. It is temporarily used when the mini program needs to obtain the openid.

Response parameters

Name
Type
Required
Note
returnCode
string
True
Response code, 0 indicates success.
returnMessage
string
False
Response message.
data
Boolean
True
Whether the user exists.
requestId
string
True
Request trace ID.

1.2 Get user temporary information code

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

Request parameters

Body
Name
Type
Required
Description
type
string
True
The type of information. Valid values: email, phone.
userId
string
True
The anonymized user ID, which is generated by the superapp using the SDK and is used to temporarily request the generation of an anonymized openid from the superapp's server. It is temporarily used when the mini program needs to obtain the openid.

Response parameters

Name
Type
Required
Description
returnCode
string
True
Response code, 0 indicates success.
returnMessage
string
False
Response information.
data
object
True
Response data.
data.data
string
True
Returns the masked mobile number or email based on the query type, e.g., 158****2850, mu****ng@tencent.com.
data.code
string
True
Gets the temporary credential code for the mobile number or email.
requestId
string
True
Request trace ID.

1.3 Get user email

Path: /user/getUserEmail
Method: POST
API description:
Gets the user's email based on the temporary credential code.

Request parameters

Body
Name
Type
Required
Description
temporaryCode
string
True
Temporary credential code.
userId
string
True
The anonymized user ID, which is generated by the superapp using the SDK and is used to temporarily request the generation of an anonymized openid from the superapp's server. It is temporarily used when the mini program needs to obtain the openid.

Response parameters

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

1.4 Get user’s mobile number

Path: /user/getUserPhoneNumber
Method: POST
API description:
Gets the user's mobile number based on the temporary credential code.

Request parameters

Body
Name
Type
Required
Description
temporaryCode
string
True
Temporary credential code.
userId
string
True
The anonymized user ID, which is generated by the superapp using the SDK and is used to temporarily request the generation of an anonymized openid from the superapp's server. It is temporarily used when the mini program needs to obtain the openid.

Response parameters

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

1.5 Get user’s nickname

Path: /user/getUserNick
Method: POST
API description:
Retrieves the user nickname.

Request parameters

Body
Name
Type
Required
Description
userId
string
True
The anonymized user ID, which is generated by the superapp using the SDK and is used to temporarily request the generation of an anonymized openid from the superapp's server. It is temporarily used when the mini program needs to obtain the openid.

Response parameters

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

1.6 Get user’s profile photo

Path: /user/getUserAvatar
Method: POST
API description:
Retrieves the user profile photo.

Request parameters

Body
Name
Type
Required
Description
userId
string
True
The anonymized user ID, which is generated by the superapp using the SDK and is used to temporarily request the generation of an anonymized openid from the superapp's server. It is temporarily used when the mini program needs to obtain the openid.

Response parameters

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

1.7 Receive subscription messages

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

Request parameters

Body
Name
Type
Required
Description
AccountId
string
True
The owner user ID of the message (same as UserId).
MessageId
string
True
The unique ID of the message.
Content
string
True
Message content.
DataTime
int
True
Timestamp of the message sending time (in seconds).
TemplateId
string
True
The ID of the message template.
MnpId
string
True
Mini program appid
MnpName
string
True
Mini program name.
TemplateTitle
string
True
Template title.
State
string
True
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.
Component event handler functions can also be defined in the Page
string
True
The page to navigate to when the template card is clicked. This must be a page within the mini program.
Parameters can be included (e.g. index?foo=bar). If not provided, the template will not have a navigation link.
MnpIcon
string
True
Mini program icon.

Response parameters

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

2. Mini program payment APIs

2.1 Create a mini program order

Path: /v3/pay/transactions/jsapi
Method: POST
API description:
Creates a mini program order.

Request parameters

Headers
Parameter
Description
Required
Description
TC-Payment-Callback
The callback URL of a successful or failed payment.
True
URL for payment callback notification, POST request.
TC-MerchantID
The merchant ID bound to the mini program’s superapp on SAS.
True
Merchant ID, the merchant's unique identifier within the superapp payment system.
TC-UserID
Superapp user login ID.
True
-
TC-TradeType
Transaction type.
True
JSAPI: Mini program payment.
TC-Platform-UserID
The user openid on SAS.
True
-
TC-ApplicationID
The superapp ID on SAS.
True
-
Authorization
Signature authentication information.
True
Body
Name
Type
Required
Description
appid
string
True
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
True
The product information description, which should be accurately provided and cannot exceed 127 characters.
out_trade_no
string
True
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.
time_expire
string
True
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 must follow the RFC3339 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
False
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
True
Order amount.
amount.total
int
True
Total order amount, integer (in cents).
amount.currency
string
False
Currency type, a three-letter code compliant with ISO 4217.
payer
object
True
Payer information.
payer.openid
string
True
A unique identifier for each user within a single merchant's mini program appid. The user's openid must be obtained before placing an order. For details, see Mini Program Login.
detail
object
True
Product information.
detail.cost_price
int
False
Original price of the order.
detail.goods_detail
array[object]
True
Product list.
detail.goods_detail.merchant_goods_id
string
True
Product code provided 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
False
Actual product name.
detail.goods_detail.quantity
int
True
Quantity of products purchased by the user.
detail.goods_detail.unit_price
int
True
The unit price of the product, integer (in cents).

Response parameters

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

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
Required
Description
TC-Callback-Serial
Superapp merchant certificate serial number.
True
The merchant serial number, and the merchant payment public key ID on the superapp's payment (Merchant serial number, merchant certificate).
TC-Signature
The signature for invoking signature verification on SAS.
True
TC-Timestamp
Timestamp for signature verification, in seconds.
True
-
TC-Callback-Nonce
Random string for verification.
True
-
TC-Callback-OutTradeNo
Merchant order number.
True
-
TC-Callback-Signature
Signature value for callback verification.
True
TC-ApplicationID
The superapp ID on SAS.
True
TC-ApplicationID in the request header when creating an order.
Body
Name
Type
Required
Description
id
string
True
Unique identifier for the callback notification.
create_time
string
True
Notification creation time: It follows the RFC3339 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
True
The superapp's payment callback notification types.
Payment success - TRANSACTION.SUCCESS.
Payment failure - TRANSACTION.PAYERROR.
resource_type
string
True
Type of notification data, fixed as encrypt-resource.
summary
string
True
Summary of the callback content from the superapp's payment.
Resource
object
True
Notification resource data.
resource.algorithm
string
True
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
True
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
False
Additional data for decryption, this field may be empty.
resource.original_type
string
True
Original callback type: The object type before encryption, which is transaction.
resource.nonce
string
True
Random string involved in decryption.
Decrypted structure of resource.ciphertext data:
Name
Type
Required
Description
transaction_id
string
True
Platform payment order ID.
mch_id
string
True
Merchant ID.
out_trade_no
string
True
Merchant order number.
appid
string
True
Merchant mini program appid.
trade_state
string
True
Transaction status, possible values:
SUCCESS: Payment successful
REFUND: Refund in process
NOTPAY: Not paid
CLOSED: Closed
REVOKED: Revoked
USERPAYING: Payment in process
PAYERROR: Payment failed
trade_state_desc
string
True
Description of the transaction status.
trade_type
string
True
Transaction type, fixed value: JSAPI.
bank_type
string
True
User’s payment method, format: bankCode_type (e.g., ICBC_DEBIT). Non-bank payments are unified as OTHERS.
success_time
string
True
Payment completion time.
payer
string
True
Identifier of the user who made the payment.
attach
string
False
Pass-through data provided during order placement.
amount
object
True
Order amount information. See table below.
Amount field description:
Name
Type
Required
Description
total
string
True
Total order amount (in cents).
payer_total
string
True
The actual amount paid by the user (in cents).
currency
string
True
Currency.
payer_currency
string
True
The currency used by the user for the payment.

Response parameters

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

2.3 Query orders by the order number

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

Request parameters

Headers
Parameter
Description
Required
Description
Authorization
Signature authentication information.
True
Path
Parameter
Description
Required
Description
out_trade_no
Merchant order number.
True
-
Query
Parameter
Description
Required
Description
mchid
Merchant ID, provided when the merchant places the order.
True
-

Response parameters

Name
Type
Required
Description
returnCode
string
True
Response code, 0 indicates success.
returnMessage
string
False
Response information.
data
object
True
Response data.
data.app_id
string
True
The mini program appid, provided when the merchant places the order.
data.mchid
string
True
Merchant ID, provided when the merchant places the order.
data.out_trade_no
string
True
Merchant order number, provided when the merchant places the order.
data.transaction_id
string
True
Unique identifier of the order on the superapp's payment, returned after successful payment.
data.trade_type
string
False
Transaction type of the current order, possible values:
JSAPI: Mini program payment.
data.trade_state
string
True
Transaction status, possible values:
SUCCESS: Payment successful
REFUND: Refund in process
NOTPAY: Not paid
CLOSED: Closed
REVOKED: Revoked
USERPAYING: Payment in process
PAYERROR: Payment failed
data.trade_state_desc
string
True
A detailed description of the transaction status.
data.bank_type
string
False
Description of the user's payment method, returned after successful payment. Format: bank code_specific type (DEBIT debit card/CREDIT credit card).
data.success_time
string
False
The time when the user completes the payment for the order. This parameter is returned after the order is successfully paid.
Format: Follow the RFC3339 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
False
Information about the payer. The superapp user ID will be returned after the order is successfully paid.
data.amount
object
False
Order amount.
data.amount.total
string
False
Total order amount.
data.amount.payer_total
string
False
The actual amount paid by the user.
data.amount.currency
string
False
Currency type.
data.amount.payer_currency
string
False
The currency used by the user for the payment.
requestId
string
True
Request trace ID.



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:
Queries orders by the merchant order number.

Request parameters

Headers
Parameter
Type
Description
Required
Description
Authorization
string
Signature authentication information.
True
Path
Parameter
Type
Description
Required
Description
out_trade_no
string
Merchant order number.
True
-
Body
Parameter
Type
Description
Required
Description
mchid
string
Merchant ID, provided when the merchant places the order.
True
-

Response parameters

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

3. Mini game virtual payment APIs

3.1 Create a virtual payment order in the mini game

Path:/requestMidasPaymentGameItem
Method: POST
API description:
Creates a virtual payment order in the mini game.

Request parameters

Headers
Parameter
Type
Description
Required
TC-Payment-Callback
string
The callback URL of a successful or failed payment.
True
TC-UserID
string
Superapp user login ID.
True
TC-ApplicationID
string
The superapp ID on SAS.
True
TC-MerchantID
string
The merchant ID bound to the mini program’s superapp on SAS.
True
TC-Platform-UserID
string
The user openid on SAS.
True
body:
Parameter
Type
Description
Required
Description
SignData
string
Original payment string.
True
For specific payment parameters, see signData below. The data must be passed in JSON format.
Example for signData:
'{"mode":"goods","offerId":"123","buyQuantity":1,"env":0,"currencyType":"USD","productId":"testproductId","goodsPrice":10,"outTradeNo":"xxxxxx","attach":"testdata"}'
PaySig
string
Payment signature.
True
The pay_sig parameter uses a signature algorithm that signs the payment request with the AppKey obtained from the superapp. This indicates that the request is initiated by the developer’s server-side payment module. The signature algorithm pseudocode is as follows:
paySig = to_hex(hmac_sha256(appKey,'requestMidasPaymentGameItem' + '&' + signData))
AppId
string
The superapp ID on SAS.
True
Superapp ID.
MiniAppId
string
The mini game appid on SAS.
True
Mini game appid.
GoodsName
string
Game item name.
True
The name of the purchased game item.
OrderSource
int
Order source.
True
Order source 1: In-game.
Event
string
Event type.
True
When OrderSource=1, it is fixed as:
minigame_game_pay_goods_deliver_notify
SignData:
Parameter
Type
Description
Required
Description
buyQuantity
int
Purchase quantity.
True
Purchase quantity.
currencyType
string
Currency.
True
Currency type, a three-letter code compliant with ISO 4217.
productId
string
Virtual item ID.
True
Virtual item ID.
goodsPrice
int
Item unit price.
True
Item unit price (in cents).
outTradeNo
string
Merchant order number.
True
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
The pass-through parameter.
False
Will be passed through and returned in payment callback.

Response parameters

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

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
Type
Description
Required
TC-ApplicationID
string
The superapp ID on SAS.
True
TC-Signature
string
The signature for invoking signature verification on SAS. See Super App as a Service Signature and Verification
True
TC-Timestamp
string
Timestamp for signature verification, in seconds.
True
body:
Parameter
Type
Description
Required
EventType
string
Message type. Payment success - TRANSACTION.SUCCESS.
Payment failure - TRANSACTION.PAYERROR.
True
Event
string
The event when creating an order.
True
PayModel
string
Payment methods: Wallet, bankcard, third party
True
Payload
string
Detailed content in JSON format. See the Payload table below. (All message content is formatted as JSON for unified signature verification.)
True
PayEventSig
string
Payment signature. For details, see Virtual payment callback signature
True
Payload
Parameter
Type
Description
Required
OpenId
string
The OpenID.
True
OutTradeNo
string
Merchant order number.
True
GoodsInfo
object
The virtual item info.
True
TransactionId
string
The payment transaction ID.
True
GoodsInfo
Parameter
Type
Description
Required
ProductId
string
Game item ID identifier.
True
Quantity
number
Quantity of game items purchased.
True
OrigPrice
number
Original game item price (in cents).
True
ActualPrice
number
Actual paid price (in cents).
True
Attach
string
Pass-through data.
True
OrderSource
number
Order source.
True

Response parameters

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

4. Mini program virtual payment APIs

4.1 Create a virtual payment order in the mini program

Path:/requestVirtualPayment
Method: POST
API description:
Creates a virtual payment order in the mini program.

Request parameters

Headers
Parameter
Type
Description
Required
TC-Payment-Callback
string
The callback URL of a successful or failed payment.
True
TC-UserID
string
Superapp user login ID.
True
TC-ApplicationID
string
The superapp ID on SAS.
True
TC-MerchantID
string
The merchant ID bound to the mini program’s superapp on SAS.
True
TC-Platform-UserID
string
The user openid on SAS.
True
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.
Example for signData:
'{"offerId":"123","buyQuantity":1,"env":0,"currencyType":"USD","productId":"testproductId","goodsPrice":10,"outTradeNo":"xxxxxx","attach":"testdata"}'
True
PaySig
string
Payment signature. The pay_sig parameter uses a signature algorithm that signs the payment request with the AppKey obtained from the superapp. This indicates that the request is initiated by the developer’s server-side payment module. The signature algorithm pseudocode is as follows:
paySig = to_hex(hmac_sha256(appKey,'requestVirtualPayment' + '&' + signData))
True
AppId
string
The superapp ID on SAS.
True
MiniAppId
string
The mini program appid on SAS.
True
GoodsName
string
Game item name.
True
OrderSource
int
Order source 10: an order placed within a mini program short drama.
True
Event
string
When OrderSource=10, it is fixed as: xpay_goods_deliver_notify
True
SignData:
Parameter
Type
Description
Required
Description
buyQuantity
int
Purchase quantity.
True
Purchase quantity.
currencyType
string
Currency.
True
Currency type, a three-letter code compliant with ISO 4217.
productId
string
Virtual item ID.
True
Virtual item ID.
goodsPrice
int
Item unit price.
True
Item unit price (in cents).
outTradeNo
string
Merchant order number.
True
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
The pass-through parameter.
False
Will be passed through and returned in payment callback.

Response parameters

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

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.
True
Event
string
Event type. The event when creating an order.
True
PayModel
string
Payment methods: Wallet, bankcard, third party
True
Payload
string
Detailed content in JSON format. See the Payload table below. (All message content is formatted as JSON for unified signature verification.)
True
PayEventSig
string
Payment signature. For details, see Virtual payment callback signature
True
Payload
Parameter
Type
Description
Required
OpenId
string
The user ID on SAS. It is TC-Platform-UserID in the header when placing an order.
True
OutTradeNo
string
Order number.
True
GoodsInfo
object
The virtual item info.
True
PayInfo
object
Payment information.
True
GoodsInfo
Parameter
Type
Description
Required
ProductId
string
Game item ID identifier.
True
Quantity
number
Quantity of game items purchased.
True
OrigPrice
number
Original game item price (in cents).
True
ActualPrice
number
Actual paid price (in cents).
True
Attach
string
Pass-through data.
True
OrderSource
number
1 In-game order.
True
PayInfo
Parameter
Type
Description
Required
MchOrderNo
string
Merchant ID, provided when the merchant places the order.
True
PaidTime
number
Payment timestamp, in seconds.
True
TransactionId
string
The payment transaction ID.
True

Response parameters

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

5. Refund API

5.1 Standard payment refund

5.1.1 Create refund request

Path: /spay/refund/refunds
Method: POST
API description: Initiates a refund request for a completed standard payment order.
Request parameters
Headers
Parameter
Type
Description
Required
Description
TC-Payment-Callback
string
Refund result callback URL.
True
Notification URL for refund completion, POST request.
TC-ApplicationID
string
The superapp ID on SAS.
True
-
Authorization
string
Signature authentication information.
True
Body
Parameter
Type
Required
Description
transaction_id
string
False
Platform payment order number, either this or out_trade_no required.
out_trade_no
string
False
Merchant order number, either this or transaction_id required.
out_refund_no
string
True
Unique refund order number per merchant.
reason
string
False
Reason for refund
refund_method
string
False
Refund method: ORIGINAL, BANKCARD, WALLET.
channel
string
False
Refund channel: ORIGINAL, BALANCE.
refund_source
string
False
Refund source:
1. Customer service agent
2. User-initiated
3. Other
amount
object
True
Refund amount details.
amount.refund
int64
True
Refund amount (in cents).
amount.total
int64
True
Total order amount (in cents).
amount.currency
string
True
Currency, e.g., USD.
goods_detail
array
False
Refunded product details.
goods_detail[].merchant_goods_id
string
True
Merchant's product code.
goods_detail[].goods_name
string
False
Product name.
goods_detail[].unit_price
int64
True
Product unit price (in cents).
goods_detail[].refund_amount
int64
True
Product refund amount (in cents).
goods_detail[].refund_quantity
int
True
Number of items refunded.
Response parameters
Name
Type
Required
Description
returnCode
string
True
Response code, 0 indicates success.
returnMessage
string
False
Response information.
data
object
True
Refund response data.
data.refund_id
string
True
Platform refund ID.
data.out_refund_no
string
True
Merchant refund number.
data.transaction_id
string
True
Platform payment order ID.
data.out_trade_no
string
True
Merchant order number.
data.channel
string
True
Refund channels.
data.user_received_account
string
True
Account receiving the refund funds.
data.success_time
string
False
Refund success timestamp.
data.create_time
string
True
Refund creation timestamp.
data.status
string
True
Refund status: PROCESSING, SUCCESS, CLOSED, ABNORMAL.
data.amount
object
True
Refund amount details.
data.amount.total
int64
True
Total order amount (in cents).
data.amount.refund
int64
True
Refund amount (in cents).
data.amount.payer_total
int64
True
Amount paid by user (in cents).
data.amount.payer_refund
int64
True
Refund amount to user (in cents).
data.amount.currency
string
True
Currency.
data.amount.refund_fee
int64
True
Refund fee (in cents).
requestId
string
True
Request trace ID.


5.1.2 Query refund

Path: /spay/refund/refunds/{out_refund_no}
Method: GET
API description: Queries refund details by merchant refund number.
Request parameters
Headers
Parameter
Type
Description
Required
Note
Authorization
string
Signature authentication information.
True
Path
Parameter
Category
Description
Required
Note
out_refund_no
string
Merchant refund number.
True
-
Response parameters
Name
Type
Required
Description
returnCode
string
True
Response code, 0 indicates success.
returnMessage
string
False
Response information.
data
object
True
Refund detail data.
data.refund_id
string
True
Platform refund ID.
data.out_refund_no
string
True
Merchant refund number.
data.transaction_id
string
True
Platform payment order ID.
data.out_trade_no
string
True
Merchant order number.
data.channel
string
True
Refund channels.
data.user_received_account
string
True
Account receiving the refund funds.
data.success_time
string
False
Refund success timestamp.
data.create_time
string
True
Refund creation timestamp.
data.status
string
True
Refund status: PROCESSING, SUCCESS, CLOSED, ABNORMAL.
data.amount
object
True
Refund amount details.
data.amount.total
int64
True
Total order amount (in cents).
data.amount.refund
int64
True
Refund amount (in cents).
data.amount.payer_total
int64
True
Amount paid by user (in cents).
data.amount.payer_refund
int64
True
Refund amount to user (in cents).
data.amount.currency
string
True
Currency.
data.amount.refund_fee
int64
True
Refund fee (in cents).
requestId
string
True
Request trace ID.


5.1.3 Standard payment refund callback

After the refund approval is completed, the platform sends a notification via POST to the address specified by the TC-Payment-Callback header in the refund request.
Path: Value of the TC-Payment-Callback header in the refund request.
Method: POST
Request parameters
Headers
Parameter
Type
Description
Required
Description
TC-Callback-Serial
string
Superapp merchant certificate serial number.
True
The serial number of the superapp payment certificate used for verification.
TC-Callback-Signature
string
Signature value for verification.
True
TC-Timestamp
string
Timestamp (in seconds).
True
-
TC-Callback-Nonce
string
Random string for verification.
True
-
TC-Callback-OutRefundNo
string
Merchant refund number.
True
Passed as out_refund_no in refund request.
TC-MerchantID
string
The merchant ID on SAS.
True
-
TC-Signature
string
The signature for invoking signature verification on SAS.
True
TC-ApplicationID
string
The superapp ID on SAS.
True
-
Body
Name
Type
Required
Description
id
string
True
Unique notification ID.
create_time
string
True
Notification creation time, RFC3339 format.
event_type
string
True
REFUND.SUCCESS / REFUND.CLOSED / REFUND.ABNORMAL
resource_type
string
True
Fixed value: encrypt-resource.
summary
string
True
Notification summary.
Resource
object
True
Encrypted notification data.
resource.algorithm
string
True
Fixed value: AEAD_AES_256_GCM.
resource.original_type
string
True
Fixed value: refund.
resource.ciphertext
string
True
Base64-encoded encrypted data, decrypt with symmetric key.
resource.associated_data
string
False
Additional data for decryption.
resource.nonce
string
True
Random string for decryption.
Decrypted structure of resource.ciphertext data:
Name
Type
Required
Description
mch_id
string
True
Merchant ID.
transaction_id
string
True
Platform payment order ID.
out_trade_no
string
True
Merchant order number.
refund_id
string
True
Platform refund ID.
out_refund_no
string
True
Merchant refund number.
refund_status
string
True
Refund Status: SUCCESS/CLOSED/ABNORMAL.
success_time
string
False
Refund success time (returned only if SUCCESS).
user_received_account
string
True
Account receiving the refund funds.
amount
object
True
Refund amount details.
amount.total
string
True
Total order amount (in cents).
amount.refund
string
True
Refund amount (in cents).
amount.payer_total
string
True
Amount paid by user (in cents).
amount.payer_refund
string
True
Refund amount to user (in cents).
amount.currency
string
True
Currency.
Response parameters
Name
Type
Required
Description
returnCode
string
True
Response code, 0 indicates success.
returnMessage
string
False
Response information.
data
string
True
Response data, OK indicates success.
requestId
string
True
Request trace ID.


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
Type
Description
Required
Description
TC-Payment-Callback
string
Refund result callback URL.
True
Notification URL for refund completion, POST request.
TC-ApplicationID
string
The superapp ID on SAS.
True
Superapp ID.
TC-MerchantID
string
The merchant ID bound to the mini program’s superapp on SAS.
True

Query Parameters
Parameter
Type
Description
Required
Description
pay_sig
string
Virtual payment signatures.
True
Payment signature. The pay_sig parameter uses a signature algorithm that signs the payment request body (payload) with the AppKey obtained from the superapp. This indicates that the request is initiated by the developer’s server-side payment module. The signature algorithm pseudocode is as follows:
paySig = to_hex(hmac_sha256(appKey,uri + '&' +payload))
Body
Parameter
Type
Required
Description
The OpenID.
string
False
User openid who placed the order.
transaction_id
string
False
Platform payment order number, either this or out_trade_no required.
out_trade_no
string
False
Merchant order number, either this or transaction_id required.
out_refund_no
string
True
Unique refund order number per merchant.
reason
string
False
Reason for refund
req_from
string
False
Refund source:
1. Customer service agent
2. User-initiated
3. Other
amount
object
True
Refund amount details.
amount.refund
int64
True
Refund amount (in cents).
amount.total
int64
True
Total order amount (in cents).
amount.currency
string
True
Currency.
Response parameters
Name
Type
Required
Description
returnCode
string
True
Response code, 0 indicates success.
returnMessage
string
False
Response information.
data
object
True
Refund response data.
data.refund_id
string
True
Platform refund ID.
data.out_refund_no
string
True
Merchant refund number.
data.transaction_id
string
True
Platform payment order ID.
data.out_trade_no
string
True
Merchant order number.
data.channel
string
True
Refund channels.
data.user_received_account
string
True
Account receiving the refund funds.
data.success_time
string
False
Refund success timestamp.
data.create_time
string
True
Refund creation timestamp.
data.status
string
True
Refund status: PROCESSING, SUCCESS, CLOSED, ABNORMAL.
data.amount
object
True
Refund amount details.
data.amount.total
int64
True
Total order amount (in cents).
data.amount.refund
int64
True
Refund amount (in cents).
data.amount.payer_total
int64
True
Amount paid by user (in cents).
data.amount.payer_refund
int64
True
Refund amount to user (in cents).
data.amount.currency
string
True
Currency.
data.amount.refund_fee
int64
True
Refund fee (in cents).
requestId
string
True
Request trace ID.


5.2.2 Virtual payment refund callback

Path: Value of the TC-Payment-Callback header in the refund request.
Method: POST
Request parameters
Headers
Parameter
Type
Description
Required
Description
TC-MerchantID
string
The merchant ID bound to the mini program’s superapp on SAS.
True
-
TC-Callback-OutRefundNo
string
Merchant refund number.
True
Passed as out_refund_no in refund request.
TC-Timestamp
string
Timestamp (in seconds).
True
-
TC-Signature
string
The signature for invoking signature verification on SAS.
True
TC-ApplicationID
string
The superapp ID on SAS.
True
-
Body
Name
Type
Required
Description
eventType
string
True
REFUND. {{Refund status}}
Refund status: SUCCESS/CLOSED/ABNORMAL
event
string
True
Event identifier, same as eventType.
payload
string
True
JSON string containing refund notification data
payEventSig
string
True
Payment signature; pseudocode:
pay_event_sig = to_hex(hmac_sha256(app_key, event + '&' + payload))
Parsed payload data structure
Name
Type
Required
Description
mch_id
string
True
Merchant ID.
transaction_id
string
True
Platform payment order ID.
out_trade_no
string
True
Merchant order number.
refund_id
string
True
Platform refund ID.
out_refund_no
string
True
Merchant refund number.
refund_status
string
True
Refund Status: SUCCESS/CLOSED/ABNORMAL.
success_time
string
False
Refund success timestamp.
user_received_account
string
True
Account receiving the refund funds.
amount
object
True
Refund amount details.
Response parameters
Name
Type
Required
Description
returnCode
string
True
Response code, 0 indicates success.
returnMessage
string
False
Response information.
data
string
True
Response data, OK indicates success.
requestId
string
True
Request trace ID.

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