WeChat Pay Open Platform

Return Home / Auto-debit / Deduction API

Deduction API

Latest update time：2021.08.18 Release notes

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.

API Intro

Request Url:https://apihk.mch.weixin.qq.com/v3/global/papay/transactions

Request method:POST

API rules: https://wechatpay-api.gitbook.io/wechatpay-api-v3

Applicable object:Common modeInstitutional mode

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.

Request Parameters

Name

Variable Name

Type

Required

Description

App ID

appid

string[1,32]

Yes

body Appid bound to the merchant ID
Note: Only forCommon mode
Example:wxcbda96de0b165486

Sub-merchant ID

sub_mchid

string[1,32]

Yes

body Sub-merchant ID allocated by WeChat Pay
Note: Only forInstitutional mode
Example:10000097

App ID of the service provider

sp_appid

string[1,32]

Yes

body Appid bound to the service provider
Note: Only forInstitutional mode
Example:wxcbda96de0b165486

App ID of the sub-merchant

sub_appid

string[1,32]

body Appid bound to the sub-merchant ID for initiating signing
Note: Only forInstitutional 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]

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]

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

Yes

Order amount information, which is detailed below

Name	Variable Name	Type	Required	Description
Total amount	total	int	Yes	Total order amount, in the minimum unit of currency, which must be an integer. For details, please refer to the transaction amount Example：888
Currency type	currency	string[1,16]	Yes	Three letter code complying with the ISO 4217 standard Example：CNY

+cene information

scene_info

object

Scene information object, which is detailed below

Name	Variable Name	Type	Required	Description
Merchant-end device ID	device_id	string[1,32]	No	Terminal device ID (customized by the merchant, e.g., a store No.) Example：013467007045764
Merchant-end device IP address	device_ip	string[1,40]	No	The device IP address at the merchant side, accessed from the public network export IP address, supporting IPv6 Example：128.0.0.1

Example：


POST
https://apihk.mch.weixin.qq.com/v3/global/papay/transactions
{
	"appid": "wxcbda96de0b165486",
	"description": "Image store-Shenzhen Tengda-QQ Doll",
	"attach": "Custom data",
	"notify_url": "https://wxpay.wxutil.com/pub_v2/pay/notify.v2.php",
	"out_trade_no": "1217752501201407033233368018",
	"goods_tag": "WXG",
	"merchant_category_code": "1011",
	"contract_id": "Wx15463511252015071056489715",
	"amount": {
		"total": 10000,
		"currency": "HKD"
	},
	"scene_info": {
		"device_ip": "59.37.125.32",
		"device_id": "013467007045764"
	}
}


POST
https://apihk.mch.weixin.qq.com/v3/global/papay/transactions
{
	"sp_appid": "wxcbda96de0b165486",
    "sub_mchid": "10000097",
    "sub_appid": "wxcbda96de0b165484",
	"description": "Image store-Shenzhen Tengda-QQ Doll",
	"attach": "Custom data",
	"notify_url": "https://wxpay.wxutil.com/pub_v2/pay/notify.v2.php",
	"out_trade_no": "1217752501201407033233368018",
	"goods_tag": "WXG",
	"merchant_category_code": "1011",
	"contract_id": "Wx15463511252015071056489715",
	"amount": {
		"total": 10000,
		"currency": "HKD"
	},
	"scene_info": {
		"device_ip": "59.37.125.32",
		"device_id": "013467007045764"
	}
}

Return Data

Name

Variable Name

Type

Required

Description

Merchant ID

mchid

string[1,32]

Yes

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

App ID

appid

string[1,32]

Yes

Appid bound to the merchant ID
Note: Only forCommon 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 forInstitutional mode
Example:10000098

Sub-merchant ID

sub_mchid

string[1,32]

Yes

Sub-merchant ID allocated by WeChat Pay
Note: Only forInstitutional 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 forInstitutional mode
Example:wxcbda96de0b165486

App ID of the sub-merchant

sub_appid

string[1,32]

Mini program appid of the sub-merchant who initiates the signing
Note: Only forInstitutional 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]

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]

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]

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

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

Name	Variable Name	Type	Required	Description
User ID (directly connected merchant]	openid	string[1,128]	Yes	Openid of the user under the merchant’s appid Note: Only forCommon mode Example：M3pxb1Q9zNjWeS6o
User ID (service provider]	sp_openid	string[1,128]	Yes	User’s unique ID under the corresponding merchant sp_appid, returned only when sp_appid is passed in Note: Only forInstitutional mode Example：M2pxb1Q9WNjWeS6o
User ID (sub-merchant]	sub_openid	string[1,128]	No	User’s unique ID under sub_appid of the acquiring bank, returned only when sub_appid is passed in Note: Only forInstitutional mode Example：M2pxb1Q9zNjWeS61

+Order amount

amount

object

Yes

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

Name

Variable Name

Type

Required

Description

Order amount

total

int

Yes

Total order amount, in the minimum unit of currency, which must be an integer. For details, please refer to transaction amount
Example：888

User payment amount

payer_total

int

Yes

User's actual payment amount, in the minimum unit of currency, which must be an integer. For details, please refer to the transaction amount
Example：888

Currency of order price

currency

string[1,16]

Yes

Three letter code complying with the ISO 4217 standard
Example：CNY

User’s payment currency

payer_currency

string[1,16]

Yes

Three letter code complying with the ISO 4217 standard
Example：HKD

+Exchange rate information

exchange_rate

object

Exchange rate information object, which is detailed below

Name	Variable Name	Type	Required	Description
Exchange rate type	type	string[1,32]	No	SETTLEMENT_RATE, namely, the exchange rate of the price currency and settlement currency Example：SETTLEMENT_RATE
Exchange rate value	rate	int	No	The rate value is the eighth power of the exchange ratio multiplied by 10. If the price currency is the same as the settlement currency and the exchange ratio is 1, then rate is 100000000; If the price currency is different from the settlement currency, e.g., the exchange ratio of US dollar to RMB is 6.5, then rate is 650000000 Example：80000000

+Promotion function

promotion_detail

object

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

Name

Variable Name

Type

Required

Description

Coupon ID

promotion_id

string[1,32]

Yes

Coupon/discount or price reduction ID
Example:109519

Promotion name

name

string[1,64]

Promotion name
Example:Single item discount-6

Promotion scope

scope

string[1,32]

GLOBAL - Global coupon
SINGLE - Single item discount
Example:SINGLE

Promotion type

type

string[1,32]

COUPON - Coupon, a recharge coupon that generates capital flow (the coupon currency of overseas merchants is the same as the payment currency)
DISCOUNT - Discount, a recharge discount that does not generate capital flow (the discount currency of overseas merchants is the same as the price currency)
Example:DISCOUNT

Discount amount

amount

int

Yes

Amount of discount enjoyed by the user
Example:5

Discount currency

currency

string[1,16]

Yes

Three letter code complying with the ISO 4217 standard
Example:HKD

Activity ID

activity_id

string[1,32]

Batch ID configured on the WeChat merchant background
Example:931386

Amount contributed by WeChat

wxpay_contribute_amount

int

Specifically referring to the discount created by the WeChat Pay merchant platform; the mount contributed is equal to the total amount of the discount
Example:0

Amount contributed by the merchant

merchant_contribute_amount

int

Specifically referring to the discount created by the merchant; the mount contributed is equal to the total amount of the discount
Example:0

Other contributed amount

other_contribute_amount

int

Amount contributed by other contributive parties
Example:5

+List of goods

goods_detail

Array

Goods information, in the JSON format

Name	Variable Name	Type	Required	Description
Goods ID	goods_id	string[1,32]	Yes	Consisting of one or more of half-angle upper and lower case letters, digits, strikethrough, and underscore Example:Goods ID
Goods remark	goods_remark	string[1,128]	No	A remark field, returned according to the original configuration; the field is set when coupon/discount is configured on the WeChat background Example:1001
Goods discount amount	discount_amount	int	Yes	Total discount amount of a single item Example:100
Goods quantity	quantity	int	Yes	Quantity of goods bought by the user Example:1
Goods price	price	int	Yes	Unit: cent. If the merchant provides a discount, the unit price after the discount needs to be transmitted (for example, if the user uses the paper discount 100-50 issued by the mall for a RMB100 order, the unit price of the goods in the activity should be the original unit price minus 50) Example:10000

Example：

Normal return


{
  "mchid": "10000091",
  "appid": "wxcbda96de0b165486",
  "out_trade_no": "1217752501201407033233368018",
  "transaction_id": "1217752501201407033233368018",
  "attach": "Custom data",
  "trade_type": "PAP",
  "bank_type": "WPHK",
  "success_time": "2018-06-08T10:34:56+08:00",
  "trade_state": "SUCCESS",
  "trade_state_desc": "Payment failed. Please order again to make payment",
  "merchant_category_code": "1011",
  "payer": {
    "openid": "oUpF8uMuAJO_M2pxb1Q9zNjWeS6a"
  },
  "amount": {
    "total": 888,
    "payer_total": 888,
    "currency": "CNY",
    "payer_currency": "HKD",
    "exchange_rate": {
      "type": "SETTLEMENT_RATE",
      "rate": 80000000
    }
  },
  "scene_info": {
    "device_id": "013467007045764",
    "device_ip": "128.0.0.1"
  },
  "promotion_detail": [
    {
      "promotion_id": "109519",
      "name": "Single item discount-6",
      "scope": "SINGLE",
      "type": "COUPON",
      "amount": 5,
      "currency": "HKD",
      "activity_id": "931386",
      "wxpay_contribute_amount": 100,
      "merchant_contribute_amount": 100,
      "other_contribute_amount": 5,
      "goods_detail": {
        "goods_id": "124512",
        "goods_remark": "1001",
        "discount_amount": 100,
        "quantity": 1,
        "price": 528800
      }
    }
  ]
}

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

WeChat Pay

Feedback

Feedback

Submitted successfully

Feedback

Network exception, please try again later

Auto-debit API

Deduction API

Tips：

API Intro

Request Parameters

Example：

Return Data

Example：

Error Codes

Release notes