Mini Program Payment

1. Query order status
API description:
Queries order status using the order number.
Request method: Get
Request URL:
/v3/pay/transactions/out-trade-no/:out_trade_no
Request parameters
Property
Type
‍Required
Description
out_trade_no
string
True
Order number.
Response parameters
Property
Type
‍Required
Description
appid
string
True
Mini program ID.
mch_id
string
True
Merchant account, provided when the merchant places the order.
out_trade_no
string
True
Merchant order number, provided when the merchant places the order.
transaction_id
string
False
Unique identifier of the payment order, which is returned when the order is paid successfully.
trade_type
string
False
Transaction type: JSAPI for mini program payments.
trade_state
string
True
Transaction status: 
WAIT_PAY - Awaiting payment
Success - Payment successful
CLOSED - Order closed
AUTO_CLOSED - Order automatically closed due to expiration
REFUND - Refunded
PAY_ERROR - Payment failed
﻿
﻿
bank_type
string
False
Bank code. Non-bank card payment types are uniformly marked as OTHERS.
attach
string
False
Merchant data packet, custom data provided by the merchant when placing the order, not visible to the user, up to 256 characters. If provided, it will be returned as-is in this API, payment success callback notification, and transaction bill. If not provided, it will not be returned.
success_time
string
False
Payment completion 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).
payer
payer
False
Information about the payer, returned when the order is paid successfully.
amount
orderAmount
False
Order amount.
Response example:
{
    "appid": "mpco56h12e6e52hj",
    "mch_id": "mi_7b0a5e40f9",
    "out_trade_no": "2b695106b888d14328d9",
    "transaction_id": "pi1738915449351wbrgic93qlahw34134wjr",
    "trade_type": "JSAP",
    "trade_state": "SUCCESS",
    "bank_type": "OTHERS",
    "attach": "attch info",
    "success_time": "2025-02-28T10:34:56+08:00",
    "payer": {
        "openid": "o910d4edeee717377adguZS89513"
    },
    "amount": {
        "payer_total": "88800",
        "total": 88800,
        "currency": "USD",
        "payer_currency": "USD"
    }
}
2. Close an order
API description:
Closes the original order to avoid duplicate payments when a merchant's order payment fails, and a new order number is generated to re-initiate the payment.
Additionally, if the user payment times out after the system places an order and the system exits without further processing, the close order API should be called to prevent the user from continuing the payment.
Request method: Post
Request URL:
/v3/pay/transactions/out-trade-no/:out_trade_no/close
Request parameters
Property
Type
‍Required
Description
out_trade_no
string
True
Merchant order number, provided when the merchant places the order.
mchid
string
True
Merchant account, provided when the merchant places the order.
Response parameters
Property
Type
‍Required
Description
Response example:
No response packet
204 No Content
﻿
3. Place an order in a mini program
API description:
In the mini program payment scenario, merchants need to call this API to place an order in the application and generate a prepay transaction session identifier (prepay_id) used to initiate the payment.
Request method: Post
Request URL:
/v3/pay/transactions/jsapi
Request parameters
Property
Type
‍Required
Description
appid
string
True
Mini program ID.
description
string
True
Product description, up to 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
1. Definition: The payment end time 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. To close an order, call the order closing API.
﻿
2. Format requirements: The payment end time shall 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).
3. Parameters can only be configured when the user first places an order, and subsequent modifications are not allowed, attempts to modify will result in errors.
If the actual payment time exceeds the set payment end time, the merchant needs to place a new order with a new merchant order number for the user to pay. If the payment end time has not been exceeded, the original parameters can be used to request the order API again to get the latest prepay_id for payment.
The payment end time cannot be earlier than 1 minute after the order time. If the set payment end time is earlier, the system will automatically adjust it to 1 minute after the order 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, and will also appear in the transaction bill.
notify_url
string
True
The URL where the merchant receives payment success callback notifications. It must comply with the notify_url specification.
amount
amount
True
Order amount.
payer
payer
True
Payer information.
detail
detail
True
Discount feature.
Response parameters
Property
Type
‍Required
Description
prepay_id
string
True
Prepay transaction session identifier, required for JSAPI or mini program payment initiation, valid for 2 hours. If it expires, a new prepay_id must be requested by calling this API again.
Response example:
{
    "prepay_id":"pi173898442419368bhz26jn4rikpwzr1akn"
}
4. Payment callback
API description:
When a user successfully pays for an order, the application payment system will send a callback notification to the merchant's pre-configured callback URL (notify_url) via a POST request, informing the merchant that the user has completed the payment.
Request method: Post
Request URL:
/super-app/transactions/callback
Request parameters
Property
Type
‍Required
Description
id
string
True
Unique identifier for the callback notification.
create_time
string
True
The time when the callback notification was created.
Format: Follow the RFC 3339 standard format: yyyy-MM-DDTHH:mm:ss+TIMEZONE. yyyy-MM-DD represents the year, month, and day. the “T” character is used to separate the date and time portions. HH:mm:ss represents the specific hour, minute, and second. TIMEZONE represents the time zone (for example, +08:00 corresponds to the East 8th Zone time, which is Beijing Time).
Example: 2015-05-20T13:29:35+08:00 represents 13:29:35 on May 20, 2015 (Beijing time).
resource_type
string
True
Resource data type of the notification. It is fixed as encrypt-resource.
﻿
event_type
string
True
Type of payment callback notification.
For successful payment notifications, the type is TRANSACTION.SUCCESS.
pay_model
string
False
Type of payment bank card, OTHERS for non-bank card payments.
summary
string
True
The summary note for callback content in the payment system, limited to 64 characters.
resource
paymentNotifyResource
True
Notification resource data.
Response parameters
Property
Type
‍Required
Description
ok
string
True
-
Response example:
{
  "ok"
}
Data types
paymentNotifyResource
Property
Type
‍Required
Description
original_type
string
True
Original callback type: The object type before encryption, which is transaction.
algorithm
string
True
Encryption algorithm type: The 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.
ciphertext
string
True
Data ciphertext: The Base64-encoded ciphertext of the callback data. Merchants need to Base64 decode and decrypt it.
associated_data
string
False
Additional data: Additional data involved in decryption. This field may be empty.
nonce
string
True
Random string: The random string involved in decryption.
detail
Property
Type
‍Required
Description
cost_price
integer
False
Original price of the order.
goods_detail
array[goods_detail]
False
List of individual product details.
goods_detail
Property
Type
‍Required
Description
merchant_goods_id
string
False
Unified product ID defined by the payment system (optional).
goods_name
string
False
 Actual name of the product.
quantity
integer
True
Quantity of products purchased by the user.
unit_price
integer
True
Integer, unit: cents. If the merchant offers a discount, the discounted unit price should be provided (e.g., if a user uses a 100-50 coupon on a 100 USD order, the unit price of the promotional product should be the original unit price minus 50).
payer
Property
Type
‍Required
Description
openid
string
False
Unique identifier for the user under the merchant's appid.
orderAmount
Property
Type
‍Required
Description
payer_total
string
False
Total order amount (in cents).
total
interger
False
Actual amount paid by the user, an integer value, in cents. User payment amount = total amount - voucher amount.
currency
string
False
Currency type: CNY - Chinese Yuan, USD - US Dollar.
payer_currency
string
False
User payment currency: CNY - Chinese Yuan, USD - US Dollar.
amount
Property
Type
‍Required
Description
total
interger
False
Actual amount paid by the user, an integer value, in cents. User payment amount = total amount - voucher amount.
currency
string
False
Currency type: CNY - Chinese Yuan, USD - US Dollar.
Guidelines for setting notify_url
（1）The notify_url should be the actual address of the merchant's own system, not an example address from the API documentation or demo.
（2）The notify_url must be a complete URL starting with either https:// or http://. Ensure that the domain and IP in the URL are accessible from the internet;     do not use localhost, 127.0.0.1, 192.168.x.x, or any local or internal network IPs.
（3）The notify_url should not include any parameters.
Common errors:
Error description
Error example
URL only contains a domain, missing a specific path.
http://www.weixin.qq.com
URL does not start with https:// or http://, missing domain or IP.
./PayNotify.aspx
URL contains a local or internal network IP.
http://127.0.0.1/pay/notify.php
Non-URL formatted string.
xxxxxxx, 1234567, test
Notes on callback handling logic
The backend code handling the notify_url should not include login state verification.
Upon receiving a payment result notification, the merchant system must respond within 5 seconds. Otherwise, the application payment system will consider the notification failed and will resend it.
The same notification may be sent multiple times to the merchant system. The merchant system must correctly handle duplicate notifications. If the notification has already been processed, directly return a success response to the payment system.
﻿
﻿
﻿

Was this page helpful?

You can also Contact Sales or Submit a Ticket for help.

Yes

Property	Type	‍Required	Description
out_trade_no	string	True	Order number.

Error description	Error example
URL only contains a domain, missing a specific path.	http://www.weixin.qq.com
URL does not start with https:// or http://, missing domain or IP.	./PayNotify.aspx
URL contains a local or internal network IP.	http://127.0.0.1/pay/notify.php
Non-URL formatted string.	xxxxxxx, 1234567, test

tencent cloud

Sign Up

Log in

Compute

Microservice

Data Migration

Database SaaS Tool

Data Security

Application Security

Big Data

Tencent Big Model

Internet of Things

Stream Services

Cloud Real-time Rendering

Management and Audit Tools

Edge Computing

Serverless

Relational Database

Networking

Business Security

Domains & Websites

Face Recognition

AI Platform Service

Middleware

Media On-Demand

Game Services

Developer Tools

Container

Essential Storage Service

Enterprise Distributed DBMS

CDN and Acceleration

Security Services

Enterprise Applications

Voice Technology

Natural Language Processing

Communication

Media Process Services

Education Sevices

Monitor and Operation

Distributed cloud

Data Process and Analysis

NoSQL Database

Network Security

Cloud Security

Office Collaboration

Image Creation

Optical Character Recognition

Interactive Video Services

Media SDK

Cloud Resource Management

More

1. Query order status

API description:

Request method: Get

Request URL:

Request parameters

Response parameters

Response example:

2. Close an order

API description:

Request method: Post

Request URL:

Request parameters

Response parameters

Response example:

3. Place an order in a mini program

API description:

Request method: Post

Request URL:

Request parameters

Response parameters

Response example:

4. Payment callback

API description:

Request method: Post

Request URL:

Request parameters

Response parameters

Response example:

Data types