Native Payment Order Placement
Update Time:2025.03.21For scenarios other than the Quick Pay method, the Merchant’s backend calls this API to create an advance transaction in the WeChat payment service backend, and initiates the payment process via payment by QR Code. JSAPI, App and other payment methods after the order is submitted successfully.
1. API intro
Applicable object: Common mode Institutional mode
Request URL: https://apihk.mch.weixin.qq.com/v3/global/transactions/native
Request method: POST
Path parameter is a path parameter.
Query parameter needs to be passed in the request URL.
Body parameter needs to be passed in the request JSON.
2. Request Parameters
Name | Variable Name | Type | Required | Description | |||
---|---|---|---|---|---|---|---|
APPID | appid | string[1,32] | Yes | Body APPID corresponding to the Service Account applied for by the merchant on the WeChat Official Accounts Platform | |||
Merchant ID | mchid | string[1,32] | Yes | Body Merchant ID assigned by WeChat Pay | |||
Organization APPID | sp_appid | string[1,32] | Yes | Body APPID corresponding to the Service Account applied for by the institution on the WeChat Official Accounts Platform | |||
Sub-merchant APPID | sub_appid | string[1,32] | No | Body APPID corresponding to the Service Account applied for by the sub-merchant on the WeChat Official Accounts Platform | |||
Institution's Merchant ID | sp_mchid | string[1,32] | Yes | Body Institution's Merchant ID assigned by WeChat Pay | |||
Sub-merchant ID | sub_mchid | string[1,32] | Yes | Body Sub-merchant ID assigned by WeChat Pay | |||
Merchant order No. | out_trade_no | string[1,32] | Yes | Body The order No. in the merchant system with a length of not more than 32 characters, including letters. If the authorization code changes, a new merchant order No. must be used. For more information, see Merchant Order No. | |||
Transaction type | trade_type | string[1,16] | Yes | Body | |||
Notification address | notify_url | string[1,256] | Yes | Body The callback address to receive WeChat Pay result notifications asynchronously. The notification URL must be accessible by external networks, and is not allowed to carry any parameters. Use the HTTPS protocol URL. | |||
Merchant data | attach | string[1,127] | No | Body Additional data, which will be returned unchanged in the query API and payment notifications. This field is mainly used for the custom data in the orders of the merchant. | |||
Product description | description | string[1,128] | Yes | Body Brief description of the product or payment order in the following format: Name of the store brand - Name of the city branch - Name of the actual product. | |||
Product tag | goods_tag | string[1,32] | No | Body The product tag, which is a parameter for the voucher or discount feature. For more information, see Vouchers or Discounts. | |||
Payment method | limit_pay | string[1,32] | No | Body no_credit: Credit card cannot be used for payment | |||
Start time of a transaction | time_start | string[1,64] | No | Body Order generation time, in RFC3339 format. For example, 2018-06-08T10:34:56+08:00 represents BJT 10:34:56 June 8, 2018. | |||
End time of a transaction | time_expire | string[1,64] | No | Body Order expiration time, in RFC3339 format. For example, 2018-06-08T10:34:56+08:00 represents BJT 10:34:56 June 8, 2018. The order expiration time is specific to the order No. Since the code_url returned by the API is only valid for two hours, it is necessary to request the API again to obtain a new code_url after two hours. | |||
MCC code | merchant_cat egory_code | string[1,16] | Yes | Body Merchant Category Code | |||
Payer | payer | object | No | Body Payer information. For more information, see the description below. | |||
| |||||||
Order amount | amount | object | Yes | Body Information on the order amount. For more information, see the description below. | |||
| |||||||
Scenario information | scene_info | object | No | Body The scenario information object. For more information, see the description below. | |||
| |||||||
Discount feature | detail | Object | No | Body Discount feature info. For more information, see the description below. | |||
|
Request Example:
Institution Mode
Common Mode
3. Response Parameters
Response for successful request:
Name | Variable Name | Type | Required | Description |
---|---|---|---|---|
QR Code URL | code_url | string[1,64] | Yes | his field is returned when trade_type is NATIVE. This parameter should be used to create a QR Code that is displayed to the Payer later. |
Response for failed request:
Name | Variable Name | Type | Required | Description | |||
---|---|---|---|---|---|---|---|
Returned status code | code | string[1,32] | Yes | Error code. See the error code list for the enumerated values. | |||
Returned information | message | string[1,256] | Yes | Returned message. It indicates the reason for the error if not empty. | |||
Detailed error description | detail | object | No | It is returned when code is PARAM_ERROR. Details will be described below. | |||
|
Response Example:
SUCCESS
ERROR
4. Error Codes
Error Message | Description | Solution |
---|---|---|
INVALID_REQUEST | Invalid request | Check your program based on the error message returned by the API. |
TRADE_ERROR | Transaction failed | Prompt the user to change payment method |
SYSTEM_ERROR | System error | Call the payment API again with the original request parameters to confirm the result. If SYSTEMERROR is returned again, call the Revoke API and inform the user to change the payment method. |
PARAM_ERROR | Incorrect request parameter | Check your program based on the error message returned by the API. |
NOT_ENOUGH | Insufficient balance | Prompt the user that the balance is insufficient or to change the payment method |
AUTH_CODE_INVALID | Invalid payment code | Check if it is a WeChat payment code. Then initiate the payment again after replacing out_trade_no and the payment code. |