Tencent Cloud Super App as a Service
- Release Notes and Announcements
- Purchasing Guide
- Plan Management
- Branded Configurations
- Introduction to Platform Functions
- Commercialization
- Virtual Payment
- Guidelines for Code Integration
- Android
- Android SDK Description
- Android API
- Mini Program Management APIs
- Custom Mini Program Capabilities
- Custom SDK Capabilities
- iOS
- iOS SDK Description
- iOS API
- Mini Program Management APIs
- Customize Mini Program Capabilities
- Customised SDK Capabilities
- Flutter
- Flutter SDK Description
- Flutter API
- Mini Program Management API
- Mini Program Capabilities Customization
- Plugin Customization
- App Server
- Payment Development Notes
- Mini Program Payment: Parameter Application and Configuration
- Mini Game Payment: Parameter Application and Configuration
- Mini Program Payment: Signature and Verification
- Guildlines for Mini Program Development
- Mini Program Code Composition
- Guidance
- Learn About Mini Programs
- Configuring Mini Program
- Mini Program Framework
- Basic Competencies
- Open Capabilities
- Framework
- Mini Program Configuration
- Framework Interface
- WXML Syntax Reference
- WXS Syntax Reference
- Components
- API
- Interface
- Media
- Device
- JS SDK
- IDE Operation Instructions
- Guildlines for Mini Game Development
- Guide
- Game Engine
- Basic Capability
- Open Capabilities
- API
- Interface
- Rendering
- Device
- Server Backend
- Practice Tutorial
- API Documentation
- Making API Requests
- User Management APIs
- Team Management APIs
- Sensitive API-Related APIs
- Role Management APIs
- Platform Management APIs
- Other Console APIs
- Mini Program APIs
- Management-Sensitive APIs
- Global Domain Management APIs
- Application APIs
API List
Last updated: 2025-04-25 19:08:07
Note:
Supported only on public cloud.
1.1 Check whether the user exists
Path: /superapp/inner/user/checkUser
Method: POST
API description:
Checks if the user exists based on the superapp's user ID.
Request parameters
Body
Name | Type | Required | Description |
userId | String | True | Superapp user ID. |
Response parameters
Name | Type | Required | Description |
returnCode | String | True | Response code, 0 indicates success. |
returnMessage | String | False | Response information. |
data | boolean | True | Indicates whether the user exists. |
requestId | String | True | Request trace ID. |
1.2. Get user temporary information code
Path: /superapp/inner/user/getUserInfoTemporaryCode
Method: GET
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 | Superapp user ID. |
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 | The masked phone 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: /superapp/inner/user/getUserEmail
Method: GET
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 | Superapp user ID. |
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. The secret key is referenced in the Configuration management . |
requestId | String | True | Request trace ID. |
1.4 Get user’s mobile number
Path: /superapp/inner/user/getUserPhoneNumber
Method: GET
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 | Superapp user ID. |
Response parameters
Name | Type | Required | Description |
returnCode | String | True | Response code, 0 indicates success. |
returnMessage | String | False | Response information. |
data | String | True | User's mobile number, a Base64 string after being encrypted using AES CBC. The secret key is referenced in the Configuration management. |
requestId | String | True | Request trace ID. |
1.5 Get user’s nickname
Path: /superapp/inner/user/getUserNick
Method: GET
API description:
Gets the user's nickname.
Request parameters
Body
Name | Type | Required | Description |
userId | String | True | Superapp user ID. |
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: /superapp/inner/user/getUserAvatar
Method: GET
API description:
Gets the user's profile photo.
Request parameters
Body
Name | Type | Required | Description |
userId | String | True | Superapp user ID. |
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. |
Error code
Error code | Error code value | Description |
0 | OK | - |
200000 | request data is not exist | The request data does not exist. |
200001 | Invalid User | User error or exception. |
200002 | Invalid User id | Invalid user ID. |
200003 | Temporary code error or expired | Temporary code error or expired. |
1.7. 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 | Note |
TC-Payment-Callback | The callback URL of a successful or failed payment | True | URL for payment callback notification, POST request. |
TC-MerchantId | Merchant ID. | True | Merchant ID (mchid) is the unique identifier for the merchant in the superapp's payment. All API calls must include this parameter for the superapp's payment to verify the merchant's identity. This ID is provided to the merchant upon successful registration. |
TC-TradeType | Transaction type. | True | JSAPI: Users pay via the mini program platform, which forward to the supperapp's payment API. |
TC-UserID | Superapp user login ID | True | - |
Authorization | Signature authentication information | True |
Body
Name | Type | Required | Description |
appid | String | True | Merchant's mini program ID, the unique identifier for the merchant on Super App as a Service (SAS). Ensure this mini program ID 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 RFC 3339 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 for Beijing time). |
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 ID. 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 | object | True | Product list. |
detail.goods_detail.merchant_goods_id | String | True | 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 | 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. |
Error code
Error code | Error code value | Description |
220000 | MCH_NOT_EXISTS | Check if the merchant ID is correct. |
220001 | TRADE_ERROR | Transaction failure, check the details returned by the API. |
220002 | ORDER_NOT_EXIST | Check if the order has been placed successfully. |
220003 | APPID_MCHID_NOT_MATCH | Check if the merchant's mini program ID matches the merchant ID. |
1.8. 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 1.7, informing the merchant that the user has completed the payment.
Path: TC-Payment-Callback, described in the section 1.7
Method: POST
API description:
Mini program order payment callback.
Request parameters
Headers
Parameter | Description | Required | Note |
TC-Serial | The callback URL of a successful or failed payment | True | The merchant serial number, and the merchant payment public key ID on the superapp's payment (Merchant serial number, merchant certificate). |
TC-Signature | Signature value for verification. | True | |
TC-Timestamp | Timestamp for verification. | True | - |
TC-Nonce | Random string for verification. | True | - |
TC-Prepay-Id | The mini program order ID. | True | - |
Body
Name | Type | Required | Description |
id | String | True | Unique identifier for the callback notification. |
create_time | String | True | Notification creation time: It follows the RFC 3339 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 for Beijing time). Example: 2015-05-20T13:29:35+08:00 represents 13:29:35 on May 20, 2015 (Beijing time). |
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 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. For details, see How to decrypt certificates and callback messages. |
resource.associated_data | String | False | Additional data for decryption, this field may be empty. |
resource.original_type | String | True | Original callback type before encryption, which is transaction. |
resource.nonce | String | True | Random string involved in decryption. |
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. |
1.9. 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 | Note |
Authorization | Signature authentication information | True |
Path
Parameter | Description | Required | Note |
out_trade_no | Merchant order number. | True | - |
Query
Parameter | Description | Required | Note |
mchid | Merchant ID, provided when the merchant places the order. | True | - |
Response parameters
Name | Type | Required | Note |
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 ID, 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: Users pay via the mini program platform, which forward to the supperapp's payment API. |
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/ECNY digital CNY). |
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 RFC 3339 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 for Beijing time). Example: 2015-05-20T13:29:35+08:00 represents 13:29:35 on May 20, 2015 (Beijing time). |
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 | The total amount of the order. |
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. |
Error code
Error code | Error code value | Description |
220000 | MCH_NOT_EXISTS | Check if the merchant ID is correct. |
220001 | TRADE_ERROR | Transaction failure, check the details returned by the API. |
220002 | ORDER_NOT_EXIST | Check if the order has been placed successfully. |
1.10 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 | Description | Required | Note |
Authorization | Signature authentication information | True |
Path
Parameter | Description | Required | Note |
out_trade_no | Merchant order number. | True | - |
Body
Parameter | Description | Required | Note |
mchid | Merchant ID, provided when the merchant places the order. | True | - |
Response parameters
204 No Content
No content body
Error code
Error code | Error code value | Description |
220000 | MCH_NOT_EXISTS | Check if the merchant ID is correct. |
220001 | TRADE_ERROR | Transaction failure, check the details returned by the API. |
220002 | ORDER_NOT_EXIST | Check if the order has been placed successfully. |
Common error codes
Error code | Error code value | Description |
210000 | PARAM_ERROR | Provide correct parameters according to the error prompt. |
210001 | INVALID_REQUEST | Check the API parameter rules. |
210002 | SIGN_ERROR | Incorrect signature. |
210003 | SYSTEM_ERROR | Try again later. |
Was this page helpful?
You can also Contact Sales or Submit a Ticket for help.
Yes
No