支付接口说明文档.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 ue3MD5签名验证例如：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.88attach商户扩展信息String(MAX)通知时原样返回，由字母和数字组成。否chuanqiip用户IPString(15)用户支付时IP地址否mch_id商户号String(5)商户号，五位数字，商户后台可查看是10000mch_order_no商户订单号String(10,50)商户订单号210822notify_url服务器异步 通知路径String(200)服务席主动异步通知商户网站指定的路径是http:/www. shanghu. com/success. htmlpay.type支付方式String(10)参考6. 2支付方式设置是请参考6. 2支付方式设置pay_way支付通道String(3)支付通道编号，与平台约定后才可用11return_url页面跳转同步通知页面String (200)支付完成后web页面跳转显示支付结果否http:www. shanghu. com/r esult. htmltitle商品名称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.88attach商户扩展信息String(MAX)交场请求时上传，通知原样返回否chuanqimch_id商户号String(5)商户号，四位数字，商户后台可查看是1111mch_order_no商户订单号String(1O.50)您的网站订单号210822order_no系统订单号String(20)【支付平台】订单号pay_amount实付金额String(10)该笔订单的资金总额，单位为RMB。取值范围为1,1000000.00 o是89.00pay_status响应代码String 请求处理状态1：处理成功0：处理失败是1pay time支付时间String(19)格式：yyyy-MM-dd HH:mm:ss是2020-05-26 18:18:18pay_type支付方式String(15)用户的支付方式是wx_pctitle商品名称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/WAPwx_h5微信公众号wxgzh微信小程序wx min支付宝扫码ali_pc娶源支付宝二维码ali_qr支付宝H5/WAPali_h5支付宝生活号ali_shh支付宝花呗ali_hbQQ钱包qq_pc曲QQ钱包QQ二维码qq_qrQQH5/WAPqq_h5QQ公众号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”，以告知【支付平台】 不再通知。