@18612183942 2018-11-20T03:44:32.000000Z 字数 8119 阅读 101

助销客支付对接文档

文档版本	修订记录	修订人	修订时间
v1.0	初步设计	杨金奎	2018-11-19

1 交易支付接口

本接口用于助销客向银行发起交易支付，有3个场景。
wap支付：调用微信、支付宝、银联支付，跳转到银行通一支付页面，其中微信、支付宝可以发起向微信、支付宝APP进行支付；
pc支付：调用微信、支付宝、银联支付，跳转到银行通一支付页面，其中微信、支付宝可以支持使用微信、支付宝APP扫码支付；
闸机闪付：支持银行卡刷卡免密码支付，微信、支付宝二维码支付。

1.1 公共请求参数

参数	类型	是否必填	最大长度	描述	示例值
app_id	String	是	32	应用ID	2014072300007148
method	String	是	128	接口名称	zxk.trade.pay
format	String	否	40	仅支持JSON	JSON
charset	String	是	10	请求使用的编码格式，如utf-8,gbk,gb2312等	utf-8
sign_type	String	是	10	商户生成签名字符串所使用的签名算法类型，目前支持RSA2和RSA，推荐使用RSA2	RSA2
sign	String	是	344	商户请求参数的签名串，详见签名	详见示例
timestamp	String	是	19	发送请求的时间，格式"yyyy-MM-dd HH:mm:ss"	2014-07-24 03:07:50
version	String	是	3	调用的接口版本，固定为：1.0	1.0
notify_url	String	否	256	银行服务器主动通知商户服务器里指定的页面http/https路径。	http://api.test.alipay.net/atinterface/receive_notify.htm
biz_content	String	是		请求参数的集合，最大长度不限

1.2 请求参数

参数	类型	是否必填	最大长度	描述	示例值
out_trade_no	String	必选	64	商户订单号,64个字符以内、可包含字母、数字、下划线；需保证在商户端不重复	20150320010101001
auth_code	String	必选	32	银行授权码，25~30开头的长度为16~24位的数字，实际字符串长度以开发者获取的付款码长度为准	28763443825664394
product_code	String	可选	32	销售产品码	FACE_TO_FACE_PAYMENT
subject	String	必选	256	订单标题	Iphone6 16G
buyer_id	String	可选	28	买家ID	2088202954065786
seller_id	String	可选	28	商户ID	2088102146225135
total_amount	Price	必选	11	订单总金额，单位为元，精确到小数点后两位，取值范围[0.01,100000000]	88.88
body	String	可选	128	订单描述	Iphone6 16G
goods_detail	GoodsDetail[]	可选		订单包含的商品列表信息，json格式，其它说明详见商品明细说明
operator_id	String}可选	28	商户操作员编号	yx_001
store_id	String	可选	32	商户门店编号	NJ_001
terminal_id	String	可选	32	商户机具终端编号	NJ_T_001

其中GoodsDetail信息如下：

参数	类型	是否必填	最大长度	描述	示例值
goods_id	String	必填	32	商品的编号	apple-01
goods_name	String	必填	256	商品名称	ipad
quantity	Number	必填	10	商品数量	1
price	Price	必填	9	商品单价，单位为元	2000
goods_category	String	可选	24	商品类目	34543238
body	String	可选	1000	商品描述信息	特价手机
show_url	String	可选	400	商品的展示地址	http://www.alipay.com/xxx.jpg

1.3 公共响应参数

参数	类型	是否必填	最大长度	描述	示例值
code	String	是	-	网关返回码	40004
msg	String	是	-	网关返回码描述	Business Failed
sub_code	String	否	-	业务返回码，参见具体的API接口文档	ACQ.TRADE_HAS_SUCCESS
sub_msg	String	否	-	业务返回码描述，参见具体的API接口文档	交易已被支付
sign	String	是	-	签名	-

1.4 响应参数

参数	类型	是否必填	最大长度	描述	示例值
trade_no	String	必填	64	银行交易号	2013112011001004330000121536
out_trade_no	String	必填	64	商户订单号	6823789339978248
buyer_logon_id	String	必填	100	买家账号	159****5620
total_amount	Price	必填	11	交易金额	120.88

2 交易退款接口

本接口用于助销客向银行发起交易退款，支持部分退款。各支付场景通一调用此接口进行退款。

2.1 公共请求参数

参数	类型	是否必填	最大长度	描述	示例值
app_id	String	是	32	应用ID	2014072300007148
method	String	是	128	接口名称	zxk.trade.refund
format	String	否	40	仅支持JSON	JSON
charset	String	是	10	请求使用的编码格式，如utf-8,gbk,gb2312等	utf-8
sign_type	String	是	10	商户生成签名字符串所使用的签名算法类型，目前支持RSA2和RSA，推荐使用RSA2	RSA2
sign	String	是	344	商户请求参数的签名串，详见签名	详见示例
timestamp	String	是	19	发送请求的时间，格式"yyyy-MM-dd HH:mm:ss"	2014-07-24 03:07:50
version	String	是	3	调用的接口版本，固定为：1.0	1.0
notify_url	String	否	256	银行服务器主动通知商户服务器里指定的页面http/https路径。	http://api.test.alipay.net/atinterface/receive_notify.htm
biz_content	String	是		请求参数的集合，最大长度不限

2.2 请求参数

参数	类型	是否必填	最大长度	描述	示例值
ut_trade_no	String	特殊可选	64	订单支付时传入的商户订单号,不能和trade_no同时为空。	20150320010101001
trade_no	String	特殊可选	64	银行交易号，和商户订单号不能同时为空	2014112611001004680073956707
refund_amount	Price	必选	9	需要退款的金额，该金额不能大于订单金额,单位为元，支持两位小数	200.12
refund_reason	String	可选	256	退款的原因说明	正常退款
out_request_no	String	可选	64	标识一次退款请求，同一笔交易多次退款需要保证唯一，如需部分退款，则此参数必传。	HZ01RF001

2.3 公共响应参数

参数	类型	是否必填	最大长度	描述	示例值
code	String	是	-	网关返回码	40004
msg	String	是	-	网关返回码描述	Business Failed
sub_code	String	否	-	业务返回码，参见具体的API接口文档	ACQ.TRADE_HAS_SUCCESS
sub_msg	String	否	-	业务返回码描述，参见具体的API接口文档	交易已被支付
sign	String	是	-	签名	-

2.4 响应参数

参数	类型	是否必填	最大长度	描述	示例值
trade_no	String	必填	64	2013112011001004330000121536	银行交易号
out_trade_no	String	必填	64	商户订单号	6823789339978248
buyer_logon_id	String	必填	100	用户的登录id	159****5620
fund_change	String	必填	1	本次退款是否发生了资金变化	Y
refund_fee	Price	必填	11	退款总金额	88.88
gmt_refund_pay	Date	必填	32	退款支付时间	2014-11-27 15:45:57
buyer_user_id	String	必填	28	买家用户id	2088101117955611

3 交易查询接口

本接口用于助销客向银行查询交易状态，调用支付、退款接口后，助销客都会调用此接口向银行查询交易状态。

3.1 公共请求参数

参数	类型	是否必填	最大长度	描述	示例值
app_id	String	是	32	应用ID	2014072300007148
method	String	是	128	接口名称	zxk.trade.query
format	String	否	40	仅支持JSON	JSON
charset	String	是	10	请求使用的编码格式，如utf-8,gbk,gb2312等	utf-8
sign_type	String	是	10	商户生成签名字符串所使用的签名算法类型，目前支持RSA2和RSA，推荐使用RSA2	RSA2
sign	String	是	344	商户请求参数的签名串，详见签名	详见示例
timestamp	String	是	19	发送请求的时间，格式"yyyy-MM-dd HH:mm:ss"	2014-07-24 03:07:50
version	String	是	3	调用的接口版本，固定为：1.0	1.0
notify_url	String	否	256	银行服务器主动通知商户服务器里指定的页面http/https路径。	http://api.test.alipay.net/atinterface/receive_notify.htm
biz_content	String	是		请求参数的集合，最大长度不限

3.2 请求参数

参数	类型	是否必填	最大长度	描述	示例值
ut_trade_no	String	特殊可选	64	订单支付时传入的商户订单号,不能和trade_no同时为空。	20150320010101001
trade_no	String	特殊可选	64	银行交易号，和商户订单号不能同时为空	2014112611001004680073956707

3.3 公共响应参数

参数	类型	是否必填	最大长度	描述	示例值
code	String	是	-	网关返回码	40004
msg	String	是	-	网关返回码描述	Business Failed
sub_code	String	否	-	业务返回码，参见具体的API接口文档	ACQ.TRADE_HAS_SUCCESS
sub_msg	String	否	-	业务返回码描述，参见具体的API接口文档	交易已被支付
sign	String	是	-	签名	-

3.4 响应参数

参数	类型	是否必填	最大长度	描述	示例值
trade_no	String	必填	64	2013112011001004330000121536	银行交易号
out_trade_no	String	必填	64	商户订单号	6823789339978248
buyer_logon_id	String	必填	100	用户的登录id	159****5620
trade_status	String	必填	32	交易状态：WAIT_BUYER_PAY（交易创建，等待买家付款）、TRADE_CLOSED（未付款交易超时关闭，或支付完成后全额退款）、TRADE_SUCCESS（交易支付成功）、TRADE_FINISHED（交易结束，不可退款）	TRADE_CLOSED
total_amount	Price	必填	11	交易的订单金额，单位为元，两位小数。该参数的值为支付时传入的total_amount	88.88
buyer_user_id	String	必填	28	买家用户id	2088101117955611

4 转账提现接口

本接口用于助销客向银行发起转账提现，用于助销客给供应商（景区/酒店等商户）进行结算。

4.1 公共请求参数

参数	类型	是否必填	最大长度	描述	示例值
app_id	String	是	32	应用ID	2014072300007148
method	String	是	128	接口名称	zxk.fund.trans.toaccount.transfer
format	String	否	40	仅支持JSON	JSON
charset	String	是	10	请求使用的编码格式，如utf-8,gbk,gb2312等	utf-8
sign_type	String	是	10	商户生成签名字符串所使用的签名算法类型，目前支持RSA2和RSA，推荐使用RSA2	RSA2
sign	String	是	344	商户请求参数的签名串，详见签名	详见示例
timestamp	String	是	19	发送请求的时间，格式"yyyy-MM-dd HH:mm:ss"	2014-07-24 03:07:50
version	String	是	3	调用的接口版本，固定为：1.0	1.0
notify_url	String	否	256	银行服务器主动通知商户服务器里指定的页面http/https路径。	http://api.test.alipay.net/atinterface/receive_notify.htm
biz_content	String	是		请求参数的集合，最大长度不限

4.2 请求参数

参数	类型	是否必填	最大长度	描述	示例值
out_biz_no	String	必选	64	商户转账唯一订单号。发起转账来源方定义的转账单据ID，用于将转账回执通知给来源方。不同来源方给出的ID可以重复，同一个来源方必须保证其ID的唯一性。只支持半角英文、数字，及“-”、“_”。	3142321423432
payee_type	String	必选	20	收款方账户类型。可取值： 1、ALIPAY_USERID：唯一用户号。以2088开头的16位纯数字组成。2、ALIPAY_LOGONID：登录号，支持邮箱和手机号格式。	ALIPAY_LOGONID
payee_account	String	必选	100	收款方账户。与payee_type配合使用。付款方和收款方不能是同一个账户。	abc@sina.com
amount	String	必选	16	转账金额，单位：元。	只支持2位小数，小数点前最大支持13位，金额必须大于等于0.1元。最大转账金额以实际签约的限额为准。
payer_show_name	String	可选	100	付款方姓名（最长支持100个英文/50个汉字）。显示在收款方的账单详情页。如果该字段不传，则默认显示付款方的认证姓名或单位名称。	上海交通卡退款
payee_real_name	String	可选	100	收款方真实姓名（最长支持100个英文/50个汉字）。如果本参数不为空，则会校验该账户登记的实名是否与收款方真实姓名一致。	张三 remark

4.3 公共响应参数

参数	类型	是否必填	最大长度	描述	示例值
code	String	是	-	网关返回码	40004
msg	String	是	-	网关返回码描述	Business Failed
sub_code	String	否	-	业务返回码，参见具体的API接口文档	ACQ.TRADE_HAS_SUCCESS
sub_msg	String	否	-	业务返回码描述，参见具体的API接口文档	交易已被支付
sign	String	是	-	签名	-

4.4 响应参数

参数	类型	是否必填	最大长度	描述	示例值
out_biz_no	String	必填	64	商户转账唯一订单号：发起转账来源方定义的转账单据号。请求时对应的参数，原样返回。	3142321423432
order_id	String	选填	64	转账单据号，成功一定返回，失败可能不返回也可能返回。	20160627110070001502260006780837
pay_date	String	选填	20	支付时间：格式为yyyy-MM-dd HH:mm:ss，仅转账成功返回。	2013-01-01 08:08:08

5 转账提现查询接口

本接口用于助销客向银行查询转账提现的状态，调用上面转账接口后，会调用本接口查询状态。

5.1 公共请求参数

参数	类型	是否必填	最大长度	描述	示例值
app_id	String	是	32	应用ID	2014072300007148
method	String	是	128	接口名称	zxk.fund.trans.order.query
format	String	否	40	仅支持JSON	JSON
charset	String	是	10	请求使用的编码格式，如utf-8,gbk,gb2312等	utf-8
sign_type	String	是	10	商户生成签名字符串所使用的签名算法类型，目前支持RSA2和RSA，推荐使用RSA2	RSA2
sign	String	是	344	商户请求参数的签名串，详见签名	详见示例
timestamp	String	是	19	发送请求的时间，格式"yyyy-MM-dd HH:mm:ss"	2014-07-24 03:07:50
version	String	是	3	调用的接口版本，固定为：1.0	1.0
notify_url	String	否	256	银行服务器主动通知商户服务器里指定的页面http/https路径。	http://api.test.alipay.net/atinterface/receive_notify.htm
biz_content	String	是		请求参数的集合，最大长度不限

5.2 请求参数

参数	类型	是否必填	最大长度	描述	示例值
out_biz_no	String	可选	64	商户转账唯一订单号：发起转账来源方定义的转账单据ID。和银行转账单据号不能同时为空。当和银行转账单据号同时提供时，将用银行转账单据号进行查询，忽略本参数。	3142321423432
order_id	String	可选	64	银行转账单据号：和商户转账唯一订单号不能同时为空。当和商户转账唯一订单号同时提供时，将用本参数进行查询，忽略商户转账唯一订单号。	20160627110070001502260006780837

5.3 公共响应参数

参数	类型	是否必填	最大长度	描述	示例值
code	String	是	-	网关返回码	40004
msg	String	是	-	网关返回码描述	Business Failed
sub_code	String	否	-	业务返回码，参见具体的API接口文档	ACQ.TRADE_HAS_SUCCESS
sub_msg	String	否	-	业务返回码描述，参见具体的API接口文档	交易已被支付
sign	String	是	-	签名	-

5.4 响应参数

参数	类型	是否必填	最大长度	描述	示例值
order_id	String	选填	64	银行转账单据号，查询失败不返回。	2912381923
status	String	选填	10	转账单据状态。SUCCESS：成功（配合"单笔转账到银行账户接口"产品使用时, 同一笔单据多次查询有可能从成功变成退票状态）；FAIL：失败（具体失败原因请参见error_code以及fail_reason返回值）； INIT：等待处理； DEALING：处理中； REFUND：退票（仅配合"单笔转账到银行账户接口"产品使用时会涉及,具体退票原因请参见fail_reason返回值）； UNKNOWN：状态未知。	SUCCESS
pay_date	String	选填	20	支付时间，格式为yyyy-MM-dd HH:mm:ss，转账失败不返回。	2013-01-01 08:08:08
arrival_time_end	String	选填	20	预计到账时间，转账到银行卡专用，格式为yyyy-MM-dd HH:mm:ss，转账受理失败不返回。此参数为预计时间，可能与实际到账时间有较大误差，不能作为实际到账时间使用，仅供参考用途。	2013-01-01 08:08:08
order_fee	String	选填	20	预计收费金额（元），转账到银行卡专用，数字格式，精确到小数点后2位，转账失败或转账受理失败不返回。	0.02
fail_reason	String	选填	100	查询到的订单状态为FAIL失败或REFUND退票时，返回具体的原因。	单笔额度超限
out_biz_no	String	选填	64	发起转账来源方定义的转账单据号。该参数的赋值均以查询结果中的 out_biz_no 为准。如果查询失败，不返回该参数。	3142321423432
error_code	String	选填	100	查询失败时，本参数为错误代码。查询成功不返回。对于退票订单，不返回该参数。	ORDER_NOT_EXIST