Deduction

Update Time:2025.03.21

The 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.

Tips:

The deduction interface returns the deduction result synchronously. The following three situations may occur:

  • If the deduction succeeds, the order details are returned.

  • If the deduction fails, the order is processed according to the error code and the corresponding suggested processing method.

  • The deduction interface times out. After the timeout, the order query interface can be called to obtain the order status, or the order status can be updated at the merchant side after the callback notification is received (see “Deduction Result Notification” for details), but the number of callbacks is limited, and WeChat does not guarantee that the merchant will receive the notification.


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
Note: Only for Common mode
Example: wxcbda96de0b165486

Sub-merchant ID

sub_mchid

string[1,32]

Yes

Body Sub-merchant ID allocated by WeChat Pay
Note: Only for Institutional mode
Example: 10000097

App ID of the service provider

sp_appid

string[1,32]

Yes

Body Appid bound to the service provider
Note: Only for Institutional mode
Example: wxcbda96de0b165486

App ID of the sub-merchant

sub_appid

string[1,32]

No

Body Appid bound to the sub-merchant ID for initiating signing
Note: Only for Institutional mode
Example: wxcbda96de0b165484

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
Example: Image store-Shenzhen Tengda-QQ Doll

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
Example: Custom data

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
Example: https://www.weixin.qq.com/wxpay/pay.php

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.
Example: 1217752501201407033233368018

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
Example: Goods_tag

Merchant category code (MCC]

merchant_category_code

string[1,16]

Yes

Merchant category code
Example: 1011

Auto-debit contract ID

contract_id

string[1,64]

Yes

Auto-debit contract ID returned by WeChat after successful signing
Example: Wx15463511252015071056489715

Order amount

amount

object

Body Order amount information, which is detailed below

Order amount

cene information

scene_info

object

No

Body Scene information object, which is detailed below

cene information

Example:

Scenario 1:Common mode

1POST
2https://apihk.mch.weixin.qq.com/v3/global/papay/transactions
3{
4	"appid": "wxcbda96de0b165486",
5	"description": "Image store-Shenzhen Tengda-QQ Doll",
6	"attach": "Custom data",
7	"notify_url": "https://wxpay.wxutil.com/pub_v2/pay/notify.v2.php",
8	"out_trade_no": "1217752501201407033233368018",
9	"goods_tag": "WXG",
10	"merchant_category_code": "1011",
11	"contract_id": "Wx15463511252015071056489715",
12	"amount": {
13		"total": 10000,
14		"currency": "HKD"
15	},
16	"scene_info": {
17		"device_ip": "59.37.125.32",
18		"device_id": "013467007045764"
19	}
20}    

Scenario 2:Service Provide Mode/Institution Mode

1POST
2https://apihk.mch.weixin.qq.com/v3/global/papay/transactions
3{
4	"sp_appid": "wxcbda96de0b165486",
5	"sub_mchid": "10000097",
6	"sub_appid": "wxcbda96de0b165484",
7	"description": "Image store-Shenzhen Tengda-QQ Doll",
8	"attach": "Custom data",
9	"notify_url": "https://wxpay.wxutil.com/pub_v2/pay/notify.v2.php",
10	"out_trade_no": "1217752501201407033233368018",
11	"goods_tag": "WXG",
12	"merchant_category_code": "1011",
13	"contract_id": "Wx15463511252015071056489715",
14	"amount": {
15		"total": 10000,
16		"currency": "HKD"
17	},
18	"scene_info": {
19		"device_ip": "59.37.125.32",
20		"device_id": "013467007045764"
21	}
22}  

 

3. Response Parameters

Name

Variable Name

Type

Required

Description

Merchant ID

mchid

string[1,32]

Yes

Merchant ID allocated by WeChat Pay
Note: Only for Common mode
Example: 10000091

App ID

appid

string[1,32]

Yes

Appid bound to the merchant ID
Note: Only for Common mode
Example: wxcbda96de0b165486

Merchant ID of the service provider

sp_mchid

string[1,32]

Yes

The institution's merchant ID allocated by WeChat Pay
Note: Only for Institutional mode
Example: 10000098

Sub-merchant ID

sub_mchid

string[1,32]

Yes

Sub-merchant ID allocated by WeChat Pay
Note: Only for Institutional mode
Example: 10000097

App ID of the service provider

sp_appid

string[1,32]

Yes

Appid bound to the service provider’s Official Account
Note: Only for Institutional mode
Example: wxcbda96de0b165486

App ID of the sub-merchant

sub_appid

string[1,32]

No

Mini program appid of the sub-merchant who initiates the signing
Note: Only for Institutional mode
Example: wxcbda96de0b165484

Merchant order No.

out_trade_no

string[1,32]

Yes

Returned merchant order No.
Example: 1217752501201407033233368018

WeChat Pay order No.

transaction_id

string[1,32]

Yes

WeChat Pay order No.
Example: 1217752501201407033233368018

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
Example: Custom data

Transaction type

trade_type

string[1,16]

Yes

Deduction payment
Example: AUTH

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
CMC and other bank card types in the Chinese mainland
WPHK: payment by Hong Kong Wallet
Example: WPHK

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
Example: 2018-06-08T10:34:56+08:00

Transaction state

trade_state

string[1,32]

Yes

SUCCESS — Payment success
REFUND — Transfer to refund
NOTPAY — Not paid
CLOSED — Closed
PAYERROR — Payment failed
USERPAYING — payment in progress
Example: SUCCESS

Transaction state description

trade_state_desc

string[1,256]

Yes

Description of the current order status and guidance for the next operation
Example: Payment failed. Please order again to make payment

Merchant category code (MCC]

merchant_category_code

string[1,16]

Yes

Merchant category code
Example: 1011

Payer

payer

object

No

Body Returned after successful payment. Payer information, which is detailed below

Payer

Order amount

amount

object

Yes

Body Returned after successful payment. Order amount information, which is detailed below

Order amount

Promotion function

promotion_detail

array

No

Body Returned after successful payment. Promotion function information, which is detailed below

Promotion function

Example:

Normal return

1{
2  "mchid": "10000091",
3  "appid": "wxcbda96de0b165486",
4  "out_trade_no": "1217752501201407033233368018",
5  "transaction_id": "1217752501201407033233368018",
6  "attach": "Custom data",
7  "trade_type": "PAP",
8  "bank_type": "WPHK",
9  "success_time": "2018-06-08T10:34:56+08:00",
10  "trade_state": "SUCCESS",
11  "trade_state_desc": "Payment failed. Please order again to make payment",
12  "merchant_category_code": "1011",
13  "payer": {
14    "openid": "oUpF8uMuAJO_M2pxb1Q9zNjWeS6a"
15  },
16  "amount": {
17    "total": 888,
18    "payer_total": 888,
19    "currency": "CNY",
20    "payer_currency": "HKD",
21    "exchange_rate": {
22      "type": "SETTLEMENT_RATE",
23      "rate": 80000000
24    }
25  },
26  "scene_info": {
27    "device_id": "013467007045764",
28    "device_ip": "128.0.0.1"
29  },
30  "promotion_detail": [
31    {
32      "promotion_id": "109519",
33      "name": "Single item discount-6",
34      "scope": "SINGLE",
35      "type": "COUPON",
36      "amount": 5,
37      "currency": "HKD",
38      "activity_id": "931386",
39      "wxpay_contribute_amount": 100,
40      "merchant_contribute_amount": 100,
41      "other_contribute_amount": 5,
42      "goods_detail": {
43        "goods_id": "124512",
44        "goods_remark": "1001",
45        "discount_amount": 100,
46        "quantity": 1,
47        "price": 528800
48      }
49    }
50  ]
51}    


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

 

 

About  WeChat  Pay

Powered By Tencent & Tenpay Copyright©

2005-2025 Tenpay All Rights Reserved.

Contact Us
Wechat Pay Global

WeChat Pay Global

Contact Us

Customer Service Tel

+86 571 95017

9:00-18:00 Monday-Friday GMT+8

Business Development

wxpayglobal@tencent.com

Developer Support

wepayTS@tencent.com

Wechat Pay Global

About Tenpay
Powered By Tencent & Tenpay Copyright© 2005-2025 Tenpay All Rights Reserved.