通联互联网支付网关商户接口技术规范模板.docx

1、通联互联网支付网关商户接口技术规范模板通联支付网络服务股份有限公司商户接口说明版本v1.0通联支付网络服务股份有限公司 10月16日文件修改记录修改说明版本变更审核批准时间变更人时间审核人时间批准人新建1.0 .10.16邬海艳重整原有网关文档内容、 增加订单批量查询接口说明1.1 .01.06邬海艳修改单笔分账业务示例1.1.1 .04.03邬海艳完善请求报文格式说明1.1.2 .08.19邬海艳增加手机网关接入地址说明1.1.3 -11-28沈仕人完善通联网关接入文档内容, 新增手续费收取业务说明1.1.4 -12-01邬海艳调整签名方式说明更正分账业务说明增加订单唯一性说明1.1.5 -

2、2-25沈仕人调整订单过期时间说明1.16 -4-18沈仕人1. 目的本文档为使用通联互联网支付网关的商户开发者编写。本文档为通联互联网支付网关的开发者和相关人员提供有效的指引和帮助。本文档的目标读者为技术人员。2. 通联互联网支付网关业务简介2.1 名词解释客户、 持卡人: 是指支付过程中的付款方, 一般分为”个人客户”和”公司客户”。商户: 是指支付过程中的收款方, 商户需要向我司相关部门申请后获得商户身份, 完成商户开户后会分配一个商户号给该商户。通联支付网关(Payment Gateway): 是银行金融网络系统和Internet网络之间的接口, 本文档中的通联支付网关是通联处理商家支

3、付信息和顾客的支付指令并连接各银行完成支付业务的银行前置系统。2.2 商户与通联合作程序1. 商户与通联签订商户接入协议, 通联为商户在通联支付网关系统开户2. 通联为该商户提供测试环境地址、 商户号、 KEY值及证书, 同时向商户提供支付网关的开发包与接入开发指南3. 商户系统加载开发包, 完成客户端开发并与通联支付网关测试系统进行联机测试4. 商户测试环境联调成功后, 通联向商户发放生产商户号、 KEY值、 正式证书1) 通联业务人员配置商户证书基本信息, 生成商户证书2) 通联业务人员审核允许商户下载证书3) 商户登录通联商户服务网站下载证书5. 商户参数配置1) 商户在通联注册的商户号

4、2) 交易类型3) 通知接收地址4) 加密方式5) 其它支付参数6. 通联为商户开通互联网支付网关的接入权限7. 投入生产8. 清算结算及差错处理9. 报表下载2.3 支付业务流程2.3.1 通联互联网支付网关的网银支付流程1. 客户在商户网站选择商品, 商户网站创立一个订单支付请求, 支付参数采用HTTP表单( FORM) 方式提交( 订单上送格式参见3.1小节页面订单提交接口) 2. 客户点击支付按钮, 将订单发送到通联互联网支付网关的支付页面, 支付页面路径如下: http(s):/通联支付网关地址/gateway/index.do3. 支付网关验证订单支付请求, 显示支付页面4. 客户

5、在支付页面上选择网银支付5. 网关把客户浏览器转发到网银系统完成支付6. 网关接收到网银系统的支付结果, 如果成功, 网关根据商户支付订单请求中的通知数据配置发送支付结果信息给商户网站( 支付结果返回数据参见3.2小节支付结果返回接口) 2.3.2 通知支付结果处理流程1. 持卡人付款成功后, 支付网关接收到银行支付结果, 服务端将支付结果通知给商户, 有两种通知方式: 页面通知和后台通知2. 商户上送订单支付请求中有receiveUrl(商户上送的后台通知地址)和pickupUrl(商户上送的页面通知地址)两字段, 如果两个参数都填写, 则服务端后台通知到receiveUrl地址, 页面跳转

6、方式通知到pickupUrl地址。3. 如果商户网站提交的支付请求中没有receiveUrl参数, 只有pickupUrl参数, 则以页面跳转方式通知到pickupUrl地址, 从网关服务器发起到商户网站的pickupUrl连接请求, 再把客户的浏览器转向到pickupUrl地址, 将支付结果post到pickupUrl地址所在页面, 同时服务端后台也通知到pickupUrl地址。4. 如果商户网站提交的支付请求中没有pickupUrl参数, 只有receiveUrl参数, 则以后台方式通知商户到receiveUrl地址, 从网关服务器发起到商户网站的receiveUrl连接请求, 将支付结果

7、post到receiveUrl地址, 同时页面也会跳转到receiveUrl地址。5. 一般建议商户两个地址都上送, 分别处理后台通知和页面跳转通知。6. 商户网站接收到连接请求, 处理对应的订单结果, 支付结果返回报文格式( 参见3.2小节支付结果返回接口) 7. 只要通知成功则停止通知, 若从网关服务器发起的到商户网站的url连接请求失败, 则把对应的url连接请求发送到系统重发队列中, 最多重发3次。2.3.3 清算结算流程2.3.4 退货流程3. 商户系统接入接口定义3.1 页面订单提交接口商户网站创立的订单支付请求报文是符合HTTP表单(Form)的形式, 采用MD5签名(参见第4小

8、节签名机验签机制), 商户上送的form参数不允许含有空格字符, 因此保证各参数头尾空格trim。注意: 1、 通联经过merchantId 、 orderDatetime 和orderNo 确定一笔订单, 且同一笔订单的订单金额必须相同, 如果是同一笔订单多次支付建议上述3个值上送时候保持不变。2、 每笔订单能够设定过期时间, 超过过期时间(最大时间9999分钟后)的订单将被作废不允许支付。超过过期时间的订单要再支付的话, 商户需要跟换订单号(或订单时间, 但更建议跟换订单号)。接入互联网网关地址: 测试环境: 生产环境: 接入手机网关提交地址: 测试环境: /mobilepayment/m

9、obile/SaveMchtOrderServlet.action生产环境: /mobilepayment/mobile/SaveMchtOrderServlet.action参数名称参数含义长度是否必填参数说明inputCharset字符集2不可空默认填1; 1代表UTF-8、 2代表GBK、 3代表GB2312; pickupUrl付款客户的取货url地址100可为空客户的取货地址, pickupUrl和receiveUrl两个参数不能同时为空, 建议两个地址都填写receiveUrl服务器接受支付结果的后台地址100可为空通知商户网站支付结果的url地址, pickupUrl和recei

10、veUrl两个参数不能同时为空, 建议两个地址都填写version网关接收支付请求接口版本10不可空默认填v1.0,固定选择值: v1.0、 v2.0; 注意为小写字母, 无特殊需求请一律填写v1.0该字段决定payType、 issuerId是否参与签名language网关页面显示语言种类2可为空默认填1, 固定选择值: 1; 1代表简体中文、 2代表繁体中文、 3代表英文signType签名类型2不可空默认填1, 固定选择值: 0、 1; 0表示订单上送和交易结果通知都使用MD5进行签名1表示商户用使用MD5算法验签上送订单, 通联交易结果通知使用证书签名Asp商户不使用通联dll文件签名

11、验签的商户填0merchantId商户号30不可空数字串, 商户在通联申请开户的商户号payerName付款人姓名32可为空英文或中文字符, 当payType为3、 issuerId为telpshx”直连模式”时, 该值不可空, 为办理银行卡时的所使用的姓名payerEmail付款人邮件联系方式50可为空字符串payerTelephone付款人电话联系方式16可为空数字串, 当payType为3、 issuerId不为空”直连模式”时, 该值不可空, 为付款人支付时所使用的手机号码payerIDCard付款人证件号22可为空数字串pid合作伙伴的商户号30可为空用于商户与第三方合作伙伴拓展支付

12、业务, Partner merchantIdorderNo商户订单号50不可空字符串, 只允许使用字母、 数字、 - 、 _,并以字母或数字开头; 每商户提交的订单号, 必须在当天的该商户所有交易中唯一orderAmount商户订单金额10不可空整型数字, 金额与币种有关如果是人民币, 则单位是分, 即10元提交时金额应为1000如果是美元, 单位是美分, 即10美元提交时金额为1000orderCurrency订单金额币种类型3不可空默认填00和156代表人民币、 840代表美元、 344代表港币orderDatetime商户订单提交时间14不可空日期格式: yyyyMMDDhhmmss,

13、例如: 01orderExpireDatetime订单过期时间14可为空整形数字, 单位为分钟。 最大值为9999分钟。如填写则以商户上送时间为准, 如不填写或填0或填非法值, 则服务端默认该订单9999分钟后过期。productName商品名称256可为空英文或中文字符串, 请勿首尾有空格字符productPrice商品价格20可为空整型数字productNum商品数量8可为空整型数字, 默认传1productId商品代码20可为空字母、 数字或- 、 _ 的组合; 用于使用产品数据中心的产品数据, 或用于市场活动的优惠productDesc商品描述400可为空英文或中文字符串ext1扩展字

14、段1128可为空英文或中文字符串, 支付完成后, 按照原样返回给商户ext2扩展字段2128可为空英文或中文字符串, 支付完成后, 按照原样返回给商户extTL业务扩展字段1024可为空参见接口技术规范文档3.9节介绍payType支付方式2不可空固定选择值: 0、 1、 4、 10、 11、 12、 21、 22接入手机网关时, 该值填固定填0接入互联网关时, 默认为间连模式, 填0若需接入外卡支付, 只支持直连模式, 即固定上送payType=23, issuerId=visa或mastercard0代表未指定支付方式, 即显示该商户开通的所有支付方式1个人网银支付4企业网银支付10 wap支付11信用卡支付12快捷付21认证支付23外卡