微信支付境外文档-委托代扣

返回上一层委托代扣 / 支付扣款API

支付扣款API

最新更新时间：2021.08.15 版本说明

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

注意：

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

• 扣款接口同步返回扣款结果，有以下三种情况：
    1. 如果扣款成功，则返回订单详情。
    2. 扣款失败，根据错误码和对应的建议处理方式处理。
    3. 扣款接口超时，超时后可通过调用查单接口获取订单状态，也可等待回调通知来更新商户侧订单状态，但回调次数有限制，不保证商户最终能收到通知。

接口说明

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

接口URL：https://apihk.mch.weixin.qq.com/v3/global/papay/transactions

请求方式：POST

接口规则：https://wechatpay-api.gitbook.io/wechatpay-api-v3/

path 指该参数为路径参数

query 指该参数为URL参数

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

请求参数

参数名

变量

类型[长度限制]

必填

描述

应用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订单金额信息

参数名	变量	类型[长度限制]	必填	描述
总金额	total	int	是	订单总金额，币种的最小单位，只能为整数，详见交易金额示例值：888
货币类型	currency	string[1,16]	是	符合ISO 4217标准的三位字母代码示例值：CNY

+场景信息

scene_info

object

否

body场景信息对象

参数名	变量	类型[长度限制]	必填	描述
商户端设备	device_id	string[1,32]	否	终端设备号(商户自定义，如门店编号) 示例值：013467007045764
商户端设备IP	device_ip	string[1,40]	否	商户侧设备IP，取公网出口IP，支持IPV6 示例值：128.0.0.1

请求示例


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

返回参数

参数名

变量

类型[长度限制]

必填

描述

商户号

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

否

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

参数名	变量	类型[长度限制]	必填	描述
用户标识（直连商户）	openid	string[1,128]	是	用户在商户appid下的openid 注意：仅适用于直连模式示例值：oUpF8uMuAJO_M2pxb1Q9zNjWeS6a
用户标识（服务商）	sp_openid	string[1,128]	是	用户在商户sp_appid对应下的唯一标识，需要传sp_appid才有返回注意：仅适用于机构模式示例值：oUpF8uMuAJO_M2pxb1Q9zNjWeS6o
用户标识（特约商户）	sub_openid	string[1,128]	否	用户在收单行sub_appid下用户唯一标识，需要传sub_appid才有返回注意：仅适用于机构模式示例值：oUpF8uMuAJO_M2pxb1Q9zNjWeS6o

+订单金额

amount

object

否

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

参数名

变量

类型[长度限制]

必填

描述

订单金额

total

int

是

订单总金额，币种的最小单位，只能为整数，详见交易金额
示例值：888

用户支付金额

payer_total

int

是

用户实际支付金额，币种的最小单位，只能为整数，详见交易金额
示例值：888

订单标价币种

currency

string[1,16]

是

符合ISO 4217标准的三位字母代码
示例值：CNY

用户支付币种

payer_currency

string[1,16]

否

符合ISO 4217标准的三位字母代码
示例值：HKD

+汇率信息

exchange_rate

object

否

汇率信息

参数名	变量	类型[长度限制]	必填	描述
汇率类型	type	string[1,32]	否	枚举值： SETTLEMENT_RATE：标价币种和结算币种的汇率类型 USERPAYMENT_RATE：标价币种和支付币种的汇率类型示例值：SETTLEMENT_RATE
汇率值	rate	int	否	rate值是兑换比例乘以10的8次方。如果标价币种和结算币种一致，兑换比例是1，则rate=100000000；如果标价币种和结算币种不一致，例如美元兑换人民币的比例为6.5，则rate=650000000 示例值：80000000

+优惠功能

promotion_detail

array

否

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

参数名

变量

类型[长度限制]

必填

描述

券ID

promotion_id

string[1,32]

是

券或者立减优惠id
示例值：109519

优惠名称

name

string[1,64]

否

优惠名称
示例值：单品惠-6

优惠范围

scope

string[1,32]

否

GLOBAL：全场代金券
SINGLE：单品优惠
示例值：SINGLE

优惠类型

type

string[1,16]

否

COUPON：代金券，需要走结算资金的充值型代金券,（境外商户券币种与支付币种一致）
DISCOUNT：优惠券，不走结算资金的免充值型优惠券，（境外商户券币种与标价币种一致
示例值：COUPON

优惠券面额

amount

int

是

用户享受优惠的金额
示例值：5

优惠币种

currency

string[1,16]

是

符合ISO 4217标准的三位字母代码
示例值：HKD

活动ID

activity_id

string[1,32]

否

在微信商户后台配置的批次ID
示例值：931386

微信出资

wxpay_contribute_amount

int

否

特指由微信支付商户平台创建的优惠，出资金额等于本项优惠总金额
示例值：5

商户出资

merchant_contribute_amount

int

否

特指商户自己创建的优惠，出资金额等于本项优惠总金额
示例值：5

其他出资

other_contribute_amount

int

否

其他出资方出资金额
示例值：5

+单品列表

goods_detail

array

否

单品信息

参数名	变量	类型[长度限制]	必填	描述
商品编码	goods_id	string[1,32]	是	由半角的大小写字母、数字、中划线、下划线中的一种或几种组成示例值：124512
商品备注	goods_remark	string[1,128]	否	goods_remark为备注字段，按照配置原样返回，字段内容在微信后台配置券时进行设置示例值：1001
商品优惠金额	discount_amount	int	是	单品的总优惠金额示例值：100
商品数量	quantity	int	是	用户购买的数量示例值：1
商品价格	price	int	是	单位为：分。如果商户有优惠，需传输商户优惠后的单价示例值：528800

返回示例

正常示例


{
	"amount": {
		"currency": "HKD",
		"payer_currency": "CNY",
		"payer_total": 8,
		"total": 10
	},
	"appid": "wx7bc98d929da735fe",
	"attach": "testruoyu",
	"bank_type": "CFT",
	"mchid": "132012662",
	"merchant_category_code": "0",
	"out_trade_no": "autotest_20210608201410_9263565",
	"payer": {
		"openid": "of8YZ6A_ySrPYzjX7joXo_h2CI44"
	},
	"promotion_detail": [{
		"promotion_id": "109519",
		"name": "单品惠-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
		}
	}]
	"success_time": "2021-12-09T10:56:27+08:00",
	"trade_state": "SUCCESS",
	"trade_state_desc": "支付成功",
	"trade_type": "AUTH",
	"transaction_id": "4200001136202112092809736426"
}


http://2323weixin.qq.com

错误码

状态码	错误码	描述	解决方案
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	系统错误	建议发起查单，获取此次支付结果，如需换单重试，请先调用撤销订单接口再换单支付，避免重复支付

WeChat Pay

Feedback

Feedback

Submitted successfully

Feedback

Network exception, please try again later

委托代扣API

支付扣款API

注意：

接口说明

请求参数

请求示例

返回参数

返回示例

错误码

版本说明