支付宝服务窗支付 - Powered by MinDoc

文档描述:

支付宝服务窗支付接口文档

文档版本：

版本号	修定人	制定日期	修订日期
1.0	EricYang	2020-08-04	2020-08-04

接口说明:

初始化请求接口

业务功能

初始化JSAPI请求，通过生成pay_info来进行交互验证。

交互模式

请求：后台请求交互模式
返回结果+通知：后台请求交互模式+后台通知交互模式

请求 url：

https://pay.xrtpay.cn/xrtpay/gateway

请求参数列表

POST XML 内容体进行请求

字段名	变量名	必填	类型	说明
业务参数	————	————	————	————
接口类型	service	是	String(32)	接口类型： pay.alipay.jspay
版本号	version	否	String(8)	版本号，version 默认值是 2.0
字符集	charset	否	String(8)	可选值 UTF-8 ，默认为 UTF-8
签名方式	sign_type	否	String(8)	签名类型，取值： MD5 默认： MD5
商户号	mch_id	是	String(32)	商户号，由技术部分配
商户订单号	out_trade_no	是	String(32)	商户系统内部的订单号 ,32个字符内、可包含字母,确保在商户系统唯一
设备号	device_info	否	String(32)	终端设备号
商品描述	body	是	String(127)	商品描述
用户 id	aliuserid	是	String(128)	买家支付宝用户ID，和buyer_logon_id不能同时为空buyer_id获取方法：https://doc.open.alipay.com/doc2/detail.htm?spm=a219a.7629140.0.0.8ujLD6&treeId=115&articleId=104114&docType=1通过网页授权获取用户信息，同步响应结果中的user_id对应文档中的buyer_id。
附加信息	attach	否	String(128)	商户附加信息，可做扩展参数， 255 字符内
总金额	total_fee	是	Int	总金额，以分为单位，不允许包含任何字、符号
终端 IP	mch_create_ip	是	String(16)	订单生成的机器 IP
通知地址	notify_url	是	String(255)	接收…通知的 URL，需给绝对路径，255字符内格式如:http://wap.tenpay.com/tenpay.asp，确保易办事能通过互联网访问该地址
订单生成时间	time_start	否	String(14)	订单生成时间，格式为 yyyyMMddHHmmss，如2009 年12月25日 9 点 10 分 10 秒表示为20091225091010。时区为 GMT+8 beijing。该时间取自商户服务器
订单超时时间	time_expire	否	String(14)	订单失效时间，格式为 yyyyMMddHHmmss，如2009 年12月27日9点 10 分 10 秒表示为20091227091010。时区为 GMT+8 beijing。该时间取自商户服务器
商品标记	goods_tag	否	String(32)	商品标记，微信平台配置的商品标记，用于优惠券或者满减使用
随机字符串	nonce_str	是	String(32)	随机字符串，不长于 32 位
是否限制信用卡	limit_credit_pay	否	String(32)	限定用户使用微信支付时能否使用信用卡，值为 1，禁用信用卡；值为 0 或者不传此参数则不禁用
签名	sign	是	String(32)	MD5 签名结果，详见“数字签名 MD5 签名规则”

返回结果

数据按 XML 的格式实时返回

字段名	变量名	必填	类型	说明
版本号	version	是	String(8)	版本号， version 默认值是 2.0。
字符集	charset	是	String(8)	可选值 UTF-8 ，默认为 UTF-8。
签名方式	sign_type	是	String(8)	签名类型，取值： MD5 默认： MD5
返回状态码	status	是	String(16)	0 表示成功非 0 表示失败此字段是通信标识，非交易标识，交易是否成功需要查看 result_code 来判断
返回信息	message	否	String(128)	返回信息，如非空，为错误原因签名失败参数格式校验错误

以下字段在 status 为 0 的时候有返回

业务结果	result_code	是	String(16)	0 表示成功非 0 表示失败
商户号	mch_id	是	String(32)	商户号，由技术部分配
设备号	device_info	否	String(32)	终端设备号
随机字符串	nonce_str	是	String(32)	随机字符串，不长于 32 位
错误代码	err_code	否	String(32)	参考错误码
错误代码描述	err_msg	否	String (128)	结果信息描述
签名	sign	是	String(32)	MD5 签名结果，详见“数字签名 MD5 签名规则”

以下字段在status和result_code 都为 0 的时候有返回

动态口令	token_id	是	String(64)	…成的预支付 ID，用于后续接口调用中使
原生支付信息	pay_info	是	String	JSON字符串，自行唤起支付宝钱包支付

JS 支付通知接口

通知结果参数列表

通知 URL 是 6.1 节中提交的参数 notify_url，支付完成后， …会把相关支付和用户信息发送到该 URL，商户需要接收处理信息。
对后台通知交互时，如果收到商户的应答不是成功或超时，微信认为通知失败，通过一定的策略（通知频率为 15/15/30/180/1800/1800/1800/1800/3600，单位：秒）定期重新发起通知，尽可能提高通知的成功率，但不保证通知最终能成功。
由于存在重新发送后台通知的情况，因此同样的通知可能会多次发送给商户系统。商户系统必须能够正确处理重复的通知。
推荐的做法是，当收到通知进行处理时，首先检查对应业务数据的状态，判断该通知是否已经处理过，如果没有处理过再进行处理，如果处理过直接返回结果成功。在对业务数据进行状态检查和处理之前，要采用数据锁进行并发控制，以避免函数重入造成的数据混乱。
特别注意：商户后台接收到通知参数后，要对接收到通知参数里的订单号 out_trade_no 和订单金额total_fee 和自身业务系统的订单和金额做校验，校验一致后才更新数据库订单状态后台通知通过请求中的 notify_url 进行， post

字段名	变量名	必填	类型	说明
接口类型	service	是	String(32)	接口类型： pay.weixin.jspay
版本号	version	是	String(8)	版本号，version 默认值是 2.0。
字符集	charset	是	String(8)	可选值 UTF-8 ，默认为 UTF-8。
签名方式	sign_type	是	String(8)	签名类型，取值： MD5 默认： MD5
返回状态码	status	是	String(16)	0 表示成功非 0 表示失败此字段是通信标识，非交易标识，交易是否成功需要查看 result_code 来判断
返回信息	message	否	String(128)	返回信息，如非空，为错误原因签名失败参数格式校验错误

以下字段在 status 为 0 的时候有返回

业务结果	result_code	是	String(16)	0 表示成功非 0 表示失败
商户号	mch_id	是	String(32)	商户号，由技术部分配
设备号	device_info	否	String(32)	终端设备号
随机字符串	nonce_str	是	String(32)	随机字符串，不长于 32 位
错误代码	err_code	否	String(32)	参考错误码
错误代码描述	err_msg	否	String(128)	结果信息描述
签名	sign	是	String(32)	MD5 签名结果，详见“ 数字签名 MD5 签名规则”

以下字段在 status 和 result_code 都为 0 的时候有返回

用户标识	openid	是	String(128)	用户在商户appid下的唯一标识
交易类型	trade_type	是	String(16)	pay.weixin.jspay
是否关注公众账号	is_subscribe	是	Int	用户是否关注公众账号， Y-关注， N-未关注，仅在公众账号类型支付有效
支付结果	pay_result	是	Int	支付结果:0—成功;其它—失败
支付结果信息	pay_info	否	String(64)	支付结果信息,支付成功时为空
…订单号	transaction_id	是	String(32)	…交易号
第三方订单号	out_transaction_id	是	String(32)	第三方订单号
子商户是否关注	sub_is_subscribe	否	Int	用户是否关注子公众账号， Y-关注， N-未关注，仅在公众账号类型支付有效
子商户 appid	sub_appid	否	String	子商户 appid
用户 openid	sub_openid	否	String(128)	用户在商户 sub_appid 下的唯一标识
商户订单号	out_trade_no	是	String(32)	商户系统内部的定单号， 32 个字符内、可包含字母
总金额	total_fee	是	Int	总金额，以分为单位，不允许包含任何字、符号
现金券金额	coupon_fee	否	Int	现金券支付金额<=订单总金额，订单总金额-现金券金额为现金支付金额
货币种类	fee_type	否	String(8)	货币类型，符合 ISO 4217 标准的三位字母代码，默认人民币： CNY
附加信息	attach	否	String(128)	商家数据包，原样返回
付款银行	bank_type	是	String(16)	银行类型
银行订单号	bank_billno	否	String(32)	银行订单号，若为微信支付则为空
支付完成时间	time_end	是	String(14)	支付完成时间，格式为 yyyyMMddHHmmss，如2009 年 12 月 27 日 9 点 10 分 10 秒表示为20091227091010。时区为 GMT+8 beijing。该时间取自…服务器

后台通知结果反馈

…后台通过 notify_url 通知商户，商户做业务处理后，需要以字符串的形式反馈处理结果，内容如下：

返回结果	结果说明
success	处理成功， …系统收到此结果后不再进行后续通知
fail 或其它字符	处理不成功， …收到此结果或者没有收到任何结果，系统通过补单机制（详见补单机制）再次通知

数据格式:

提交数据

采用 HTTP 标准的 POST 协议，为了保证接收方接收数据正确,传输数据必须签名。

<xml>
<service>pay.weixin.jspay</service>
<attach><![CDATA[att]]></attach>
<body><![CDATA[支付测试]]></body>
<device_info>1000</device_info>
<mch_id>10000100</mch_id>
<nonce_str>adf880d5c8986bd0deb6423c92c9d948</nonce_str>
<out_trade_no>1406046836</out_trade_no>
<spbill_create_ip>127.0.0.1</spbill_create_ip>
<total_fee>1</total_fee>
<sign><![CDATA[F53145E553092CE52E4CAA4D2B49A91C]]></sign>
</xml>

XML 数据格式

采用标准 XML 协议，所有参数只存在一级节点中，不采用多级节点嵌套。
协议级错误返回：

<xml>
<status>500</status>
<message><![CDATA[SYSERR]]></message>
</xml>

正确返回数据：

<xml>
<status>0</status>
<message><![CDATA[OK]]></message>
<appid><![CDATA[wx2421b1c4370ec43b]]></appid>
<mch_id><![CDATA[10000100]]></mch_id>
<device_info><![CDATA[1000]]></device_info>
<nonce_str><![CDATA[FvYSnPuFFPkAr77M]]></nonce_str>
<sign><![CDATA[63238039D6E43634297CF2A6EB5F3B72]]></sign>
<result_code>0</result_code>
<openid><![CDATA[oUpF8uN95-Ptaags6E_roPHg7AG0]]></openid>
<is_subscribe><![CDATA[Y]]></is_subscribe>
<trade_type><![CDATA[pay.weixin.jspay]]></trade_type>
<bank_type><![CDATA[CCB_CREDIT]]></bank_type>
<total_fee>1</total_fee>
<coupon_fee>0</coupon_fee>
<fee_type><![CDATA[CNY]]></fee_type>
<transaction_id><![CDATA[1008450740201407220000058756]]></transaction_id>
<out_trade_no><![CDATA[1406033828]]></out_trade_no>
<attach><![CDATA[att]]></attach>
<time_end><![CDATA[20140722160655]]></time_end>
</xml>

业务级错误返回：

<xml>
<status>0</status>
<message><![CDATA[OK]]></message>
<appid><![CDATA[wx2421b1c4370ec43b]]></appid>
<mch_id><![CDATA[10000100]]></mch_id>
<device_info><![CDATA[1000]]></device_info>
<nonce_str><![CDATA[sthBJ9QyUG6vkrjJ]]></nonce_str>
<sign><![CDATA[6277A96D7875D4FF23AA7B6A4C3046AB]]></sign>
<result_code>1</result_code>
<err_code><![CDATA[AUTHCODE_EXPIRE]]></err_code>
<err_code_des><![CDATA[二维码已过期， 请刷新再试]]></err_code_des>
</xml>

一般有返回有 status 参数， 0 表示调用成功；非 0 表示调用失败。

数字签名:

为了保证数据传输过程中的数据真实性和完整性，我们需要对数据进行数字签名，在接收签名数据之后进行签名校验。
数字签名有两个步骤，先按一定规则拼接要签名的原始串，再选择具体的算法和密钥计算出签名结果。
一般失败的结果不签名。

签名原始串

无论是请求还是应答，签名原始串按以下方式组装成字符串：
1、除 sign 字段外，所有参数按照字段名的 ascii 码从小到大排序后使用 QueryString 的格式（即key1=value1&key2=value2…）拼接而成，空值不传递，不参与签名组串。
2、签名原始串中，字段名和字段值都采用原始值，不进行 URL Encode。
3、 …返回的应答或通知消息可能会由于升级增加参数，请验证应答签名时注意允许这种情况。
举例：
调用某个接口，接口有如下字段：

<xml><body><![CDATA[测试支付]]></body>
<mch_create_ip><![CDATA[127.0.0.1]]></mch_create_ip>
<mch_id><![CDATA[001075552110006]]></mch_id>
<nonce_str><![CDATA[1409196838]]></nonce_str>
<notify_url><![CDATA[http://227.0.0.1:9001/javak/sds?123&23=3]]></notify_url>
<out_trade_no><![CDATA[141903606228]]></out_trade_no>
<service><![CDATA[pay.weixin.jspay]]></service>
<sign><![CDATA[83684D9546F261997EFF2ECFAC372583]]></sign>
<total_fee><![CDATA[1]]></total_fee>
</xml>

正确的签名字段排序为：
body=测试支付
&mch_create_ip=127.0.0.1&mch_id=001075552110006&nonce_str=1409196838&notify_url=http://227.0.0.1:9001/javak/sds?123&23=3&out_trade_no=141903606228&service=pay.weixin.jspay&total_fee=1
4.2.签名算法
目前暂只支持 MD5 签名
MD5 签名
MD5 是一种摘要生成算法，通过在签名原始串后加上商户通信密钥的内容，进行 MD5 运算，形成的摘要字符串即为签名结果。为了方便比较，签名结果统一转换为大写字符。
注意：签名时将字符串转化成字节流时指定的编码字符集应与参数 charset 一致。
MD5 签名计算公式：
sign = Md5(原字符串&key=商户密钥). toUpperCase
如：
假设以下为 XML 传入参数：

<xml><body><![CDATA[测试支付]]></body>
<mch_create_ip><![CDATA[127.0.0.1]]></mch_create_ip>
<mch_id><![CDATA[001075552110006]]></mch_id>
<nonce_str><![CDATA[1409196838]]></nonce_str>
<notify_url><![CDATA[http://227.0.0.1:9001/javak/sds?123&23=3]]></notify_url>
<out_trade_no><![CDATA[141903606228]]></out_trade_no>
<service><![CDATA[pay.weixin.jspay]]></service>
<sign><![CDATA[2CE21B763658760DFD0758360C8054C7]]></sign>
<total_fee><![CDATA[1]]></total_fee>
</xml>

假设商户密钥为： e1cf0ddcf6b47b59c351565d8ad717af
i：经过 a 过程 URL 键值对字典序排序后的字符串 string1 为：
body=测试支付
&mch_create_ip=127.0.0.1&mch_id=001075552110006&nonce_str=1409196838&notify_url=http://227.0.0.1:9001/javak/sds?123&23=3&out_trade_no=141903606228&service=pay.weixin.scancode&total_fee=1
ii：经过 b 过程后得到 sign 为：
sign=md5(string1&key=e1cf0ddcf6b47b59c351565d8ad717af).toUpperCase
=md5(body=测试支付
&mch_create_ip=127.0.0.1&mch_id=001075552110006&nonce_str=1409196838&notify_url=http://227.0.0.1:9001/javak/sds?123&23=3&out_trade_no=141903606228&service=pay.weixin.jspay&total_fee=1&key=e1cf0ddcf6b47b59c351565d8ad717af).toUpperCase()
=”2CE21B763658760DFD0758360C8054C7”

补单机制:

注意：对后台通知交互模式，如果…收到商户的应答不是“success” 或超时， …认为通知失败， …会通过一定的策略（通知频率为 15/15/30/180/1800/1800/1800/1800/3600，单位：秒）定期重新发起通知，尽可能提高通知的成功率，但…不保证通知最终能成功。
由于存在重新发送后台通知的情况，因此同样的通知可能会多次发送给商户系统。商户系统必须能够正确处理重复的通知。
推荐的做法是，当收到通知进行处理时，首先检查对应业务数据的状态，判断该通知是否已经处理过，如果没有处理过再进行处理，如果处理过直接返回“success” 。在对业务数据进行状态检查和处理之前，要采用数据锁进行并发控制，以避免函数重入造成的数据混乱。

关闭订单接口:

业务功能

商户订单支付失败需要生成新单号重新发起支付，要对原订单号调用关单，避免重复支付；系统下单后，用户支付超时，系统退出不再受理，避免用户继续，请调用关单接口。

交互模式

请求：后台请求交互模式
返回结果：后台请求交互模式

请求 url:

http://pay.xrtpay.com/xrtpay/gateway

请求参数列

POST XML 内容体进行请求

字段名	变量名	必填	类型	说明
业务参数	————	————	————	————
接口类型	service	是	String(32)	接口类型： unified.micropay.reverse
版本号	version	否	String(8)	版本号， version 默认值是 2.0
字符集	charset	否	String(8)	可选值 UTF-8 ，默认为 UTF-8
签名方式	sign_type	否	String(8)	签名类型，取值： MD5 默认： MD5
商户号	mch_id	是	String(32)	商户号，由技术部分配
商户订单号	out_trade_no	是	String(32)	商户系统内部的订单号 ,32 个字符内、可包含字母,确保在商户系统唯一
随机字符串	nonce_str	是	String(32)	随机字符串，不长于 32 位
签名	sign	是	String(32)	MD5 签名结果，详见“ 数字签名 MD5 签名规则”

返回结果

数据按 XML 的格式实时返回

字段名	变量名	必填	类型	说明
版本号	version	是	String(8)	版本号，version 默认值是 2.0。
字符集	charset	是	String(8)	可选值 UTF-8 ，默认为UTF-8。
签名方式	sign_type	是	String(8)	签名类型，取值： MD5 默认： MD5
返回状态码	status	是	String(16)	0 表示成功非 0 表示失败此字段是通信标识，非交易标识，交易是否成功需要查看 result_code 来判断
返回信息	message	否	String(128)	返回信息，如非空，为错误原因签名失败参数格式校验错误

以下字段在 status 为 0 的时候有返回

业务结果	result_code	是	String(16)	0 表示成功非 0 表示失败0 表示关单成功，此笔订单不能再发起支付；非 0 或其它表示关单接口异常，需再次发起关单操作；
商户号	mch_id	是	String(32)	商户号，由技术部分配
随机字符串	nonce_str	是	String(32)	随机字符串，不长于 32 位
错误代码	err_code	否	String(32)	具体错误码请看文档最后错误码列表
错误代码描述	err_msg	否	String (128)	结果信息描述
签名	sign	是	String(32)	MD5 签名结果，详见“数字签名 MD5 签名规则”

注意事项:

1、所有涉及到金额的单位都是分，最小的单位是 1 分，不能有小数出现
2、 notify_url 是…服务器从后台直接发起请求到商户服务器，商户处理时不能检查用户的 cookie 或 session；商户更新 DB 等发货流程需要在 notify_url 完成后，以确保掉单时， …补单能成功补上
3、 notify_url 有可能重复通知，商户需要做去重处理，避免多次发货
4、 notify_url 收到的通知，商户处理成功或检查订单已经处理，需要返回处理成功的标志“ success” ，以告知不再通知
5、文档中请求接口时传的参数，必填为是的参数是必须要传的（如有缺少会报错），必填为否的参数可以传也可以不传
6、返回参数中必填为是的参数是一定会返回的，必填为否的参数则不一定返回，因升级或配置等情况实际返回参数可能不会跟文档完全一致，必须以实际接收到的参数为准
7、关于用户 openid：在关注者与公众号产生消息交互后，公众号可获得关注者的 OpenID（加密后的微信号，每个用户对每个公众号的 OpenID 是唯一的。对于不同公众号，同一用户的 openid 不同）获取 openid 可参考以下地址：http://www.cnblogs.com/txw1958/p/weixin76-user-info.html。使用测试商户号不需要传用户 openid；切换正式的商户号需获取 openid,在请求参数里增加 sub_openid 字段，并把获取的
openid 值传给 sub_openid。在切换成正式商户号传sub_openid 参数前，需提供正式商户号和公众号（服务号） appid 由我方配置，如果没有配置的话，会报 sub_appid and su_openid not match 错误，导致无法正常调用接口
8、其它注意事项
（ 1）参数大小写问题
请留意文档中要求的字符大小写问题，如 “ md5 运算后，字符串的字符要转换为大写” 。
（ 2）参数格式问题
所有传入参数，均为字符串类型，请注意文档中各处的具体要求。
（ 3）时间戳问题
请使用 Linux 时间戳，注意为字符串格式。精确到秒，不需要到毫秒，即 10 位数字。
（ 4）同一商户订单号支付问题
商户的 out_trade_no 必须全局唯一，调试和生产环境，都需要使用唯一的订单号。
注意：当商户的同一个商户号绑定了多种支付方式也需要加标识来区分，不能出现重复。当发起支付返回失败时，一定要用原订单的 out_trade_no 而不能重新生成新的订单号发起支付，避免同一单重复支付。

问题排查:

备注:

更多返回错误代码请看首页的错误代码描述

文档更新时间: 2021-03-23 10:29 作者：EricYang