API List
Last updated: 2025-12-05 23:13:24
1. Mini Program Login Interface
1.1 Check if User Exists
Path: /user/checkUser
Method: POST
Interface Description:
Check if the user exists based on the Superapp User ID
Request Parameters
Body
Name | Type | Required | Remarks |
userId | string | Yes | User anonymized ID, generated by the superapp using the SDK. Used to temporarily request an anonymized openid from the superapp server. Used temporarily when the Mini Program needs to obtain an openid. |
Response Parameters
Name | Type | Required | Remarks |
returnCode | string | Yes | Response code, 0 indicates success |
returnMessage | string | No | Response message |
data | boolean | Yes | Whether user exists |
requestId | string | Yes | Request Link ID |
1.2 Get User Temporary Information Code
Path: /user/getUserInfoTemporaryCode
Method: POST
Interface Description:
Get a temporary credential for user phone or email based on Type
Request Parameters
Body
Name | Type | Required | Remarks |
type | string | Yes | Acquisition type. Valid values: email, phone |
userId | string | Yes | User anonymized ID, generated by the superapp using the SDK. Used to temporarily request an anonymized openid from the superapp server. Used temporarily when the Mini Program needs to obtain an openid. |
Response Parameters
Name | Type | Required | Remarks |
returnCode | string | Yes | Response code, 0 indicates success |
returnMessage | string | No | Response message |
data | object | Yes | Response data. |
data.data | string | Yes | Returns the masked phone number or email based on the query type, e.g., 158****2850, mu****ng@tencent.com |
data.code | string | Yes | Temporary credential Code for phone or email |
requestId | string | Yes | Request Link ID |
1.3 Get User Email
Path: /user/getUserEmail
Method: POST
Interface Description:
Get user email based on the temporary credential code
Request Parameters
Body
Name | Type | Required | Remarks |
temporaryCode | string | Yes | Temporary credential Code |
userId | string | Yes | User anonymized ID, generated by the superapp using the SDK. Used to temporarily request an anonymized openid from the superapp server. Used temporarily when the Mini Program needs to obtain an openid. |
Response Parameters
Name | Type | Required | Remarks |
returnCode | string | Yes | Response code, 0 indicates success |
returnMessage | string | No | Response message |
data | string | Yes | User email information, encrypted via AES CBC (using the first 16 bytes of the key as the iv) and then base64 encoded. For the key, refer to SecretKey in Configuration Management. |
requestId | string | Yes | Request Link ID |
1.4 Get User Phone Number
Path: /user/getUserPhoneNumber
Method: POST
Interface Description:
Get user phone number based on the temporary credential code
Request Parameters
Body
Name | Type | Required | Remarks |
temporaryCode | string | Yes | Temporary credential Code |
userId | string | Yes | User anonymized ID, generated by the superapp using the SDK. Used to temporarily request an anonymized openid from the superapp server. Used temporarily when the Mini Program needs to obtain an openid. |
Response Parameters
Name | Type | Required | Remarks |
returnCode | string | Yes | Response code, 0 indicates success |
returnMessage | string | No | Response message |
data | string | Yes | User phone number, encrypted via AES CBC (using the first 16 bytes of the key as the iv) and then base64 encoded. For the key, refer to SecretKey in Configuration Management. |
requestId | string | Yes | Request Link ID |
1.5 Get User Nickname
Path: /user/getUserNick
Method: POST
Interface Description:
Get User Nickname
Request Parameters
Body
Name | Type | Required | Remarks |
userId | string | Yes | User anonymized ID, generated by the superapp using the SDK. Used to temporarily request an anonymized openid from the superapp server. Used temporarily when the Mini Program needs to obtain an openid. |
Response Parameters
Name | Type | Required | Remarks |
returnCode | string | Yes | Response code, 0 indicates success |
returnMessage | string | No | Response message |
data | string | Yes | User nickname |
requestId | string | Yes | Request Link ID |
1.6 Get User Avatar
Path: /user/getUserAvatar
Method: POST
Interface Description:
Get User Avatar
Request Parameters
Body
Name | Type | Required | Remarks |
userId | string | Yes | User anonymized ID, generated by the superapp using the SDK. Used to temporarily request an anonymized openid from the superapp server. Used temporarily when the Mini Program needs to obtain an openid. |
Response Parameters
Name | Type | Required | Remarks |
returnCode | string | Yes | Response code, 0 indicates success |
returnMessage | string | No | Response message |
data | string | Yes | User avatar URL |
requestId | string | Yes | Request Link ID |
1.7 Receive Subscription Message
Path: /message/send
Method: POST
Interface Description:
Receive user subscription message content pushed by the SAS platform side
Request Parameters
Body
Name | Type | Required | Remarks |
AccountId | string | Yes | Message owner User ID (same as UserId) |
MessageId | string | Yes | Message Unique ID |
Content | string | Yes | Message content |
DateTime | int | Yes | Message send timestamp in seconds |
TemplateId | string | Yes | Message Template ID |
MnpId | string | Yes | Mini Program ID |
MnpName | string | Yes | Mini Program Name |
TemplateTitle | string | Yes | Template Title |
State | string | Yes | Jump Mini Program type: developer (dev version), trial (trial version), formal (formal version); default is formal. |
Page | string | Yes | Jump page within the Mini Program after clicking the message card. Supports parameters (example: index?foo=bar). If this field is empty, the template will not jump. |
MnpIcon | string | Yes | Mini Program Icon |
Response Parameters
Name | Type | Required | Remarks |
returnCode | string | Yes | Response code, 0 indicates success |
returnMessage | string | No | Response message |
data | bool | Yes | Processing Result |
requestId | string | Yes | Request Processing Link ID |
2. Mini Program Payment Interface
2.1 Create Mini Program Pre-order
Path: /v3/pay/transactions/jsapi
Method: POST
Interface Description:
Create a pre-order for Mini Program payment.
Request Parameters
Headers
Parameter Name | Description | Required | Remarks |
TC-Payment-Callback | Callback address for payment success or failure | Yes | Payment callback notification address, POST request |
TC-MerchantId | Merchant ID | Yes | Merchant ID (mchid) is the unique identifier for the merchant on the Superapp payment side. All interface calls must include this parameter for identity verification. The Merchant ID is provided by Superapp Payment after successful onboarding. |
TC-TradeType | Trade Type | Yes | JSAPI: Mini Program Payment |
TC-UserID | Superapp Login User ID | Yes | - |
Authorization | Signature Authentication Information | Yes |
Body
Name | Type | Required | Remarks |
appid | string | Yes | Merchant Mini Program ID, the unique identifier of the merchant on the platform. Must ensure that this appid is bound to the 【mchid】. |
description | string | Yes | Product description. Merchants must provide a description that truly represents the product information. Must not exceed 127 characters. |
out_trade_no | string | Yes | Merchant's internal order number. Must be 6-32 characters, only numbers, letters (case sensitive), _, -, | and *. Must be unique under the same merchant ID. |
time_expire | string | Yes | Payment expiration time. The deadline for the user to complete the payment for this order, not the order closing time. After this time, the user cannot pay for this order. Format requirement: Must follow RFC3339 standard format: yyyy-MM-DDTHH:mm:ss+TIMEZONE. yyyy-MM-DD represents year-month-day; T separates date and time; HH:mm:ss represents specific time; TIMEZONE represents time zone (e.g., +08:00 for UTC+8, Beijing Time). |
attach | string | No | Custom data packet provided by the merchant when creating the order. This data is invisible to the user and is used to store order-related custom information. Total length limit is 128 characters. This field will be returned to the merchant in the order query API and payment success callback. |
amount | object | Yes | Order Amount Information |
amount.total | int | Yes | Total order amount, in cents (integer). |
amount.currency | string | No | Currency type, ISO 4217 compliant three-letter code. |
payer | object | Yes | Payer Information |
payer.openid | string | Yes | Unique identifier of the user under the merchant appid. Must obtain the user's OpenID before placing an order. See details in Mini Program Login |
detail | object | Yes | Product Information |
detail.cost_price | int | No | Original order price |
detail.goods_detail | array[object] | Yes | Product List |
detail.goods_detail.merchant_goods_id | string | Yes | Merchant side product code, consisting of one or more of: alphanumeric characters, hyphens, and underscores. |
detail.goods_detail.goods_name | string | No | Actual name of the product |
detail.goods_detail.quantity | int | Yes | Quantity of product purchased by user |
detail.goods_detail.unit_price | int | Yes | Product unit price, integer, unit: cents. |
Response Parameters
Name | Type | Required | Remarks |
returnCode | string | Yes | Response code, 0 indicates success |
returnMessage | string | No | Response message |
data | object | Yes | Response data |
data.prepayId | string | Yes | Pre-order ID, unique for the merchant |
requestId | string | Yes | Request Link ID |
2.2 Mini Program Pre-order Payment Callback
Using the standard payment function, after the user successfully pays for the order, superapp Payment will send a callback notification via POST request to the address specified in the TC-Payment-Callback header of the 2.1 interface request, informing the merchant that the user has completed the payment.
Path: The value of the TC-Payment-Callback header in the request of interface 2.1
Method: POST
Interface Description:
Mini Program Pre-order Payment Callback
Request Parameters
Headers
Parameter Name | Description | Required | Remarks |
TC-Serial | Callback address for payment success or failure | Yes | Superapp platform merchant serial number for verification / Superapp platform merchant payment public key ID [Merchant Serial Number, Merchant Certificate] |
TC-Signature | Signature value for verification | Yes | |
TC-Timestamp | Verification timestamp, in seconds | Yes | - |
TC-Nonce | Random string for verification | Yes | - |
TC-Prepay-Id | Mini Program Pre-order ID | Yes | - |
X-TC-Signature | Signature for calling Superapp Service Platform service verification | Yes | |
X-TC-ApplicationId | Superapp Service Platform Application ID | Yes | X-TC-ApplicationId in the request header when creating the order |
Body
Name | Type | Required | Remarks |
id | string | Yes | [Notification ID] Unique ID of callback notification |
create_time | string | Yes | [Notification Creation Time] Format: Follows RFC3339 standard format: yyyy-MM-DDTHH:mm:ss+TIMEZONE. yyyy-MM-DD represents year-month-day; T separates date and time; HH:mm:ss represents specific time; TIMEZONE represents time zone (e.g., +08:00 for UTC+8, Beijing Time). Example: 2015-05-20T13:29:35+08:00 represents May 20, 2015, at 13:29:35 Beijing Time. |
event_type | string | Yes | [Notification Type] Type of Superapp payment callback notification. Payment Success - TRANSACTION.SUCCESS. Payment Failure - TRANSACTION.PAYERROR. |
resource_type | string | Yes | [Notification Data Type] Resource data type of notification, fixed as encrypt-resource. |
summary | string | Yes | [Callback Summary] Summary note of callback content by Superapp platform payment. |
resource | object | Yes | [Notification Data] Notification resource data. |
resource.algorithm | string | Yes | [Encryption Algorithm Type] The encryption algorithm type of the callback data ciphertext. Currently AEAD_AES_256_GCM. Developers need to use the same type of data for decryption. |
resource.ciphertext | string | Yes | [Data Ciphertext] Base64 encoded callback data ciphertext. Merchants need to Base64 decode it and decrypt it using the API secret key. |
resource.associated_data | string | No | [Associated Data] Associated data participating in 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 | [Nonce] Random string participating in decryption. |
Response Parameters
Name | Type | Required | Remarks |
returnCode | string | Yes | Response code, 0 indicates success |
returnMessage | string | No | Response message |
data | boolean | Yes | Whether the order was closed successfully |
requestId | string | Yes | Request Link ID |
2.3 Query Order by Merchant Order No
Path: /v3/pay/transactions/out-trade-no/{out_trade_no}
Method: GET
Interface Description:
Query order based on merchant order number
Request Parameters
Headers
Parameter Name | Description | Required | Remarks |
Authorization | Signature Authentication Information | Yes |
Path
Parameter Name | Description | Required | Remarks |
out_trade_no | Merchant Order No | Yes | - |
Query
Parameter Name | Description | Required | Remarks |
mchid | Merchant ID passed during order placement | Yes | - |
Response Parameters
Name | Type | Required | Remarks |
returnCode | string | Yes | Response code, 0 indicates success |
returnMessage | string | No | Response message |
data | object | Yes | Response data |
data.app_id | string | Yes | Merchant Mini Program ID passed during order placement |
data.mchid | string | Yes | Merchant ID passed during order placement |
data.out_trade_no | string | Yes | Merchant system internal order number passed during order placement |
data.transaction_id | string | Yes | Unique identifier of the order on the Superapp payment side, returned after payment success |
data.trade_type | string | No | Return the transaction type of the current order, enum values: JSAPI: Mini Program Payment |
data.trade_state | string | Yes | Transaction status, enum values: SUCCESS: Payment Success REFUND: Refunded NOTPAY: Not Paid CLOSED: Closed REVOKED: Revoked USERPAYING: User Paying PAYERROR: Payment Failure |
data.trade_state_desc | string | Yes | Detailed description of the transaction status |
data.bank_type | string | No | User payment type description, returned after payment success, format: bank short code_specific type (DEBIT debit card/CREDIT credit card) |
data.success_time | string | No | Time when the user completed the order payment. This parameter is returned after payment success. Format: Follows RFC3339 standard format: yyyy-MM-DDTHH:mm:ss+TIMEZONE. yyyy-MM-DD represents year-month-day; T separates date and time; HH:mm:ss represents specific time; TIMEZONE represents time zone (e.g., +08:00 for UTC+8, Beijing Time). Example: 2015-05-20T13:29:35+08:00 represents May 20, 2015, at 13:29:35 Beijing Time. |
data.payer | object | No | Payer information, returned after payment success, superapp User ID |
data.amount | object | No | Order Amount Information |
data.amount.total | string | No | Total Order Amount |
data.amount.payer_total | string | No | User Actual Payment Amount |
data.amount.currency | string | No | Currency Type |
data.amount.payer_currency | string | No | User Payment Currency |
requestId | string | Yes | Request Link ID |
2.4 Close Order
Unpaid orders can be closed by calling this interface when payment is no longer required. Common order closing scenarios include:
The user submits an order cancellation request in the merchant system, and the merchant needs to perform an order closing operation.
The order times out and remains unpaid (exceeding the payment time limit set by the merchant system or the time_expire payment deadline at the time of ordering), and the merchant needs to process the order closing.
Path: /v3/pay/transactions/out-trade-no/{out_trade_no}/close
Method: POST
Interface Description:
Query order based on merchant order number
Request Parameters
Headers
Parameter Name | Description | Required | Remarks |
Authorization | Signature Authentication Information | Yes |
Path
Parameter Name | Description | Required | Remarks |
out_trade_no | Merchant Order No | Yes | - |
Body
Parameter Name | Description | Required | Remarks |
mchid | Merchant ID passed during order placement | Yes | - |
Response Parameters
204 No Content
No response body
3. Mini Game Virtual Payment Interfaces
3.1 Create Mini Game Virtual Payment Order
Path: /requestMidasPaymentGameItem
Method: POST
Interface Description:
Create Mini Game virtual payment pre-order
Request Parameters
Headers
Parameter Name | Description | Required |
TC-Payment-Callback | Callback address for payment success or failure | Yes |
TC-UserID | Superapp Login User ID | Yes |
TC-PackageName | Superapp Platform Package Name | Yes |
X-TC-ApplicationId | Superapp Platform Application ID | Yes |
TC-MerchantId | Superapp Merchant ID | Yes |
TC-Platform-UserId | Superapp Platform User OpenID | Yes |
body：
Parameter Name | Field Type | Description | Required | Remarks |
SignData | string | Payment Original String | Yes | See signData below for specific payment parameters. Data must be passed in JSON format. signData Example: '{"mode":"goods","offerId":"123","buyQuantity":1,"env":0,"currencyType":"USD","productId":"testproductId","goodsPrice":10,"outTradeNo":"xxxxxx","attach":"testdata"}' |
PaySig | string | Payment Signature | Yes | Signature algorithm for pay_sig parameter. Use the AppKey in superapp to sign the payment request, representing the request initiated by the developer's server-side payment module. The signature algorithm pseudocode is: paySig = to_hex(hmac_sha256(appKey,'requestMidasPaymentGameItem' + '&' + signData)) |
AppId | string | Superapp Platform Application ID | Yes | Application ID |
MiniAppId | string | Superapp Platform Mini Game ID | Yes | Mini Game ID |
GoodsName | string | Game Item Name | Yes | Name of game item ordered |
OrderSource | int | Order Source | Yes | Order Source 1: In-game |
Event | string | Event Type | Yes | Fixed when OrderSource=1: minigame_game_pay_goods_deliver_notify |
SignData：
Parameter Name | Field Type | Description | Required | Remarks |
buyQuantity | int | Purchase Quantity | Yes | Purchase Quantity |
currencyType | string | Currency | Yes | Currency type, ISO 4217 compliant three-letter code. |
productId | string | Item ID | Yes | Item ID |
goodsPrice | int | Item Unit Price | Yes | Item unit price (Unit: cents) |
outTradeNo | string | Merchant Business Order No | Yes | Merchant system internal order number. Must be 6-32 characters, consisting only of numbers, case-sensitive letters, _, -, |, and *. Must be unique under the same merchant ID. |
attach | string | Passthrough Parameters | No | Returned as-is during payment callback |
Response Parameters
Name | Type | Required | Remarks |
returnCode | string | Yes | Response code, 0 indicates success |
returnMessage | string | No | Response message |
data | object | Yes | Response data |
data.prepayId | string | Yes | Pre-order ID, unique per merchant |
requestId | string | Yes | Request Link ID |
3.2 Mini Game Payment Callback
When a user successfully pays using the standard payment function, superapp Payment will send a callback notification via POST request to the address specified in the TC-Payment-Callback header of the 3.1 interface request, informing the merchant that the user has completed the payment.
Path: Value of TC-Payment-Callback header in request of interface 3.1
Method: POST
Interface Description:
Mini Game Payment Callback
Request Parameters
header:
Parameter Name | Description | Required |
X-TC-ApplicationId | Superapp Platform Application ID | Yes |
X-TC-Signature | Signature for calling Superapp Service Platform verification service, refer to Superapp Platform Signature Verification | Yes |
TC-Timestamp | Verification timestamp, in milliseconds | Yes |
body:
Parameter Name | Field Type | Description | Required |
EventType | string | Message type: Payment Success - TRANSACTION.SUCCESS. Payment Failure - TRANSACTION.PAYERROR. | |
Event | string | Event from order creation | Yes |
PayModel | string | Payment Model: Wallet, Bankcard, Third | Yes |
Payload | string | Specific content carried, in JSON format. Specific content is in the Payload table below (designed as JSON because message content needs unified signing). | Yes |
PayEventSig | string | Yes |
Payload
Parameter Name | Field Type | Description | Required |
OpenId | string | Superapp Platform User ID, TC-Platform-UserId from order placement header | Yes |
OutTradeNo | string | Order Number | Yes |
GoodsInfo | Object | Delivery Item | Yes |
TransactionId | string | Payment Transaction ID | Yes |
GoodsInfo
Parameter Name | Field Type | Description | Required |
ProductId | String | Game Item ID Identifier | Yes |
Quantity | Number | Quantity of purchased items | Yes |
OrigPrice | Number | Original item price (Unit: cents) | Yes |
ActualPrice | Number | Actual item payment price (Unit: cents) | Yes |
Attach | String | Passthrough Data | Yes |
OrderSource | Number | Yes | Yes |
Response Parameters
Name | Type | Required | Remarks |
returnCode | string | Yes | Response code, 0 indicates success |
returnMessage | string | No | Response message |
data | string | Yes | Response data, 'ok' on success |
requestId | string | Yes | Request Link ID |
4. Mini Program Virtual Payment Interface
4.1 Create Mini Program Virtual Payment Order
Path: /requestVirtualPayment
Method: POST
Interface Description:
Create Mini Program Virtual Payment Pre-order
Request Parameters
Headers
Parameter Name | Description | Required |
TC-Payment-Callback | Callback address for payment success or failure | Yes |
TC-UserID | Superapp Login User ID | Yes |
TC-PackageName | Superapp Platform Package Name | Yes |
X-TC-ApplicationId | Superapp Platform Application ID | Yes |
TC-MerchantId | Merchant ID bound to superapp in the Superapp Platform Mini Program | Yes |
TC-Platform-UserId | Superapp Platform User OpenID | Yes |
body
Parameter Name | Field Type | Description | Required |
SignData | string | Payment Original String. See signData below for specific payment parameters. Data must be passed in JSON format. signData Example: '{"offerId":"123","buyQuantity":1,"env":0,"currencyType":"USD","productId":"testproductId","goodsPrice":10,"outTradeNo":"xxxxxx","attach":"testdata"}' | Yes |
PaySig | string | Payment Signature. Signature algorithm for pay_sig parameter. Use the AppKey in superapp to sign the payment request, representing the request initiated by the developer's server-side payment module. The signature algorithm pseudocode is: paySig = to_hex(hmac_sha256(appKey,'requestMidasPaymentGameItem' + '&' + signData)) | Yes |
AppId | string | Application ID | Yes |
MiniAppId | string | Mini Game ID | Yes |
GoodsName | string | Game Item Name | Yes |
OrderSource | int | Order Source 10: Order placed within Mini Program Short Drama | Yes |
Event | string | Fixed when orderSource=10: xpay_goods_deliver_notify | Yes |
SignData：
Parameter Name | Field Type | Description | Required | Remarks |
buyQuantity | int | Purchase Quantity | Yes | Purchase Quantity |
currencyType | string | Currency | Yes | Currency type, ISO 4217 compliant three-letter code. |
productId | string | Item ID | Yes | Item ID |
goodsPrice | int | Item Unit Price | Yes | Item unit price (Unit: cents) |
outTradeNo | string | Merchant Business Order No | Yes | Merchant system internal order number. Must be 6-32 characters, consisting only of numbers, case-sensitive letters, _, -, |, and *. Must be unique under the same merchant ID. |
attach | string | Passthrough Parameters | No | Returned as-is during payment callback |
Response Parameters
Name | Type | Required | Remarks |
returnCode | string | Yes | Response code, 0 indicates success |
returnMessage | string | No | Response message |
data | object | Yes | Response data |
data.prepayId | string | Yes | Pre-order ID, unique per merchant |
requestId | string | Yes | Request Link ID |
4.2 Mini Program Virtual Payment Callback
When a user successfully pays using the standard payment function, superapp Payment will send a callback notification via POST request to the address specified in the TC-Payment-Callback header of the 4.1 interface request, informing the merchant that the user has completed the payment.
Path: Value of TC-Payment-Callback header in request of interface 4.1
Method: POST
Interface Description:
Mini Program Virtual Payment Callback
Request Parameters
Parameter Name | Field Type | Description | Required |
EventType | string | Message type: Payment Success - TRANSACTION.SUCCESS. Payment Failure - TRANSACTION.PAYERROR. | Yes |
Event | string | Event type, event from order creation | Yes |
PayModel | string | Payment Model: Wallet, Bankcard, Third | Yes |
Payload | string | Specific content carried, in JSON format. Specific content is in the Payload table below (designed as JSON because message content needs unified signing). | Yes |
PayEventSig | string | Yes |
Payload
Parameter Name | Field Type | Description | Required |
OpenId | string | Superapp Platform User ID, TC-Platform-UserId from order placement header | Yes |
OutTradeNo | string | Order Number | Yes |
GoodsInfo | Object | Delivery Item | Yes |
PayInfo | Object | Payment Information | Yes |
GoodsInfo
Parameter Name | Field Type | Description | Required |
ProductId | String | Game Item ID Identifier | Yes |
Quantity | Number | Purchase Quantity | Yes |
OrigPrice | Number | Original item price (Unit: cents) | Yes |
ActualPrice | Number | Actual item payment price (Unit: cents) | Yes |
Attach | String | Passthrough Data | Yes |
OrderSource | Number | 1 In-game | Yes |
PayInfo
Parameter Name | Field Type | Description | Required |
MchOrderNo | String | Merchant ID passed during order placement | Yes |
PaidTime | Number | Payment timestamp, unit: seconds | Yes |
TransactionId | String | Payment Transaction ID | Yes |
Response Parameters
Name | Type | Required | Remarks |
returnCode | string | Yes | Response code, 0 indicates success |
returnMessage | string | No | Response message |
data | string | Yes | Response data, 'ok' on success |
requestId | string | Yes | Request Link ID |
Was this page helpful?
You can also Contact Sales or Submit a Ticket for help.
Yes
No
Feedback