API List
Last updated:2025-12-31 18:46:42
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（Special information except for public request headers）
Request header | Description | Note | Example |
TC-OpenId | The unique identifier of the user in the Mini Program | Mini Program user unique identifier. This field is provided by Super App as a Service (SAS) and is a hex-encoded string based on AES ECB encryption of the OpenID value string. The secret key is referenced in the Configuration Management . | xxx |
TC-MiniAppID | The unique identifier of the Mini Program in the App | Mini Program ID. This field is provided by Super App as a Service (SAS) and is a hex-encoded string based on AES ECB encryption of the miniAppID value string. The secret key is referenced in the Configuration Management . | xxx |
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 | Boolean | True | Indicates 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:
Gets the user's 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:
Gets the user's 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. |
DateTime | 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. |
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 | 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: Mini program payment. |
TC-UserID | Superapp user login ID. | 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 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-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 signature verification, in seconds. | True | - |
TC-Nonce | Random string for verification. | True | - |
TC-Prepay-Id | The mini program order ID. | True | - |
X-TC-Signature | The signature for invoking signature verification on SAS. | True | See |
X-TC-ApplicationId | The superapp ID on SAS. | True | X-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 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. |
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 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 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 | 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. |
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 | Description | Required | Description |
Authorization | Signature authentication information. | True |
Path
Parameter | Description | Required | Description |
out_trade_no | Merchant order number. | True | - |
Body
Parameter | Description | Required | Description |
mchid | Merchant ID, provided when the merchant places the order. | True | - |
Response parameters
204 No Content
No content body
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 | Description | Required |
TC-Payment-Callback | The callback URL of a successful or failed payment. | True |
TC-UserID | Superapp user login ID. | True |
TC-PackageName | The superapp package name on SAS. | True |
X-TC-ApplicationId | The superapp ID on SAS. | True |
TC-MerchantId | Superapp merchant ID. | True |
TC-Platform-UserId | 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 | Description | Required |
X-TC-ApplicationId | The superapp ID on SAS. | True |
X-TC-Signature | The signature for invoking signature verification on SAS. See Super App as a Service Signature and Verification | True |
TC-Timestamp | Timestamp for signature verification, in milliseconds. | True |
body:
Parameter | Type | Description | Required |
| | Message type. Payment success - TRANSACTION.SUCCESS. Payment failure - TRANSACTION.PAYERROR. | |
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 | True |
Payload
Parameter | Type | Description | Required |
OpenId | string | 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 | Description | Required |
TC-Payment-Callback | The callback URL of a successful or failed payment. | True |
TC-UserID | Superapp user login ID. | True |
TC-PackageName | The superapp package name on SAS. | True |
X-TC-ApplicationId | The superapp ID on SAS. | True |
TC-MerchantId | The merchant ID bound to the mini program’s superapp on SAS. | True |
TC-Platform-UserId | 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,'requestMidasPaymentGameItem' + '&' + signData)) | True |
AppId | string | Superapp ID. | True |
MiniAppId | string | Mini game appid. | 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 | 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. |
Was this page helpful?
You can also Contact Sales or Submit a Ticket for help.
Yes
No
Feedback