通联互联网支付网关商户接口技术规范模板.docx
《通联互联网支付网关商户接口技术规范模板.docx》由会员分享，可在线阅读，更多相关《通联互联网支付网关商户接口技术规范模板.docx（40页珍藏版）》请在冰豆网上搜索。
通联互联网支付网关商户接口技术规范模板
通联支付网络服务股份有限公司
商户接口说明
版本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-25
沈仕人
调整订单过期时间说明
1.16
-4-18
沈仕人
1.
目的
本文档为使用通联互联网支付网关的商户开发者编写。
本文档为通联互联网支付网关的开发者和相关人员提供有效的指引和帮助。
本文档的目标读者为技术人员。
2.通联互联网支付网关业务简介
2.1名词解释
客户、持卡人:
是指支付过程中的付款方,一般分为”个人客户”和”公司客户”。
商户:
是指支付过程中的收款方,商户需要向我司相关部门申请后获得商户身份,完成商户开户后会分配一个商户号给该商户。
通联支付网关（PaymentGateway）:
是银行金融网络系统和Internet网络之间的接口,本文档中的通联支付网关是通联处理商家支付信息和顾客的支付指令并连接各银行完成支付业务的银行前置系统。
2.2商户与通联合作程序
1.商户与通联签订商户接入协议,通联为商户在通联支付网关系统开户
2.通联为该商户提供测试环境地址、商户号、KEY值及证书,同时向商户提供支付网关的开发包与接入开发指南
3.商户系统加载开发包,完成客户端开发并与通联支付网关测试系统进行联机测试
4.商户测试环境联调成功后,通联向商户发放生产商户号、KEY值、正式证书
1）通联业务人员配置商户证书基本信息,生成商户证书
2）通联业务人员审核允许商户下载证书
3）商户登录通联商户服务网站下载证书
5.商户参数配置
1）商户在通联注册的商户号
2）交易类型
3）通知接收地址
4）加密方式
5）其它支付参数
6.通联为商户开通互联网支付网关的接入权限
7.投入生产
8.清算结算及差错处理
9.报表下载
2.3支付业务流程
2.3.1通联互联网支付网关的网银支付流程
1.客户在商户网站选择商品,商户网站创立一个订单支付请求,支付参数采用HTTP表单（FORM）方式提交（订单上送格式参见3.1小节页面订单提交接口）
2.客户点击支付按钮,将订单发送到通联互联网支付网关的支付页面,支付页面路径如下:
http（s）:
//通联支付网关地址/gateway/index.do
3.支付网关验证订单支付请求,显示支付页面
4.客户在支付页面上选择网银支付
5.网关把客户浏览器转发到网银系统完成支付
6.网关接收到网银系统的支付结果,如果成功,网关根据商户支付订单请求中的通知数据配置发送支付结果信息给商户网站（支付结果返回数据参见3.2小节支付结果返回接口）
2.3.2通知支付结果处理流程
1.持卡人付款成功后,支付网关接收到银行支付结果,服务端将支付结果通知给商户,有两种通知方式:
页面通知和后台通知
2.商户上送订单支付请求中有receiveUrl（商户上送的后台通知地址）和pickupUrl（商户上送的页面通知地址）两字段,如果两个参数都填写,则服务端后台通知到receiveUrl地址,页面跳转方式通知到pickupUrl地址。
3.如果商户网站提交的支付请求中没有receiveUrl参数,只有pickupUrl参数,则以页面跳转方式通知到pickupUrl地址,从网关服务器发起到商户网站的pickupUrl连接请求,再把客户的浏览器转向到pickupUrl地址,将支付结果post到pickupUrl地址所在页面,同时服务端后台也通知到pickupUrl地址。
4.如果商户网站提交的支付请求中没有pickupUrl参数,只有receiveUrl参数,则以后台方式通知商户到receiveUrl地址,从网关服务器发起到商户网站的receiveUrl连接请求,将支付结果post到receiveUrl地址,同时页面也会跳转到receiveUrl地址。
5.一般建议商户两个地址都上送,分别处理后台通知和页面跳转通知。
6.商户网站接收到连接请求,处理对应的订单结果,支付结果返回报文格式（参见3.2小节支付结果返回接口）
7.只要通知成功则停止通知,若从网关服务器发起的到商户网站的url连接请求失败,则把对应的url连接请求发送到系统重发队列中,最多重发3次。
2.3.3清算结算流程
2.3.4退货流程
3.商户系统接入接口定义
3.1页面订单提交接口
商户网站创立的订单支付请求报文是符合HTTP表单（Form）的形式,采用MD5签名（参见第4小节签名机验签机制）,商户上送的form参数不允许含有空格字符,因此保证各参数头尾空格trim。
注意:
1、通联经过merchantId、orderDatetime和orderNo确定一笔订单,且同一笔订单的订单金额必须相同,如果是同一笔订单多次支付建议上述3个值上送时候保持不变。
2、每笔订单能够设定过期时间,超过过期时间（最大时间9999分钟后）的订单将被作废不允许支付。
超过过期时间的订单要再支付的话,商户需要跟换订单号（或订单时间,但更建议跟换订单号）。
接入互联网网关地址:
测试环境:
生产环境:
接入手机网关提交地址:
测试环境:
/mobilepayment/mobile/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和receiveUrl两个参数不能同时为空,建议两个地址都填写
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文件签名验签的商户填0
merchantId
商户号
30
不可空
数字串,商户在通联申请开户的商户号
payerName
付款人姓名
32
可为空
英文或中文字符,当payType为3、issuerId为telpshx”直连模式”时,该值不可空,为办理银行卡时的所使用的姓名
payerEmail
付款人邮件联系方式
50
可为空
字符串
payerTelephone
付款人电话联系方式
16
可为空
数字串,当payType为3、issuerId不为空”直连模式”时,该值不可空,为付款人支付时所使用的手机号码
payerIDCard
付款人证件号
22
可为空
数字串
pid
合作伙伴的商户号
30
可为空
用于商户与第三方合作伙伴拓展支付业务,PartnermerchantId
orderNo
商户订单号
50
不可空
字符串,只允许使用字母、数字、-、_,并以字母或数字开头;每商户提交的订单号,必须在当天的该商户所有交易中唯一
orderAmount
商户订单金额
10
不可空
整型数字,金额与币种有关
如果是人民币,则单位是分,即10元提交时金额应为1000
如果是美元,单位是美分,即10美元提交时金额为1000
orderCurrency
订单金额币种类型
3
不可空
默认填0
0和156代表人民币、840代表美元、344代表港币
orderDatetime
商户订单提交时间
14
不可空
日期格式:
yyyyMMDDhhmmss,例如:
01
orderExpireDatetime
订单过期时间
14
可为空
整形数字,单位为分钟。
最大值为9999分钟。
如填写则以商户上送时间为准,如不填写或填0或填非法值,则服务端默认该订单9999分钟后过期。
productName
商品名称
256
可为空
英文或中文字符串,请勿首尾有空格字符
productPrice
商品价格
20
可为空
整型数字
productNum
商品数量
8
可为空
整型数字,默认传1
productId
商品代码
20
可为空
字母、数字或-、_的组合;用于使用产品数据中心的产品数据,或用于市场活动的优惠
productDesc
商品描述
400
可为空
英文或中文字符串
ext1
扩展字段1
128
可为空
英文或中文字符串,支付完成后,按照原样返回给商户
ext2
扩展字段2
128
可为空
英文或中文字符串,支付完成后,按照原样返回给商户
extTL
业务扩展字段
1024
可为空
参见《接口技术规范文档3.9节介绍》
payType
支付方式
2
不可空
固定选择值:
0、1、4、10、11、12、21、22
接入手机网关时,该值填固定填0
接入互联网关时,默认为间连模式,填0
若需接入外卡支付,只支持直连模式,即固定上送payType=23,issuerId=visa或mastercard
0代表未指定支付方式,即显示该商户开通的所有支付方式
1个人网银支付
4企业网银支付
10wap支付
11信用卡支付
12快捷付
21认证支付
23外卡
升级会员 