Latest update time：2022.03.10 Release notes
For 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.
Request URL: https://api.mch.weixin.qq.com/hk/v3/transactions/native
Request method: POST
Applicable object:Common modeInstitutional mode
API Rules: https://wechatpay-api.gitbook.io/wechatpay-api-v3
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.
| Name | Variable Name | Type | Required | Description |
|---|---|---|---|---|
| Merchant ID | mchid | string(32) | Yes | body Merchant ID assigned by WeChat Pay Note: Only forCommon mode Example：1900000109 |
| APPID | appid | string(32) | Yes | body APPID corresponding to the mobile app applied by the merchant on the WeChat Open Platform Note: Only forCommon mode Example：wx8888888888888888 |
| Sub-merchant ID | sub_mchid | string(32) | Yes | body Sub-merchant ID assigned by WeChat Pay Note: Only forInstitutional mode Example：1900000109 |
| Institution's Merchant ID | sp_mchid | string(32) | Yes | body Institution's Merchant ID assigned by WeChat Pay Note: Only forInstitutional mode Example：1900000100 |
| Organization APPID | sp_appid | string(32) | Yes | body APPID corresponding to the Service Account applied for by the institution on the WeChat Official Accounts Platform Note: Only forInstitutional mode Example：wx8888888888888888 |
| Sub-merchant APPID | sub_appid | string(32) | No | body APPID corresponding to the mobile app applied for by the sub-merchant on the WeChat Open Platform |
| Product description | description | string(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. Example：Image Store - Tencent Building in Shenzhen - QQ Doll |
| Merchant data | attach | string(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. Example：Custom data |
| Notification address | notify_url | string(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. Example：https://www.weixin.qq.com/wxpay/pay.php |
| Merchant order No. | out_trade_no | string(32) | Yes | body The order No. in the merchant system with the 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. Example：1217752501201407033233368018 |
| Product tag | goods_tag | string(32) | No | body The product tag, which is a parameter for the voucher or discount feature. For more information, see Vouchers or Discounts. Example：WXG |
| Transaction type | trade_type | string(16) | Yes | bodyOfficialPayment：JSAPI Native Payment: NATIVE In-APP payment: APP H5 payment: MWEB QuickPay: MICROPAY MiniProgram payment: JSAPI Example：NATIVE |
| Payment method | limit_pay | string(32) | No | bodyno_credit - Credit card cannot be used for payment Example：no_credit |
| Start time of a transaction | time_start | string(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. Example：2018-06-08T10:34:56+08:00 |
| End time of a transaction | time_expire | string(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. It is recommended that the minimum expiration time interval be greater than 1 minute. Example：2018-06-08T10:34:56+08:00 |
| MCC code | merchant_category_code | string(16) | Yes | body Merchant category codes,See merchant_category_code Example：1011 |
| + Payer | payer | object | No | body Payer information. For more information, see Merchant category codes. |
| +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. |
{
"sp_appid": "wxdace645e0bc2c424",
"sp_mchid": "10000100",
"sub_mchid": "20000100",
"out_trade_no": "YX202111100020Z",
"merchant_category_code": "4111",
"notify_url": "https://wxpay.wxutil.com/pub_v2/pay/notify.v2.php",
"trade_type": "NATIVE",
"amount": {
"total": 10,
"currency": "HKD"
},
"attach": "QR code test",
"description": "QR code test",
"goods_tag": "001",
"detail":{
"cost_price": 10000,
"receipt_id": "1234",
"goods_detail": [{
"goods_id": "iphone6s_16G",
"wxpay_goods_id": "1001",
"goods_name": "iPhone6s 16G",
"quantity": 1,
"price": 10
}]
},
"scene_info": {
"payer_client_ip": "14.23.150.211",
"device_ip": "59.37.125.32",
"device_id": "013467007045764",
"operator_id": "P001",
"store_info": {
"id": "SZTX001"
}
}
}
| Name | Variable Name | Type | Required | Description |
|---|---|---|---|---|
| Returned status code | code | string(32) | Yes | Error code. See the error code list for the enumerated values. Example：INVALID_REQUEST |
| Returned message | message | string(256) | Yes | Returned message. It indicates the reason for the error if not empty. Example：Parameter format verification error |
| + Detailed error description | detail | object | No | It is returned when code is PARAM_ERROR. Details will be described below. |
| Name | Variable Name | Type | Required | Description |
|---|---|---|---|---|
| QR Code URL | code_url | string(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.
Only for QR Code Payment Example：weixin://wxpay/s/An4baqw |
| Name | Description | Solution |
|---|---|---|
| NOAUTH | The merchant does not have access to the API. | Let the merchant to apply for access to the API. |
| NOTENOUGH | Insufficient balance | The user's account balance is insufficient. Top up or use another payment card. |
| ORDERPAID | Merchant order paid. | Merchant order paid. Other operation not needed. |
| ORDERCLOSED | Order closed | Order closed. Place a new order. |
| SYSTEMERROR | System error | System exception. Call again with the same parameters. |
| APPID_NOT_EXIST | APPID does not exist. | Check whether APPID is correct. |
| MCHID_NOT_EXIST | MCHID does not exist. | Check whether MCHID is correct. |
| APPID_MCHID_NOT_MATCH | appid and mchid do not match. | Check whether appid and mchid match. |
| LACK_PARAMS | Missing parameters | Check if the parameters are complete. |
| OUT_TRADE_NO_USED | Duplicate merchant order number | Check whether the merchant order number is submitted repeatedly. |
| SIGNERROR | Signature error | Check if signature parameters and methods meet the algorithm requirements. |
| REQUIRE_POST_METHOD | Use post method. | Check whether the request parameter is submitted via post method. |
| POST_DATA_EMPTY | post is empty. | Check whether post is empty. |
| NOT_UTF8 | Incorrect encoding format | Use UTF-8 encoding format. |
Customer Service Tel
Business Development
9:00-18:00
Monday-Friday GMT+8
Technical Support
WeChat Pay Global
ICP证