支付接口说明文档.docx

支付接口说明文档
版本：2. 11文档说明1.1功能描述
本文描述了【支付平台】提供给合作商户的支付解决方案，帮助商户轻松实现在线收款的功能。文档分别从交互模式、签名、接口、注意事项等方面详细介绍了【支付平台】的接口连接方式和开发注意事项，可以帮助开发人员快速集成支付接口到网站中去。
1.2阅读对象
合作商户系统的技术开发人员，要求具有WEB程序开发背景，了解http和https请求和应答的格式和过程，对json格式有所掌握。
1.3业务术语2接口开发2.1支付角色定位
术语
解释
防钓鱼
“网络钓鱼”攻击利用欺骗性的电子邮件和伪造的Web站点来进行诈骗活动，受骗者往往会泄露自己的财务数据，如信用卡号、 账户用户名、口令和社保编号等内容，造成损失。防钓鱼用来防止以上情况的发生。
商户号
注册成为商户后，系统自动分配一个五位数字商户ID,登录商户后台即可查看
请求
通过HTTP协议把需要传输的数据发送给接收方的过程。
同步通知
页面交垃，商户订单请求支付完成后，【支付平台】会将得到的处理结果参数，传递到商户提供的return_url地址上，同时 从【支付平台】支付成功页面跳转到商户提供的接收结果页面上。页面交互不作为修改商户订单状态的依据
异步通知
服务器交巡，商户订单请求支付完成后，【支付平台】的服务器会主动发起通知给商户的网站，同时携带处理完成的结果 信息反馈给商户网站。
密钥
为保证通讯不被篡改，商户在【支付平台】网站上获取的一组字符串，生成签名的时侯使用：登录商户后台即可查看
在电子商务中，商家、买家、中间服务方是交易活动中的三个环节。买家向商家购买服务或者商品使用中间服务方来进行支付。
在这个过程中商家的网站需要集成中间服务方的支付功能，让买家完成付款的动作。【支付平台】作为一家专业的中间服务方除了 提供支付接口外，还提供了订单查询接口，让商家能把更多的精力集中到商品服务上。
2.2接口介绍2.2. 1接口请求地址请求地址：（https或）注：对接前请与【支付平台】客服人员确认最新域名功能说明：通过POST/GET请求到【支付平台】，可选择直连跳转或返回交易连接模式，具体根据不同接口处理。
2.3接入准备
商户集成支付接口，需要先申请一个【支付平台】注册账号，等待账号审核通过。
审核成功才能进行对接，登录【支付平台】商户后台，获取商户ID和商户密钥2.4支付实现流程
（1）构造请求数据
商户根据【支付平台】提供的接口规则，通过程序生成得到签名结果及要传输给【支付平台】的数据集合。
（2）发送请求数据
把构造完成的数据集合，通过页面链接跳转或表单提交的方式传递给【支付平台】。
（3）【支付平台】对请求数据进行处理
【支付平台】得到这些集合后，会先进行安全校验等验证，一系列验证通过后便会处理这次发送过来的数据请求。
（4）返回处理的结果数据
对于处理完成的交易，【支付平台】会以两种方式把数据反馈给商户网站。
同步通知——程序上自动进行重.新构造URL地址链接，在用户当前页面上通过自动跳转的方式跳回商户在请求时设定好的页面路径地址（参数return url,如果商户没有设定，则不会进行该操作）：
异步通知——【支付平台】服务器主动发起通知，调用商户在请求时设定好的页面路径（参数notify url） °
（5）获取的返回结果数据进行处理
商户在同步通知处理页面（参数return_url指定页面文件）或服务器异步通知页面（参数notify url指定页面文件）获取【支付平台】返回的结果数据后，可以结合自身网站的业务逻辑进行数据处理（如：订单更新、自动充值到会员账号中等）°3数据交互3.1页面跳转交互
页面跳转交互是指商户系统与【支付平台】的数据交互通过用户浏览器中转进行，是一种实时的同步交互。
如买家下单买一个商品，商户系统会生成一个支付链接，此链接通过用户的浏览器跳转到【支付平台】，支付通过此链接获取 支付请求的参数，这个支付请求用的就是页面跳转交互模式。
用户在支付页面完成支付后，支付通过return_url跳转到商户系统接收页面返回结果的页面，显示支付成功状态给用户。
3.2服务器通知交互
服务器通知交互是指【支付平台】主动向商户系统发送通知数据，并同步等待商户系统处理完毕后返问的响应数据。数据交互 是【支付平台】服务器与商户服务器宜接通信，一•般请求采用http的Get和post同时传，应答用字符串格式。
如用户支付成功后，【支付平台】会在后台通过支付请求noi ify_url参数向商户系统发起通知，商户处理后成功返网success, 失败返回error或其他字符。
4数据格式POST
采用HTTP标准的POST协议，为了保证接收方接收数据正确，传递的参数如果存在特殊字符（如&、=等）需要进行URL Encode。
4.1 JSON数据格式
采用标准JSON协议，一般不会有多级节点嵌套。
5数字签名
为了保证数据传输过程中的数据真实性和完整性，我们需要对数据进行数字签名，在接收签名数据之后进行签名校验。
数字签名有两个步骤，先按一定规则拼接签名的原始串，再使用指定加密方式和密钥计算出签名结果。
5.1签名原始串
无论是用post/get,签名原始串根据相关的约定来进行拼接，不进行URL Encode。
5.2签名算法2. 1 MD5 签名
MD5是一种摘要生成算法，通过在签名原始串后加上商户通信密钥的内容，进行MD5运算，形成的摘要字符串即为签名结果。 为了方便比较，签名结果统一转换为小写字符。
商户首先需要进入【支付平台】商户后台，获取MD5密钥。
交易请求时请选择加密方式为：MD5
根据下面的签名明文拼接说明，将参数信息进行拼接后使用您选择的签名方式进行对应的加密签名，生成对应的密文后赋值给 参数：sign
•拼接签名明文数据
将参数与其对应值，根据参数名按字典序正序组合成“key（参数名）=value（参数值）”的格式（参数值为空不参与签名）， 并旦把这些参数用&字符连接起来，此时生成的字符吊为待签名字符串。
签名明文：key 1=val uel&key2=va 1 ue2&key3=va 1 ue3
MD5签名验证
例如：key 1 =va 1 uel&key2=va 1 ue2&key3=va 1 ue3 密钥
根据拼接规则将参数拼接后在最后而添加上密钥，使用MD5进行加密得到密文并转换为小写。其中密钥是在【支付平 台】商户后台获取.注：MD5加密编码为UTF-85.2.2 RSA加密算法
> 暂无6接口6.1支付接口1. 1业务功能
买家在商户网站拍下商品或服务后，商户系统调用【支付平台】支付接口，页而跳转或获取支付链接自行处理。用户完成支付 后，【支付平台】把用户引导回商户页面（return_url）,同时服务器后台通知商户服务器（notify_url）支付结果。
6. 1.2数据交互
请求：POST/GET
返网结果：前段网页显示支付结果，最终支付结果一般以后台通知（异步通知）接收的支付状态为准。
请求参数列表注意：所有参数都必须是utf-8编码。
参数
参数名称
类型（长度）
参数说明
必填
样例
amount
交易金额
String(10)
该笔订单的资金总额，单位为：RMB.取 值范围为［1, 1000000.00］,精确到小数点 后两位。
是
88.88
attach
商户扩展信
息
String(MAX)
通知时原样返回，由字母和数字组成。
否
chuanqi
ip
用户IP
String(15)
用户支付时IP地址
否

mch_id
商户号
String(5)
商户号，五位数字，商户后台可查看
是
10000
mch_order_no
商户订单号
String(10,50)
商户订单号

210822
notify_url
服务器异步 通知路径
String(200)
服务席主动异步通知商户网站指定的路径
是
http://www. shanghu. com/s
uccess. html
pay.type
支付方式
String(10)
参考6. 2支付方式设置
是
请参考6. 2支付方式设置
pay_way
支付通道
String(3)
支付通道编号，与平台约定后才可用

11
return_url
页面跳转同
步通知页面
String (200)
支付完成后web页面跳转显示支付结果
否
http:〃www. shanghu. com/r esult. html
title
商品名称
String(50)
用户购买的商品名称，如参数值有中文需要
进行url编码后发送到支付平台
否
在线充值
sign
数字签名
String(32)
签名规则请参考5. 2签名算法
是
请参考5. 2签名算法
参数不能包含特殊字符（如：#、%、&、+、-）、敏感词汇，目前仅支持简体中文，请勿使用其他语言（如：韩文、泰语、藏文、 蒙古文、阿拉伯语）。
同步响应参数说明：
页面返回（同步通知）和服务器返回（异步通知）页面返回和服务器返同，返回的参数是一致的，页面返回（同步通知）通过请求中的return url进行，服务器返p］（异步通知） 通过请求中的notify url来信息，采用Get/Post返回参数包含如下内容：
参数
参数名称
类型（长度）
参数说明
必填
样例
amount
提交金额
String(1O)
该笔订单的资金总额，单位为RMB。取值
范围为[1,1000000.00] o
是
88.88
attach
商户扩展信息
String(MAX)
交场请求时上传，通知原样返回
否
chuanqi
mch_id
商户号
String(5)
商户号，四位数字，商户后台可查看
是
1111
mch_order_no
商户订单号
String(1O.
50)
您的网站订单号

210822
order_no
系统订单号
String(20)
【支付平台】订单号

pay_amount
实付金额
String(10)
该笔订单的资金总额，单位为RMB。取值
范围为[1,1000000.00] o
是
89.00
pay_status
响应代码
String ⑴
请求处理状态
1：处理成功
0：处理失败
是
1
pay time
支付时间
String(19)
格式：yyyy-MM-dd HH:mm:ss
是
2020-05-26 18:18:18
pay_type
支付方式
String(15)
用户的支付方式
是
wx_pc
title
商品名称
String(20)
商品名称
否
在线充值
trade_no
第三方交易号
String(4)
最顶层如微信官方交易号，一般用不到
否

sign
数字签名
String(32)
签名规则请参考5. 2签名算法
是
请参考5. 2签名算法
注意：买家在支付成功后会看到一个【支付平台】提示交易成功的页面，然后会跳转回商户指定的同步通知页面（参数Return_url）o支付结果返回规则
• 通知机制
【支付平台】在用户支付成功后会将支付结果转换成对应的参数信息通过支付请求传递过来的return_url和notify_url两 个网页地址，将支付结果返回给您的网站。
其中，用户付款完成后，【支付平台】会网页跳转到return_url.
并且，同时服务端会将支付结果通过HTTP模拟请求协议，将支付结果通知到notify_url,商户需返回success。
• 特别提示
建议根据异步通知处理您平台的业务！ ！ ！接收到【支付平台】的异步通知后，请根据指定规则验证签名是 否正确，签名通过验证后，根据pay_status判断用户支付状态，当pay_status为1时，可以认为用户己经支付 完成，并根据实际情况使用【支付平台】实际返回的支付金额。代码说明6.2支付方式PayType参数的取值范围，大小写敏感，具体己开通支付方式请对接前与【支付平台】客服确认:
支付方式
编码
Logo图片
微信扫码
wxpc
白微信支区|
微信二维码
wx_qr

微信 II5/WAP
wx_h5

微信公众号
wxgzh

微信小程序
wx min

支付宝扫码
ali_pc
娶源
支付宝二维码
ali_qr

支付宝H5/WAP
ali_h5

支付宝生活号
ali_shh

支付宝花呗
ali_hb

QQ钱包
qq_pc
［曲QQ钱包］
QQ二维码
qq_qr

QQH5/WAP
qq_h5

QQ公众号
qq_gzh

网银
onlinebank

银联快捷支付
yi_kj
快捷厕
银联快捷H5/WAP+
yl_h5

银联云闪付扫码
yi_pc
段银联钱包:
银联云闪付二维码
yl_qr

京东钱包
jd_pc

励京东钱包

7注意事项mch_order_no需要保证在商户号下全局唯'»建议使用"数字账号+日期+序列号"的方式。如果mch_order_no相同，【支 付平台】会拒绝支付。
1 notify_url有可能重复通知，商户需要做去重处理，避免多次业务处理错误notify_url收到的通知，商户处理成功或检查订单已经处理，需要返P1处理成功的标志“success”，以告知【支付平台】 不再通知。