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.
Applicable object： Common mode Institutional mode
Request URL: https://apihk.mch.weixin.qq.com/v3/global/transactions/native
Request method: POST
| 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 Note:Only forCommon mode Example: wx8888888888888888 |
| Merchant ID | mchid | string[1,32] | Yes | Body Merchant ID assigned by WeChat Pay Note:Only forCommon mode Example: 1900000109 |
| 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 Note:Only forInstitutional mode Example: wx8888888888888888 |
| 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 Note:Only forInstitutional mode Example: wx8888888888888888 |
| Institution's Merchant ID | sp_mchid | string[1,32] | Yes | Body Institution's Merchant ID assigned by WeChat Pay Note:Only forInstitutional mode Example: 1900000109 |
| Sub-merchant ID | sub_mchid | string[1,32] | Yes | Body Sub-merchant ID assigned by WeChat Pay Note:Only forInstitutional mode Example: 1900000109 |
| 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. Example: 1217752501201407033233368018 |
| Transaction type | trade_type | string[1,16] | Yes | Body OfficialPayment：JSAPI Native Payment: NATIVE In-APP payment: APP H5 payment: MWEB QuickPay: MICROPAY MiniProgram payment: JSAPI Example: NATIVE |
| 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. Example: https://www.weixin.qq.com/wxpay/pay.php |
| 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. Example: Custom data |
| 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. Example: Tencent Image Store- Shenzhen Tencent Building - QQ Doll |
| 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. Example: WXG |
| Payment method | limit_pay | string[1,32] | No | Body no_credit: Credit card cannot be used for payment Example: no_credit |
| 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. Example: 2018-06-08T10:34:56+08:00 |
| 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. 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_cat egory_code | string[1,16] | Yes | Body Merchant Category Code Example: 4111 |
| 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. |
{
"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 |
|---|---|---|---|---|
| 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.
Only for Native Payment Example：weixin://wxpay/s/An4baqw |
| 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. |
{
"code_url": "weixin://wxpay/s/An4baqw"
}
| 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. |
Customer Service Tel
Business Development
9:00-18:00
Monday-Friday GMT+8
Technical Support
WeChat Pay Global
ICP證
