支付押金（人脸支付）

更新时间：2024.11.18

应用场景

微信支付提供了四种付款方式供用户支付押金：付款码支付、人脸支付、JSAPI支付、APP支付。商户可根据场景需要选择支持哪种付款方式，也可以四种都支持，即四种方式都对接。

◆ 商户通过支付押金（人脸）接口发起押金支付请求；

◆ 用户使用微信支付完成押金支付，支付完成后扣除相应金额，并生成押金交易记录，下发押金支付凭证；

◆ 支付成功后，为用户下发押金支付凭证；

注意

当押金超过一个月未进行处理，会自动执行退款。

接口规则

请求Url	https://api.mch.weixin.qq.com/deposit/facepay
是否需要证书	否
请求方式	post
签名方式	HMAC-SHA256

请求参数

名称	变量名	必填	类型	示例值	描述
是否押金支付	deposit	是	String(1)	Y	是否押金人脸支付，Y-是,N-普通人脸支付
服务商应用ID	appid	是	String(32)	wx8888888888888888	服务商商户的APPID
商户号	mch_id	是	String(32)	1900000109	服务商商户的商户号
子商户应用ID	sub_appid	否	String(32)	wx8888888888888888	微信分配的子商户APPID，如需在支付完成后获取sub_openid则此参数必传。
子商户号	sub_mch_id	是	String(32)	1900000109	服务商通过进件后获得的特约商户号
设备号	device_info	否	String(32)	013467007045764	终端设备号(商户自定义，如门店编号)
随机字符串	nonce_str	是	String(32)	5K8264ILTKCH16CQ2502SI8ZNMTM67VS	随机字符串，不长于32位。推荐随机数生成算法
签名	sign	是	String(64)	C370BEC2BFD727A4B6845133519F3AD6C370BEC2BFD727A4B6845133519F3AD6	签名，详见签名生成算法
商品描述	body	是	String(128)	image形象店-深圳腾大- QQ公仔	商品或支付单简要描述，格式要求：门店品牌名-城市分店名-实际商品名称
商品详情	detail	否	String(6000)		单品优惠功能字段，需要接入详见“单品优惠参数说明”
附加数据	attach	否	String(127)	说明	附加数据，在查询API和支付通知中原样返回，该字段主要用于商户携带订单的自定义数据
商户订单号	out_trade_no	是	String(32)	1217472501201407033233367018	商户系统内部订单号，要求32个字符内，只能是数字、大小写字母_-\|*且在同一个商户号下唯一。详见商户订单号
总金额	total_fee	是	int	888	订单总金额，单位为分，只能为整数，详见支付金额
货币类型	fee_type	是	String(16)	CNY	符合ISO 4217标准的三位字母代码，默认人民币：CNY
终端IP	spbill_create_ip	是	String(16)	8.8.8.8	调用微信支付API的机器IP
指定支付方式	limit_pay	否	String(32)	no_credit	no_credit--指定不能使用信用卡支付
交易起始时间	time_start	否	String(14)	20091225091010	订单生成时间，格式为yyyyMMddHHmmss，如2009年12月25日9点10分10秒表示为20091225091010。其他详见时间规则
交易结束时间	time_expire	否	String(14)	20091227091010	订单失效时间，格式为yyyyMMddHHmmss，如2009年12月27日9点10分10秒表示为20091227091010
用户标识	openid	否	String(128)	oUpF8uMuAJO_M2pxb1Q9zNjWeS6o	用户在父商户APPID下的用户唯一标识
授权码	face_code	是	String(128)	b713b5d2-666c-48	人脸凭证，用于人脸支付
签名类型	sign_type	是	String(64)	HMAC-SHA256	签名类型，仅支持HMAC-SHA256

举例如下：

1<xml>
2  <appid>wx2421b1c4370ec43b</appid>
3  <attach>订单额外描述</attach>
4  <face_code> b713b5d2-666c-48b6-8c37-f15acf5a7069</face_code>
5  <openid> oHkLxtxS5pkpxVbVeVuqpPQviw5o </openid>
6  <body>押金人脸支付测试</body>
7  <device_info>1000</device_info>
8  <mch_id>10000100</mch_id>
9  <sub_mch_id>10000101</sub_mch_id>
10  <nonce_str>8aaee146b1dee7cec9100add9b96cbe2</nonce_str>
11  <out_trade_no>1415757673</out_trade_no>
12  <spbill_create_ip>14.17.22.52</spbill_create_ip>
13  <total_fee>1</total_fee>
14  <sign_type> HMAC-SHA256</sign_type>
15  <sign>C29DB7DB1FD4136B84AE35604756362C</sign>
16</xml>

注意

参数值用XML转义即可，CDATA标签用于说明数据不被XML解析器解析。

返回结果

名称	变量名	必填	类型	示例值	描述
返回状态码	return_code	是	String(16)	SUCCESS	SUCCESS/FAIL 此字段是通信标识，非交易标识，交易是否成功需要查看result_code来判断
返回信息	return_msg	否	String(128)	签名失败	返回信息，如非空，为错误原因签名失败参数格式校验错误

当return_code为SUCCESS的时候，还会包括以下字段：

名称	变量名	必填	类型	示例值	描述
服务商应用ID	appid	是	String(32)	wx8888888888888888	服务商商户的APPID
商户号	mch_id	是	String(32)	1900000109	服务商商户的商户号
子商户应用ID	sub_appid	否	String(32)	wx8888888888888888	微信分配的子商户APPID，如需在支付完成后获取sub_openid则此参数必传。
子商户号	sub_mch_id	是	String(32)	1900000109	服务商通过进件后获得的特约商户号
设备号	device_info	否	String(32)	013467007045764	调用接口提交的终端设备号
随机字符串	nonce_str	是	String(32)	5K8264ILTKCH16CQ2502SI8ZNMTM67VS	微信返回的随机字符串
签名	sign	是	String(64)	C380BEC2BFD727A4B6845133519F3AD6C380BEC2BFD727A4B6845133519F3AD6	签名，详见签名生成算法
业务结果	result_code	是	String(16)	SUCCESS	SUCCESS/FAIL
错误代码	err_code	否	String(32)	SYSTEMERROR	详细参见错误列表
错误代码描述	err_code_des	否	String(128)	系统错误	错误返回的信息描述

当return_code 和result_code都为SUCCESS的时，还会包括以下字段：

名称	变量名	必填	类型	示例值	描述
用户标识	openid	是	String(128)	Y	用户在父商户appid 下的唯一标识
是否关注公众账号	is_subscribe	是	String(1)	Y	用户是否关注公众账号，仅在公众账号类型支付有效，取值范围：Y或N;Y-关注;N-未关注
用户子标识	sub_openid	否	String(128)	Y	子商户appid下用户唯一标识，如需返回则请求时需要传sub_appid
是否关注子公众账号	sub_is_subscribe	否	String(1)	Y	用户是否关注子公众账号，仅在公众账号类型支付有效，取值范围：Y或N;Y-关注;N-未关注
交易类型	trade_type	是	String(16)	MICROPAY	支付类型为MICROPAY(即扫码支付)
付款银行	bank_type	是	String(32)	CMC	银行类型，采用字符串类型的银行标识，值列表详见银行类型
标价币种	fee_type	否	String(16)	CNY	符合ISO 4217标准的三位字母代码，默认人民币：CNY，其他值列表详见货币类型
标价金额	total_fee	是	int	888	订单总金额，单位为分，只能为整数，详见支付金额
现金支付币种	cash_fee_type	否	String(16)	CNY	符合ISO 4217标准的三位字母代码，默认人民币：CNY，其他值列表详见货币类型
现金支付金额	cash_fee	是	int	100	订单现金支付金额，详见支付金额
应结订单金额	settlement_total_fee	否	int	100	当订单使用了免充值型优惠券后返回该参数，应结订单金额=订单金额-免充值优惠券金额。
代金券金额	coupon_fee	否	int	100	“代金券”金额<=订单金额，订单金额-“代金券”金额=现金支付金额，详见支付金额
微信支付订单号	transaction_id	是	String(32)	1217472501201407033233368018	微信支付订单号
商户订单号	out_trade_no	是	String(32)	1217752501201407033233368018	商户系统内部订单号，要求32个字符内，只能是数字、大小写字母_-\|*且在同一个商户号下唯一。
商家数据包	attach	否	String(128)	123456	商家数据包，原样返回
支付完成时间	time_end	是	String(14)	20141030133525	订单生成时间，格式为yyyyMMddHHmmss，如2009年12月25日9点10分10秒表示为20091225091010。详见时间规则

举例：

1<xml>
2  <return_code><![CDATA[SUCCESS]]></return_code>
3  <return_msg><![CDATA[OK]]></return_msg>
4  <appid><![CDATA[wx2421b1c4370ec43b]]></appid>
5  <mch_id><![CDATA[10000100]]></mch_id>
6  <device_info><![CDATA[1000]]></device_info>
7  <nonce_str><![CDATA[GOp3TRyMXzbMlkun]]></nonce_str>
8  <sign><![CDATA[D6C76CB785F07992CDE05494BB7DF7FD]]></sign>
9  <result_code><![CDATA[SUCCESS]]></result_code>
10  <openid><![CDATA[oUpF8uN95-Ptaags6E_roPHg7AG0]]></openid>
11  <is_subscribe><![CDATA[Y]]></is_subscribe>
12  <trade_type><![CDATA[MICROPAY]]></trade_type>
13  <bank_type><![CDATA[CCB_DEBIT]]></bank_type>
14  <total_fee>1</total_fee>
15  <coupon_fee>0</coupon_fee>
16  <fee_type><![CDATA[CNY]]></fee_type>
17  <transaction_id><![CDATA[1008450740201411110005820873]]></transaction_id>
18  <out_trade_no><![CDATA[1415757673]]></out_trade_no>
19  <attach><![CDATA[订单额外描述]]></attach>
20  <time_end><![CDATA[20141111170043]]></time_end>
21</xml>

错误码列表

名称	描述	支付状态	原因	解决方案
SYSTEMERROR	接口返回错误	支付结果未知	系统超时	请立即调用被扫订单结果查询API，查询当前订单状态，并根据订单的状态决定下一步的操作。
PARAM_ERROR	参数错误	支付确认失败	请求参数未按指引进行填写	请根据接口返回的详细信息检查您的程序
SIGNERROR	签名错误	支付确认失败	参数签名结果不正确	请检查签名参数和方法是否都符合签名算法要求
USERPAYING	用户支付中，需要输入密码	支付结果未知	该笔交易因为业务规则要求，需要用户输入支付密码。	等待5秒，然后调用被扫订单结果查询API，查询当前订单的不同状态，决定下一步的操作。
AUTH_CODE_INVALID	授权码检验错误	支付确认失败	收银员扫描的不是微信支付的条码	请扫描微信支付被扫条码/二维码
TRADE_ERROR	交易错误	支付确认失败	业务错误导致交易失败、用户账号异常、风控、规则限制等	请确认账号是否存在异常
RULELIMIT	限额等规则导致失败	限额等规则导致失败	限额等规则导致失败	限额等规则导致失败
NOTENOUGH	余额不足	余额不足	余额不足	余额不足

文档是否有帮助

更多支持

开发文档(商户)开发文档(V2版)开发者社区微信开放平台微信公众平台腾讯客服