支付扣款

更新时间:2025.01.07

可应用于定期扣款或需事后扣款以期提高效率的场景。例如:水电煤缴费、话费、充电宝租借等场景。

注意:

  • 扣费请求按签约协议中记录的优先支付方式扣费,扣费失败后则依次轮询用户的其它支付方式

  • 扣款接口同步返回扣款结果,有以下三种情况:

  1. 如果扣款成功,则返回订单详情。

  2. 扣款失败,根据错误码和对应的建议处理方式处理。

  3. 扣款接口超时,超时后可通过调用查单接口获取订单状态,也可等待回调通知来更新商户侧订单状态,但回调次数有限制,不保证商户最终能收到通知。


1. 接口说明

适用对象: 直连模式 机构模式

请求URL:https://apihk.mch.weixin.qq.com/v3/global/papay/transactions

请求方式:POST

 

Path 指该参数为路径参数

Query 指该参数为URL参数

Body 指该参数需在请求JSON传参


2. 请求参数

参数名

变量

类型[长度限制]

必填

描述

应用ID

appid

string[1,32]

Body 直连模式必填,商户号绑定的appid
注意:仅适用于直连模式
示例值:wxcbda96de0b165486

子商户号

sub_mchid

string[1,32]

Body 服务商模式必填,微信支付分配的子商户号
注意:仅适用于机构模式
示例值:10000097

服务商应用ID

sp_appid

string[1,32]

Body 服务商模式必填,服务商绑定的appid
注意:仅适用于机构模式
示例值:wxcbda96de0b165486

子商户应用ID

sub_appid

string[1,32]

Body 发起签约的子商户号绑定的appid
示例值:wxcbda96de0b165484

商品描述

description

string[1,128]

Body 商品或支付单简要描述,格式要求:门店品牌名-城市分店名-实际商品名称
示例值:image形象店-深圳腾大- QQ公仔

商户数据

attach

string[1,127]

Body 附加数据,在查询API和支付通知中原样返回,该字段主要用于商户携带订单的自定义数据
示例值:自定义数据

通知地址

notify_url

string[1,256]

Body 异步接收微信支付结果通知的回调地址,通知url必须为外网可访问的url,不能携带参数。请使用https协议链接
示例值:https://www.weixin.qq.com/wxpay/pay.php

商户订单号

out_trade_no

string[1,32]

Body 商户系统内部的订单号
示例值:1217752501201407033233368018

商品标记

goods_tag

string[1,32]

Body 商品标记,代金券或立减优惠功能的参数
示例值:实例值

MCC码

merchant_category_code

string[1,16]

Body 商户行业编码,可参见商户行业编码表
示例值:1011

委托代扣协议id

contract_id

string[1,64]

Body 签约成功后,微信返回的委托代扣协议id
示例值:Wx15463511252015071056489715

订单金额

amount

object

Body 订单金额信息

订单金额

场景信息

scene_info

object

Body 场景信息对象

场景信息

请求示例

场景一:直连模式

1POST
2https://apihk.mch.weixin.qq.com/v3/global/papay/transactions
3{
4		"appid": "wxcbda96de0b165486",
5		"description": "PAPAuto-debit支付测试",
6		"attach": "支付测试",
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}

场景二:服务商模式/机构模式

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": "PAPAuto-debit支付测试",
8		"attach": "支付测试",
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. 返回参数

参数名

变量

类型[长度限制]

必填

描述

商户号

mchid

string[1,32]

微信支付分配的商户号
注意:仅适用于直连模式
示例值:10000091

应用ID

appid

string[1,32]

商户号绑定的appid
注意:仅适用于直连模式
示例值:wxcbda96de0b165486

服务商商户号

sp_mchid

string[1,32]

微信支付分配的机构商户号
注意:仅适用于机构模式
示例值:10000098

子商户号

sub_mchid

string[1,32]

微信支付分配的子商户号
注意:仅适用于机构模式
示例值:10000097

服务商应用ID

sp_appid

string[1,32]

服务商绑定的appid
注意:仅适用于机构模式
示例值:wxcbda96de0b165486

子商户应用ID

sub_appid

string[1,32]

发起签约的子商户号绑定的appid
注意:仅适用于机构模式
示例值:wxcbda96de0b165484

商户订单号

out_trade_no

string[1,32]

返回的商户订单号
示例值:1217752501201407033233368018

微信支付订单号

transaction_id

string[1,32]

微信支付订单号
示例值:1217752501201407033233368018

商户数据

attach

string[1,127]

附加数据,在查询API和支付通知中原样返回,该字段主要用于商户携带订单的自定义数据
示例值:自定义数据

交易类型

trade_type

string[1,16]

代扣支付
示例值:AUTH

付款银行

bank_type

string[1,32]

银行类型
示例值:WPHK:香港钱包支付

支付完成时间

success_time

string[1,64]

支付完成时间,格式为rfc3339格式,如2018-06-08T10:34:56+08:00 代表北京时间2018年06月08日10时34分56秒
示例值:2018-06-08T10:34:56+08:00

交易状态

trade_state

string[1,16]

枚举值:
SUCCESS:支付成功
REFUND:转入退款
NOTPAY:未支付
CLOSED:已关闭
PAYERROR:支付失败
USERPAYING:用户支付中
示例值:SUCCESS

交易状态描述

trade_state_desc

string[1,256]

对当前订单状态的描述和下一步操作的指引
示例值:支付失败,请重新下单支付

MCC码

merchant_category_code

string[1,16]

商户行业编码
示例值:1011

支付者

payer

object

Body 成功时才返回。支付者信息,详细说明见下文

支付者

订单金额

amount

object

Body 成功时才返回。订单金额信息,详细说明见下文

订单金额

优惠功能

promotion_detail

array

Body 成功时才返回。优惠功能信息,详细说明见下文

优惠功能

返回示例

正常示例

1{
2		"amount": {
3			"currency": "HKD",
4			"payer_currency": "CNY",
5			"payer_total": 8,
6			"total": 10
7		},
8		"appid": "wx7bc98d929da735fe",
9		"attach": "testruoyu",
10		"bank_type": "CFT",
11		"mchid": "132012662",
12		"merchant_category_code": "0",
13		"out_trade_no": "autotest_20210608201410_9263565",
14		"payer": {
15			"openid": "of8YZ6A_ySrPYzjX7joXo_h2CI44"
16		},
17		"promotion_detail": [{
18			"promotion_id": "109519",
19			"name": "单品惠-6",
20			"scope": "SINGLE",
21			"type": "COUPON",
22			"amount": 5,
23			"currency": "HKD",
24			"activity_id": "931386",
25			"wxpay_contribute_amount": 100,
26			"merchant_contribute_amount": 100,
27			"other_contribute_amount": 5,
28			"goods_detail": {
29				"goods_id": "124512",
30				"goods_remark": "1001",
31				"discount_amount": 100,
32				"quantity": 1,
33				"price": 528800
34			}
35		}]
36		"success_time": "2021-12-09T10:56:27+08:00",
37		"trade_state": "SUCCESS",
38		"trade_state_desc": "支付成功",
39		"trade_type": "AUTH",
40		"transaction_id": "4200001136202112092809736426"
41	}


4. 错误码

状态码

错误码

描述

解决方案

400

PARAM_ERROR

参数错误

请检查参数格式是否符合协议规范

400

INVALID_REQUEST

参数不符合业务规则

重入请求时请保持参数前后一致

404

NO_AUTH

签约协议不存在

请检查签约协议号是否正确,是否已解约

404

USER_NOT_EXIST

用户账户注销

请确认扣款用户的微信账号是否注销

400

ORDER_PAID

订单已支付

请确认该订单号是否重复支付,如果是新单,请使用新订单号提交

400

ORDER_CLOSED

订单已关闭

商户订单号异常或者支付失败,请重新下单支付

400

ALREADY_EXISTS

订单已存在

商户订单号对应的订单已存在,请查单确认订单状态

500

BANK_ERROR

支付银行卡所在行渠道维护中

用户银行卡错误,建议换单重试

403

CONTRACT_ERROR

协议已过期

请检查签约协议号是否已过期

403

USER_ERROR

该笔交易存在风险

请联系用户,明确微信号是否有违规操作,如有疑问可联系微信客服接触风险控制

403

RULE_LIMIT

用户账户支付已达上限

商户侧对用户发起验密支付

403

NOT_ENOUGH

余额不足

建议用户补充资金或商户发起垫资支付

500

SYSTEM_ERROR

系统错误

建议发起查单,获取此次支付结果,如需换单重试,请先调用撤销订单接口再换单支付,避免重复支付

 

 

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.