Deduction
Update Time:2025.03.21The deduction request implements deduction according to the priority payment method recorded in the signed contract. If the deduction fails, the other payment methods of the user will be polled in turn.
|
1. API Intro
Applicable object: Common mode Institutional mode
Request Url: https://apihk.mch.weixin.qq.com/v3/global/papay/transactions
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 | |||
---|---|---|---|---|---|---|---|
App ID | appid | string[1,32] | Yes | Body Appid bound to the merchant ID | |||
Sub-merchant ID | sub_mchid | string[1,32] | Yes | Body Sub-merchant ID allocated by WeChat Pay | |||
App ID of the service provider | sp_appid | string[1,32] | Yes | Body Appid bound to the service provider | |||
App ID of the sub-merchant | sub_appid | string[1,32] | No | Body Appid bound to the sub-merchant ID for initiating signing | |||
Goods description | description | string[1,128] | Yes | Brief description of the goods or payment slip, in this format: Store Brand Name-City Branch Store Name-Actual Goods Name | |||
Merchant data | attach | string[1,127] | No | Additional data, returned in the query API and payment notification without any changes; this field is used for the custom order data carried by the merchant | |||
Notification address | notify_url | string[1,256] | Yes | Callback address for receiving the result notification from WeChat Pay asynchronously; the notification URL must be an URL that is accessible by the external network and cannot carry parameters. Please use an HTTPS protocol link | |||
Merchant order No. | out_trade_no | string[1,32] | Yes | Order No. inside the merchant system, which consists of 32 characters and can contain letters; to change the authorization code, you must replace the merchant order No. with a new one. For other information, please refer to Merchant order No. | |||
Goods tag | goods_tag | string[1,32] | No | Goods tag, which is a parameter of the coupon or price reduction function. For more information, please refer to Coupon or price reduction | |||
Merchant category code (MCC] | merchant_category_code | string[1,16] | Yes | Merchant category code | |||
Auto-debit contract ID | contract_id | string[1,64] | Yes | Auto-debit contract ID returned by WeChat after successful signing | |||
Order amount | amount | object | 是 | Body Order amount information, which is detailed below | |||
| |||||||
cene information | scene_info | object | No | Body Scene information object, which is detailed below | |||
|
Example:
Scenario 1:Common mode
Scenario 2:Service Provide Mode/Institution Mode
3. Response Parameters
Name | Variable Name | Type | Required | Description | |||
---|---|---|---|---|---|---|---|
Merchant ID | mchid | string[1,32] | Yes | Merchant ID allocated by WeChat Pay | |||
App ID | appid | string[1,32] | Yes | Appid bound to the merchant ID | |||
Merchant ID of the service provider | sp_mchid | string[1,32] | Yes | The institution's merchant ID allocated by WeChat Pay | |||
Sub-merchant ID | sub_mchid | string[1,32] | Yes | Sub-merchant ID allocated by WeChat Pay | |||
App ID of the service provider | sp_appid | string[1,32] | Yes | Appid bound to the service provider’s Official Account | |||
App ID of the sub-merchant | sub_appid | string[1,32] | No | Mini program appid of the sub-merchant who initiates the signing | |||
Merchant order No. | out_trade_no | string[1,32] | Yes | Returned merchant order No. | |||
WeChat Pay order No. | transaction_id | string[1,32] | Yes | WeChat Pay order No. | |||
Merchant data | attach | string[1,127] | No | Additional data, returned in the query API and payment notification without any changes; this field is used for the custom order data carried by the merchant | |||
Transaction type | trade_type | string[1,16] | Yes | Deduction payment | |||
Paying bank | bank_type | string[1,32] | No | Returned after successful payment. Bank type is a bank ID of string type. For the list of specific values, please refer to bank type | |||
Payment completion time | success_time | string[1,64] | No | Payment completion time, in the rfc3339 format, e.g., 2018-06-08T10:34:56+08:00 indicates 10:34:56 a.m. on June 8, 2018 of Beijing time | |||
Transaction state | trade_state | string[1,32] | Yes | SUCCESS — Payment success | |||
Transaction state description | trade_state_desc | string[1,256] | Yes | Description of the current order status and guidance for the next operation | |||
Merchant category code (MCC] | merchant_category_code | string[1,16] | Yes | Merchant category code | |||
Payer | payer | object | No | Body Returned after successful payment. Payer information, which is detailed below | |||
| |||||||
Order amount | amount | object | Yes | Body Returned after successful payment. Order amount information, which is detailed below | |||
| |||||||
Promotion function | promotion_detail | array | No | Body Returned after successful payment. Promotion function information, which is detailed below | |||
|
Example:
Normal return
4. Error Codes
Error Codes | Error Message | Description | Solution |
---|---|---|---|
400 | PARAM_ERROR | Parameter error | Please check the request parameter format. |
500 | SYSTEMERROR | System error | Please try the request again |
400 | INVALID_REQUEST | Parameters do not match the business rules | Please check the parameters and makes sure they follow the ruless |
404 | NO_AUTH | The signed contract does not exist | Please check whether the signed contract number is correct and whether the contract has been terminated |
404 | USER_NOT_EXIST | User account is canceled | Check if the WeChat account of the user for deduction has been canceled |
400 | ORDERPAID | The order has been paid | Check if the order is paid repeated; if it is a new order, submit the new order No. |
400 | ORDERCLOSED | The order is closed | The order No. of the merchant is abnormal. Please place an order again |
400 | ALREADY_EXISTS | The order number is already used | Please check the order number and retry with a new one。 |
500 | BANKERROR | The bank of the paying bank card is performing channel maintenance | The user's bank card is in error. It is advised to change the order and try again |
403 | CONTRACTERROR | The agreement has expired | Please check whether the signed contract number has expired |
403 | USER_ERROR | There is risk in the transaction | Please contact the user to confirm whether any illegal operation has been performed using the WeChat ID. In case of any questions, please contact WeChat customer service to termination risk control |
403 | RULE_LIMIT | The user’s account payment has reached the upper limit | The merchant side initiates password verification payment to the user |
403 | NOTENOUGH | Insufficient balance | It is recommended that the user supplement fund or the merchant initiate advance payment |