省号百平台支付接口技术规范-V10.docx

【WEB网上号百技术接口规范】
V1.0

2011年6月
湖北公众

目 录

1. 文档说明 3
1.1 文档目标 3
1.2 阅读对象 3
1.3 相关约定 3
1.4 业务及技术支持 3
2. 业务描述及接口开发 3
2.1 功能说明及流程 3
2.2 商户接入前提 4
2.3 参数说明 5
2.3.1 HTTP订单支付请求接口 5
2.3.2退款接口 5
2.4 开发提示 5
2.4.1 商户对支付结果的处理 5
3. 参考资料 5
3.1 出参类型说明 5

1. 文档说明
1.1 文档目标
本文档的目的是为WEB网上支付定义一个标准接口规范，以帮助各省号百及合作商户技术人员接入号百网上支付，并快速掌握号百网上支付相关功能，为业务开展提供支付服务。

1.2 阅读对象
对号百网上支付存在需求的公司、机构及合作商户的网上应用开发人员、维护人员和业务管理人员。

1.3 相关约定
商户：指已注册成为号百用户、并使用号百产品实现其收付费功能需求、为其用户提供各类产品或者相关服务的个人。
用户：指在商户网站等系统购物的个人。
购物：指用户在商户网站购买相关产品或服务。
1.4 业务及技术支持
如果您有任何业务及技术上的疑问，可联系省号百技术人员。
2. 业务描述及接口开发
2.1 功能说明及流程
WEB网上支付方式是指利用网银账户，通过互联网Web网页操作完成支付过程的方式。此种方式下，客户利用PC终端，通过登陆号百或合作方网站，进行商品或服务选购，生成并确认订单信息，根据本人使用借记卡或贷记卡付款的要求，选择相应银行通过银行网银界面实现支付的功能。
用户向交易网站购物时，需要通过一定方式向商户支付相关费用。商户网站系统如果集成号百网上支付功能，则可以让用户安全、方便、快捷地向商户支付选购商品及服务款项，并且商户也可以很容易了解到款项的到帐情况及用户购买的产品或服务。
整体流程如下：
用户在商户交易网站选择产品或服务，在下订单支付完成后，商户网站会将该订单号及对应订单金额等相关信息提交到号百，然后跳转到号百页面进行支付。当支付完成后，号百将支付结果返回商户，并且根据商户指定的地址跳转到商户指定页面。商户系统后台接收到支付结果之后，对数据库进行相应更新，然后在显示给用户的页面中作出相应提示。

2.2 商户接入前提
商户接入号百平台网上支付，须准备好指定网站供客户上网浏览，并为用户提供商品查询、选购，直至下单的功能及页面展示。以下页面须由商户预先实现方能进行号百网上支付接入，参考图示如下：

2.3 参数说明
2.3.1 HTTP订单支付请求接口
http订单支付请求地址：
2.3.1.1接口描述
接口名称
重定向跳转订单支付请求接口
接口描述
通过调用支付接口向号百平台发出支付请求,平台通过支付Portal与用户进行交互，完成支付处理后，重定向回应用系统（SP）
接口提供者
号百平台
接口使用者
应用系统（SP）

2.3.1.2接口定义
应用系统的请求参数定义：
字段
名称
长度
是否必填
说明
BSTMERCHANTID
SP身份标识
CHAR(30)
是
由号百平台统一分配
ORDERSEQ
订单号
CHAR(30)
是
由SP提供，在sp处不能重复，用于标识一个唯一的订单，订单号可以在没有支付成功的情况下，再次进行交易，但每次交易时的订单请求交易流水号不能重复
数字或字母组成
ORDERREQTRANSEQ
订单请求交易流水号
CHAR(30)
是
订单支付请求的交易流水号
每次订单支付时，不要重复
以日期时间yyyyMMddHHmmssff+号百平台商户代码（由号百平台提供），如：
20061012132425350001
2006101213242535为日期时间
0001为号百给定的商户代码
数字或字母组成
ORDERDATE
订单日期
CHAR(8)
是
由SP提供，长度8
yyyy-MM-dd格式
ORDERAMOUNT
订单总金额
NUMBER(10)
是
单位：分
订单总金额 = 产品金额+附加金额
PRODUCTAMOUNT
产品金额
NUMBER(10)
是
单位：分
ATTACHAMOUNT
附加金额
NUMBER(10)
是
单位：分
VIEWURL
前台返回地址
CHAR(256)
是
SP提供的用于接收交易返回的前台url，不做业务处理，仅仅用于前台页面显示结果
DEALURL
后台返回地址
CHAR(256)
是
SP提供的用于接收交易返回的后台url，用于实际的业务处理
USERID
SP用户ID
CHAR(40)
是
SP平台用户ID，为SP平台用户体系的唯一标识。
REMARK
备注
CHAR(256)
是
SP平台提供对本次订单的描述
如：“充值”或
“购买了一张电影票”
ATTACH
附加信息
CHAR(50)
否
SP附加信息
MAC
MAC校验域
CHAR(256)
是
采用标准的MD5算法，由SP实现
说明：
1）商户要保证订单号的唯一性。
2）在商户提交订单的页面上，提交按钮应该是点击一次后，马上不可用，防止用户多次提交。
3） 接口方式采用表单方式，商户将以上信息包含在表单中，直接SUBMIT 到号百平台url上
4）MAC校验，保证了交易信息到支付平台的完整性，参与MAC运算的字符及其顺序如下：
BSTMERCHANTID=123456789&ORDERSEQ=20060314000001&ORDERDATE=20060314&ORDERAMOUNT=10000
将上述固定顺序组织的字符串，参数名均为大写，使用标准md5算法进行摘要，然后将摘要果转成16进制字符串，就是校验域MAC的值，并在提交订单时，将MAC值和订单信息一起提交到号百平台

号百平台的响应参数定义：
字段
名称
类型
是否必填
说明
BSTUPTRANSEQ
号百平台交易流水号
CHAR(50)
是
由号百平台提供，SP必须保存该信息，作为对帐依据
BSTTRANDATE
号百平台交易日期
CHAR(8)
是
由号百平台提供，SP必须保存该信息，格式：yyyy-MM-dd, 商户对账、清算报表以此日期为准
RETNCODE
处理结果码
CHAR(4)
是
由号百平台统一定义，SP需保存，作为对帐数据。结果码为“0000” 表示支付成功，其他值则表示支付失败
RETNINFO
处理结果解释码
CHAR(10)
是
由号百平台统一定义，对支付结果的说明码
ORDERREQTRANSEQ
订单请求交易流水号
CHAR(32)
是
从SP发送的订单的信息中获得
，号百平台原值传回
ORDERSEQ
订单号
CHAR(32)
是
从SP发送的订单的信息中获得
，号百平台原值传回
ORDERAMOUNT
订单总金额
NUMBER(10)
是
从SP发送的订单的信息中获得
，号百平台原值传回，单位：分
订单总金额 = 产品金额+附加金额
PRODUCTAMOUNT
产品金额
NUMBER(10)
是
从SP发送的订单的信息中获得
，号百平台原值传回，单位：分
ATTACHAMOUNT
附加金额
NUMBER(10)
是
从SP发送的订单的信息中获得
，号百平台原值传回，单位：分
USERID
SP用户ID
CHAR(40)
是
SP平台用户ID，为SP平台用户体系的唯一标识。号百平台原值传回
ATTACH
SP附加信息
CHAR(32)
否
从SP发送的订单的信息中获得
，号百平台原值传回
SIGN
数字签名
CHAR(256)
是
数字签名算法由号百平台统一提供，作为核查依据

说明：
1、 商户提供的后台url，号百平台是以post方式将支付结果提交到该url上
2、 商户平台在收到后台支付结果后，请直接在应答时写入格式为UPTRANSEQ_XXXXXX的字符串，其中UPTRANSEQ_ 为固定写死，XXXXXX为号百平台发送过去的号百平台交易流水号
3、 号百平台，如果在60秒钟没有收到应答，则会重复发送，重复次数是3次，如果还没有应答会每隔半小时发送一次截止到第二天凌晨。
4、 号百平台如果收到应答，则不再发送支付结果。
5、 当商户收到号百平台发回来的支付结果信息后，获取支付结果和签名的信息，然后对数字签名进行校验，步骤如下：
1）商户将支付结果的明文和密钥组成一个固定顺序的串，如下：
BSTUPTRANSEQ=20080101000001&BSTMERCHANTID=0250000001&ORDERSEQ=2006050112564931556&ORDERAMOUNT=10000&RETNCODE=0000&RETNINFO=0000&BSTTRANDATE=20060101&KEY=123456
串的顺序不能改变，参数名一定要用大写；
KEY的值由号百平台统一提供。
2）将1）获得的结果使用标准的 MD5 算法运算，再将运算结果转成16进制字符串；
3）将2）获得值和SIGN值进行比较，如一致则数字签名正确，说明信息没有被篡改。

2.3.2退款接口
Webservices接口地址：
方法名：String refund()
号百支付平台对调用该接口的服务器地址进行绑定，在联调前，请提供服务器地址。
请求入参说明：
参数
含义
类型
长度
必填
备注
commCode
商户代码
xsd:string
20
是
由号百平台统一分配给各接入商户
subCommCode
商户子代码
xsd:string
30
否
商户子代码
如没有则填空
commPwd
商户调用密码
xsd:string
20
是
商户执行时需填入相应密码
oldOrderId
原扣款订单号
xsd:string
30
是
原扣款成功的订单号
oldOrderPayId
原订单请求支付流水号
xsd:string
30
是
原订单请求支付流水号
orderRefundId
退款流水号
xsd:string
30
是
该流水在商户处必须是唯一的，而且每次发起支付或退款时，都必须是唯一的
transamt
订单交易金额
xsd:string
12
是
单位为元
如2.00
reqTime
交易请求时间
xsd:string
14
是
YYYYMMDDHHMMSS
mac
Mac校验域
xsd:string
32
是
md5摘要
为什么支付时交易金额单位是分，而在退款时时以元为单位？能否统一？
方法返回参数
类型
长度
必填
备注
xsd:String
20
是
具体见出参类型说明
返回成功即表示退款成功
说明：
1）商户要保证退款流水号的唯一性。
2）在商户提交退款时，防止多次提交同一笔退款。
3）接口方式采用webservices方式，key由号百支付平台分配给各商户。
4）MAC校验，保证了交易信息到支付平台的完整性，参与MAC运算的字符及其顺序如下：
COMMCODE=123456789&COMMPWD=123456&ORDERREFUNDID=20080314000001&REQTIME=20080314&TRANSAMT=10000&KEY=DJKF34ER35D58D
商户平台将上述固定顺序组织的字符串，参数名均为大写，使用标准md5算法进行摘要，然后将摘要果转成16进制字符串，就是校验域MAC的值，将MAC值和订单信息调用接口时，一起提供给号百支付平台

附：
MD5算法的.net实现：
/// <summary>
/// MD5加¨®密¨¹
/// </summary>
/// <param name="str">加¨®密¨¹字Á?符¤?</param>
/// <returns></returns>
private string md5(string str)
{
return System.Web.Security.FormsAuthentication.HashPasswordForStoringInConfigFile(str, "MD5");
}

上述算法如果在实施时遇到具体问题，可以协商解决。
2.4 开发提示
2.4.1 商户对支付结果的处理
l 商户在接收到号百的支付结果之后，基于安全的考虑，请务必要判断同一订单号是否已经针对支付成功的情况进行过处理。特别是对于一些使用号百提供充值功能的商户，必须严格防止对同一订单对用户多次进行充值。如果同一订单号，已经按照支付成功的情况进行过处理，商户再次接收到时则不要重复处理。
l 因网络或银行服务器原因，号百可能第一次发送支付失败的结果给商户，但后来会对同一订单号发送支付成功的信息给商户。商户应在保证对加密验证串等信息严格验证的前提下，对相同订单号按照支付成功的业务逻辑进行处理。即商户收到的支付结果通知有失败也有成功，以成功信息为准进行支付成功相关业务处理。
l 可能会由于网络或者用户刷新页面的原因，商户的页面可能短时间内会多次接收到支付结果信息，而支付人看到的只能是最后的页面。商户最好能在后续的提示中，给出让支付人不易误解的提示信息。

3. 参考资料
3.1出参类型说明
0
本次调用成功

0000
本次调用成功

1001
商户未注册

1002
商户已注册，但未审批

1003
商户已注册，已审批，但未开通

1004
商户已注销

1005
商户原自助服务用户密码错误

1006
商户已注册，但未开通此业务

1007
商户已注册，但未开通此接入方式

1101
订单正在交易中，不允许再次交易

1102
订单交易成功，不允许再次交易

1103
订单交易结果未知，不允许再次交易

1104
订单交易记录不存在或状态不为请求中

1105
订单请求记录不存在或状态不为请求中

1109
退款流水号重复

1119
退款金额超出原始订单金额

2002
请求记录已存在

2003
结果状态不正确

2004
该交易存在，但日志状态已经不是请求状态

2011
银行方扣款失败

2012
银行方扣款超时

2013
卡或帐户类型不存在

2014
卡或帐户密码不正确，但记录密码输错次数失败

3001
银行未注册

3002
银行已注册，但未审批

3003
银行已注册，已审批，但未开通

3004
银行已注销

3005
银行已注册，但未开通此业务

3006
银行交易记录不存在或状态不为请求中

9999
操作失败