新一代商户接入手册V2.7
更新时间:2024-04-30 23:01:01 阅读量: 综合文库 文档下载
- 小微商户接入推荐度:
- 相关推荐
新一代商户接入用户手册
(Version: 2.7)
修订历史记录
日期 20151014 20151021 20151118 20160105 20160118 20160214 20160301 20160506 版本 V2.0 V2.1 V2.2 V2.3 V2.4 V2.5 V2.6 V2.7 说明 修改应答数据签名验签的说明 增加插件包超链接及合并插件 更新.net插件,删除一条hosts配置 更新C语言部分及其他问题 更新文件验签部分示例代码及结算对账文件名 统一security.properties的描述,增加RiskData 更改运营中心电话 修改附录A 上海银联电子支付服务有限公司
地址:上海浦东新区东方路800号 宝安大厦29楼-30楼 (200122)
Tel: (86-021)60872088 Fax: (86-021)60872000 Website: http://www.ChinaPay.com ?Copyright 2010 ChinaPay e-Payment Service Co.,Ltd. All rights reserved
作者 初伟 初伟 初伟 初伟 初伟 初伟 初伟 初伟 http://www.ChinaPay.com Chinapay新一代商户接入手册
目录
1 ChinaPay简介.......................................................................................................................... 4 2 前言........................................................................................................................................... 4
2.1 目的 ........................................................................................................................... 4 3 总述........................................................................................................................................... 4
3.1 使用对象 ................................................................................................................... 4 3.2 运行及开发环境 ....................................................................................................... 5 3.3 术语 ........................................................................................................................... 5 3.4 NetPayClient的使用 .............................................................................................. 6
3.4.1 NetPayClient for Java 使用说明 ........................................................... 6 3.4.2 NetPayClient for PHP使用说明 ............................................................ 12 3.4.3 NetPayClient for .NET使用说明 .......................................................... 18 3.4.4 NetPayClient for C使用说明 ................................................................ 24
4 交易流程说明 ......................................................................................................................... 29
4.1 消费类交易流程 ..................................................................................................... 29 4.2 后续类交易流程 ..................................................................................................... 30 4.3 查询交易流程 ......................................................................................................... 31 4.4 对账处理流程 ......................................................................................................... 31 4.5 结算处理流程 ......................................................................................................... 31 5 数据类型定义 ......................................................................................................................... 31 6 消费类交易接口 ..................................................................................................................... 32
6.1 接入地址 ................................................................................................................. 32 6.2 请求报文 ................................................................................................................. 33 6.3 应答报文 ................................................................................................................. 35 7 后续类交易接口 ..................................................................................................................... 37
7.1 接入地址 ................................................................................................................. 37 7.2 请求报文 ................................................................................................................. 38 7.3 同步响应 ................................................................................................................. 40 7.4 应答报文 ................................................................................................................. 40 8 交易查询接口 ......................................................................................................................... 41
8.1 接入地址 ................................................................................................................. 41 8.2 请求报文 ................................................................................................................. 41 8.3 应答报文 ................................................................................................................. 42 9 对账接口 ................................................................................................................................. 43
9.1 概述 ......................................................................................................................... 43 9.2 通知商户的地址规范 ............................................................................................. 43
9.2.1 https方式 .................................................................................................. 43 9.2.2 ftp方式 ...................................................................................................... 44 9.3 对账文件名规则 ..................................................................................................... 44 9.4 商户对账文件格式(版本号:20150813) ......................................................... 44 10 网银支付结算接口 ......................................................................................................... 46
10.1 概述 ......................................................................................................................... 46
第 2 页 共 35 页
http://www.ChinaPay.com Chinapay新一代商户接入手册
10.2 通知商户的地址规范 ............................................................................................. 46
10.2.1 https方式 .................................................................................................. 46 10.2.2 ftp方式 ...................................................................................................... 46 10.3 结算文件名规则 ..................................................................................................... 47 10.4 商户结算文件格式(版本号:20150813) ......................................................... 47
附录A 常见接入问题及解答 ........................................................................................ 48 附录B 应答码说明 ........................................................................................................ 49 附录C 支付机构代码 .................................................................................................... 58 ChinaPay商户安全加密控件 ........................................................................................ 61 14.1 JAVA版 .................................................................................................................... 61 14.2 PHP版 ...................................................................................................................... 61 14.3 .NET版 .................................................................................................................... 62 14.4 C语言版 .................................................................................................................. 62
11 12 13 14
第 3 页 共 35 页
http://www.ChinaPay.com Chinapay新一代商户接入手册
1 ChinaPay简介
CHINAPAY 致力于发展中国金融电子支付服务。
银联电子支付服务有限公司(ChinaPay)是中国银联控股的银行卡专业化服务公司,拥有面向全国的
统一支付平台,主要从事以互联网等新兴渠道为基础的网上支付、企业B2B账户支付、电话支付、网上跨行转账、网上基金交易、企业公对私资金代付、自助终端支付等银行卡网上支付及增值业务,是中国银联旗下的网络方面军。
ChinaPay依托中国银联全国统一的跨行信息交换网络,在人民银行及中国银联的业务指导和政策支持下,致力于银行卡受理环境的建设和银行卡业务的推广,将先进的支付科技与专业的金融服务紧密结合起来,通过业务创新形成多元化的支付服务体系,为广大持卡人和各类商户提供安全、方便、快捷的银行卡支付及资金结算服务。公司充分利用中国银联全国性的品牌、网络、市场等优势资源,整合银联体系的系统资源、银行资源、商户资源和品牌影响力,实现强强联合、资源共享和优势互补。
经过数年的开拓发展,ChinaPay拥有了雄厚的技术开发力量及丰富的业务拓展经验,为网上购物、金融、民航、旅游、彩票、移动通讯等行业领域提供了先进的支付系统解决方案,并积累了丰富的工程项目实施经验。
2 前言
ChinaPay商户支付接口接入为ChinaPay商户会员提供完善的网上支付解决方案,让商户更快捷、方
便和安心的开展网上交易。目前ChinaPay商户支付接口接入提供如下功能:
? ? ?
商户消费交易的银行支付 商户针对成功消费交易的退款 商户对已有交易(消费)查询
2.1 目的
本手册的主要目的是帮助ChinaPay商户会员使用我们提供的支付服务接口方式。 3
总述
3.1 使用对象
本手册的使用对象为ChinaPay商户会员的网上应用开发人员、维护人员和管理人员,他们应具有如下之一或者几项基本知识:
熟悉Microsoft Windows/NT、Windows9x、Windows 2000、HP-UX、AIX、SUN Solaris、Linux、BSD等操作系统;
熟悉上述系统上的网站设置和网页制作方法;
熟悉标准CGI(Common Gateway Interface)或ASP(Active Server Pages)或ISAPI的开发方法或PHP或JAVA;
了解一般信息安全的基本概念。
第 4 页 共 35 页
http://www.ChinaPay.com Chinapay新一代商户接入手册
3.2 运行及开发环境
商户可根据自己的实际情况,选用合适的开发平台和运行平台。ChinaPay将提供对应的NetPayClient版本。目前ChinaPay的NetPayClient有如下几种:
? ? ? ?
NetPayClient for Java (以JAR的方式提供) NetPayClient for Win32 (以DLL方式提供) NetPayClient for (以.class.php方式提供) NetPayClient for C (以.so或.a的方式提供)
3.3 术语
电子商务 Electronic Commerce是指通过信息网络以电子数据信息流通的方式在全世界范围内进行并完成的各种商务活动、交易活动、金融活动和相关的综合服务活动。
网络贸易 指在网络平台基础上直接进行在线贸易(Trade Online),利用数字化技术将企业、海关、运输、金融、商检和税务等有关部门有机连接起来,实现从浏览、洽谈、签约、交货到付款等全部或部分业务自动化处理。网络贸易由信息共享、订购、支付、执行、服务与支持5个部分组成,每个部分在网络贸易中都各自承担了不同的任务。
B2C(Business to Consumer) 指企业与消费者之间的电子商务。这是消费者利用因特网直接参与经济活动的形式,类同于商业电子化的零售商务。目前,在因特网上有许许多多各种类型的虚拟商店和虚拟企业,提供各种与商品销售有关的服务。
B2B(Business to Business) 指企业与企业间的电子商务。企业可以使用因特网或其它网络对每笔交易寻找最佳合作伙伴,完成从订购到结算的全部交易行为,包括向供应商订货、签约、接受发票和使用电子资金转移、信用证、银行托收等方式进行付款,以及在商贸过程中发生的其它问题,如索赔、商品发送管理和运输跟踪等。
商户 具有电子商务功能的商店和企业。
银行卡 商业银行所发行的储蓄卡、信用卡、储值卡、企业购物卡、购物联名卡、虚拟电子卡等支付工具。
持卡人 银行卡的拥有者。
网上支付密码 数字串。发卡行用于鉴别网上持卡人身份,具体产生方法、使用范围和管理规范见各发卡行\业务规范\。
发卡行 具有发行银行卡功能的商业银行。
开户行 指持卡人卡账户或企业资金账户所在的商业银行。
SSL(Secure Socket Layer) 是一种基于网络传输层的安全网络传输协议,实现客户端与服务器端间的数据安全传递。
第 5 页 共 35 页
http://www.ChinaPay.com Chinapay新一代商户接入手册
3.4 NetPayClient的使用
说明
NetPayClient实现消费者、商户和银行间的网上安全支付。提供如下功能: ? ? ? ?
商户对订单关键信息进行数字签名 商户验证ChinaPay发送的交易应答 商户对一段字符串的签名 商户对一段字符串的签名验证
各语言NetPayClient压缩包见14章。 3.4.1
NetPayClient for Java 使用说明
3.4.1.1 核心文件清单
名 称 chinapaysecure.jar Chinapayfilesecure.jar Mer.pfx 放置的路径 根据项目工程的需要放置对应路径下 用 途 用于提供商户签名、验签、加密、解密方法调用 根据项目工程的需要放置对应路径下 用于提供商户验签结算和对账文件 可以放置到任意路径下,但是需要调用方法指定文件位置和名称 商户签名证书(控台申请) cp.cer 可以放置到任意路径下,但是需要调用方法指定文件位置和名称 ChinaPay签名证书 3.4.1.2 方法说明
类名 方法名 用 途 初始化商户签名、验签配置信息 用于对商户报文进行签名 获取商户签名值 对交易过程中的敏感数据进行加密 对密码进行加密 获取加密后的密码字符串 获取加密后的密文字符串 验证chinapay返回的应答数据 获取商户签名、验签、加密及解密的处理结果 com.chinapay.secss.SecssUtil init sign getSign encryptData encryptPin getEncPin getEncValue verify getErrCode init SecssFileService verifyFile getErrCode 初始化商户签名、验签配置信息 文件验签 获取商户签名、验签、加密及解密的处理结果 第 6 页 共 35 页
http://www.ChinaPay.com Chinapay新一代商户接入手册
?
初始化安全控件方法:init
方法说明:
public boolean init() 作用:
初始化商户签名、验签配置信息。
使用此方法需要将security.properties放在类路径下,并配置如下: #交易证书路径
sign.file=D:/cert_cp/000000000000001.pfx #交易证书密码
sign.file.password=XXXXXX #交易证书的密钥容器格式 sign.cert.type=PKCS12
#报文中不参与签名的字段名称,多个字段用逗号进行分隔 sign.invalid.fields=Signature,CertId #验签证书路径
verify.file=D:/cert_cp/cp_test.cer #签名值字段名称
signature.field=Signature 参数说明:
security.properties文件中,商户只需要修改sign.file、sign.file.password、verify.file三项。 返回值:
true :表示正确初始化证书文件,并且可以调用签名方法签名或者签名验证方法验证签名; false:表示初始化证书文件失败,不可以使用签名方法和签名验证方法。 注:该方法在类com.chinapay.secss.SecssUtil中。
方法说明:
public boolean init(Properties pros) 作用:
初始化商户签名、验签配置信息。 参数说明:
Properties pros 属性配置文件对象,用于加载商户自定义的属性配置文件,需要在该文件中配置商户签名证书文件绝对路径、签名文件密码、密钥容器格式、验证签名证书文件绝对路径、签名值和证书id、签名值字段名称等。
返回值:
true :表示正确初始化证书文件,并且可以调用签名方法签名或者签名验证方法验证签名; false:表示初始化证书文件失败,不可以使用签名方法和签名验证方法。 注:该方法在类com.chinapay.secss.SecssUtil中。 ?
订单签名方法:sign 方法说明:
public void sign(Map map) 作用:
用于对商户报文进行签名。
第 7 页 共 35 页
http://www.ChinaPay.com Chinapay新一代商户接入手册
参数说明:
Map map 为商户交易数据。 返回值: 无
注:该方法在类com.chinapay.secss.SecssUtil中。 ?
获取签名结果字符串方法:getSign 方法说明:
public String getSign() 作用:
获取商户签名后生成的字符串。 参数说明: 无 返回值:
商户签名结果字符串。
注:该方法在类com.chinapay.secss.SecssUtil中。 ?
敏感数据加密方法:encryptData 方法说明:
public void encryptData(String data) 作用:
对交易过程中的敏感数据进行加密。 参数说明:
String data 待加密的明文字符串 返回值: 无 ?
密码加密方法:encryptPin 方法说明:
public void encryptPin(String pin,String card) 作用:
对密码进行加密。 参数说明:
String pin 银行卡密码 String card 卡号 返回值: 无 ?
获取加密后的密码:getEncPin 方法说明:
public String getEncPin() 作用:
获取加密后的密码字符串。 参数说明: 无 返回值:
第 8 页 共 35 页
http://www.ChinaPay.com Chinapay新一代商户接入手册
加密后的密码字符串。 ?
获取加密后的密文字符串:getEncValue 方法说明:
public String getEncValue() 作用:
获取加密后的密文字符串。 参数说明: 无 返回值:
加密后的密文字符串。 ?
获取商户签名、验签、加密及解密的处理结果的方法:getErrCode 方法说明:
public String getErrCode() 作用:
获取商户签名、验签、加密及解密的处理结果。 参数说明: 无 返回值:
00表示处理成功,其他表示处理失败。
注:该方法在类com.chinapay.secss.SecssUtil中。
第 9 页 共 35 页
http://www.ChinaPay.com Chinapay新一代商户接入手册
?
验证交易应答方法:verify
方法说明:
public void verify(Map map) 作用:
验证chinapay返回的应答数据。 参数说明:
Map map 返回商户报文中的所有参数。 返回值: 无
注:该方法在类com.chinapay.secss.SecssUtil中。 ?
文件验签方法:verifyFile 方法说明:
public void verifyFile(String path) 作用:
验证chinapay返回的文件签名。 参数说明: 文件路径。 返回值: 无 ?
注:该方法在类com.chinapay.secss.SecssUtil中。
3.4.1.3 使用示例代码
(以下代码未经测试,仅供参考)
?
签名示例代码 //初始化安全控件:
public static void main(String[] args) {
Map
myMap.put(\myMap.put(\??
SecssUtil secssUtil = new SecssUtil(); //从默认配置文件初始化安全控件 secssUtil.init();
System.out.println(\未知错误测试-->\secssUtil.sign(myMap);
if(!\ }
String sign = secssUtil.getSign(); System.out.println(\
第 10 页 共 35 页
System.out.println(\签名过程发生错误,错误信息为-->\return;
http://www.ChinaPay.com Chinapay新一代商户接入手册
} ?
验证签名示例代码
Map
myMap.put(\//参与签名的字段和值
myMap.put(\myMap.put(\??
secssUtil.verify(myMap);
if(!\
}
System.out.println(\验签通过。\} ?
验签文件示例代码
public static void main(String[] args) { try {
SecssFileService secssFileService = new SecssFileService(); secssFileService.init();
File f = new File(\ secssFileService.verifyFile(f.getPath());
System.out.println(\验签结果:\
if(!\
System.out.println(\验签过程发生错误,错误信息为-->\ return;
System.out.println(\验签过程发生错误,错误信息为-->\return;
public static void main(String[] args) {
secssFileService.getErrMsg());
}
} catch (Exception e) { e.printStackTrace(); } } ?
敏感信息加密示例代码
//敏感信息加密,需要先将加密的敏感信息转成json格式,base64加密处理 Map
第 11 页 共 35 页
public static void main(String[] args) {
http://www.ChinaPay.com Chinapay新一代商户接入手册
SecssUtil secssUtil = new SecssUtil(); secssUtil.init();
secssUtil.encryptData(Base64.encodeBase64String(new
ObjectMapper().writeValueAsString(cardInfoMap).getBytes()));
if(!\ }
System.out.println(\敏感信息加密成功,敏感信息机密结果[\} ?
密码加密示例代码
Map
SecssUtil secssUtil = new SecssUtil(); secssUtil.init();
secssUtil.encryptPin(pin, card);
if(!\ } 3.4.2
NetPayClient for PHP使用说明 }
System.out.println(\密码加密结果[\
System.out.println(\密码加密出错,错误信息为\return;
public static void main(String[] args) {
System.out.println(\敏感信息加密发生错误,错误信息为return;
\
3.4.2.1 核心文件清单
名 称 SecssUtil.class.php Mer.pfx 放置的路径 根据项目工程的需要放置对应路径下 支持PHP5.4.8及以上版本 可以放置到任意路径下,但是需要调用方法指定文件位置和名称 用 途 用于提供商户签名、验签、加密、解密、文件验签等方法调用 商户签名证书(控台申请) cp.cer 可以放置到任意路径下,但是需要调用方法指定文件位置和名称 ChinaPay签名证书 security.properties 安全配置文件,根据项目工程的需要放置对应路径下 指定签名验签证书文件存放路径等 第 12 页 共 35 页
http://www.ChinaPay.com Chinapay新一代商户接入手册
3.4.2.2 方法说明
类名 SecssUtil 方法名 init sign getSign verify verifyFile encryptData encryptPin getEncPin getEncValue getErrCode getErrMsg 用途 用于创建证书对象,初始化安全加密控件并初始化公私钥信息 用于对商户报文进行签名 获取商户签名后生成的字符串 验证ChinaPay返回的应答数据 验证ChinaPay返回的结算和对账文件签名 对交易过程中的敏感数据进行加密 对密码进行加密 获取加密后的密码字符串 获取加密后的密文字符串 获取商户签名、验签、加密及解密的处理结果 获取对响应码的中文描述 ?
初始化安全控件方法:init 方法说明:
public function init($securityPropFile) 作用:
用于创建证书对象,初始化安全加密控件并初始化公私钥信息。
使用此方法需要将security.properties放在PHP项目路径下,并配置如下: #交易证书路径
sign.file=D:/cert_cp/000000000000001.pfx #交易证书密码
sign.file.password=XXXXXX #交易证书的密钥容器格式 sign.cert.type=PKCS12
#报文中不参与签名的字段名称,多个字段用逗号进行分隔 sign.invalid.fields=Signature,CertId #验签证书路径
verify.file=D:/cert_cp/cp_test.cer #签名值字段名称
signature.field=Signature 参数说明:
securityPropFile:security.properties文件全路径
security.properties文件中,商户只需要修改sign.file、sign.file.password、verify.file三项。 返回值:
true :表示正确初始化证书文件,并且可以调用签名方法签名或者签名验证方法验证签名; false:表示初始化证书文件失败,不可以使用签名方法和签名验证方法。 注:该方法在类SecssUtil中。 ?
订单签名方法:sign
第 13 页 共 35 页
http://www.ChinaPay.com Chinapay新一代商户接入手册
方法说明:
public function sign($paramArray) 作用:
用于对商户报文进行签名。 参数说明:
$paramArray 为数组形式的商户交易数据。数组格式如: array(\MerOrderNo \
返回值: 无 ?
获取签名结果字符串方法:getSign 方法说明:
public function getSign() 作用:
获取商户签名后生成的字符串。 参数说明: 无 返回值:
商户签名结果字符串。
注:该方法在类SecssUtil中。 ?
验证交易应答方法:verify 方法说明:
public function verify($paramArray) 作用:
验证chinapay返回的应答数据。 参数说明:
$paramArray 返回商户报文中的所有参数。 返回值: 无
注:该方法在类SecssUtil中。 ?
验证文件方法:verifyFile 方法说明:
public function verifyFile($file) 作用:
验证结算和对账文件签名。 参数说明: $file文件路径 返回值: 无
注:该方法在类SecssUtil中。 ?
敏感数据加密方法:encryptData 方法说明:
public function encryptData($data) 作用:
第 14 页 共 35 页
http://www.ChinaPay.com Chinapay新一代商户接入手册
对交易过程中的敏感数据进行加密。 参数说明:
$data 待加密的明文字符串 返回值: 无
注:该方法在类SecssUtil中。 ?
密码加密方法:encryptPin 方法说明:
public function encryptPin($pin, $card) 作用:
对密码进行加密。 参数说明: $pin 银行卡密码 $card 卡号 返回值: 无
注:该方法在类SecssUtil中。 ?
获取加密后的密码:getEncPin 方法说明:
public function getEncPin() 作用:
获取加密后的密码字符串。 参数说明: 无 返回值:
加密后的密码字符串。
注:该方法在类SecssUtil中。 ?
获取加密后的密文字符串:getEncValue 方法说明:
public function getEncValue() 作用:
获取加密后的密文字符串。 参数说明: 无 返回值:
加密后的密文字符串。
注:该方法在类SecssUtil中。 ?
获取商户签名、验签、加密及解密的处理结果的方法:getErrCode 方法说明:
public function getErrCode() 作用:
获取商户签名、验签、加密及解密的处理结果。 参数说明:
第 15 页 共 35 页
http://www.ChinaPay.com Chinapay新一代商户接入手册
无 返回值:
00表示处理成功,其他表示处理失败。 注:该方法在类SecssUtil中。 ?
响应码描述信息:getErrMsg 方法说明:
public function getErrMsg() 作用:
获取对响应码的中文描述。 参数说明: 无 返回值:
响应码的中文描述。
注:该方法在类SecssUtil中。
3.4.2.3 使用示例代码
(以下代码未经测试,仅供参考)
?
签名示例代码
require 'SecssUtil.class.php';
$securityPropFile=\perties\
$paramArray=array(
\\\
\测试-商品信息\\\ AccessType\
\ MerBgUrl\\ MerPageUrl\\
$secssUtil = new SecssUtil();
$secssUtil->init($securityPropFile); //初始化安全控件: $secssUtil->sign($paramArray); if(\
echo\签名过程发生错误,错误信息为-->\ }
$signature==$secssUtil->getSign(); echo \签名数据为:\ ?
验证签名示例代码
第 16 页 共 35 页
return;
http://www.ChinaPay.com Chinapay新一代商户接入手册
require 'SecssUtil.class.php';
$securityPropFile=\perties\
$paramArray=array(
\\\
\测试-商品信息\\\ AccessType\
\ MerBgUrl\\\\???\);
$secssUtil = new SecssUtil();
$secssUtil->init($securityPropFile); //初始化安全控件: $secssUtil->verify($paramArray); if(\
echo\验签过程发生错误,错误信息为-->\ }
echo \验签通过。\?
敏感数据加密示例代码 require 'SecssUtil.class.php';
$securityPropFile=\perties\
$plainData=\$secssUtil = new SecssUtil();
$secssUtil->init($securityPropFile); //初始化安全控件: $secssUtil->encryptData ($plainData); if(\
echo\加密过程发生错误,错误信息为-->\ }
echo \加密后的密文为:\
?
密码加密示例代码
require 'SecssUtil.class.php';
$securityPropFile=\perties\
$card=\$pin=\
第 17 页 共 35 页
return; return;
http://www.ChinaPay.com Chinapay新一代商户接入手册
$secssUtil = new SecssUtil();
$secssUtil->init($securityPropFile); //初始化安全控件: $secssUtil->encryptPin($pin, $card); if(\
echo\密码加密过程发生错误,错误信息为-->\ }
echo \加密后的PIN密文为:\?
文件验签示例代码
require ' SecssUtil.class.php';
$securityPropFile=\perties\
$secssUtil = new SecssUtil(); $secssUtil->init($securityPropFile);
$file=\测试文件.txt\echo \$secssUtil->verifyFile($file); if(\
echo \文件验签成功,errcode=[\}else{
echo \文件验签失败,errcode=[\}
echo \3.4.3
NetPayClient for .NET使用说明 return;
3.4.3.1 核心文件清单
名 称 chinapaysecure.dll BouncyCastle.CryptoExt.dll Mer.pfx 放置的路径 根据项目工程的需要放置对应路径下 用 途 用于提供商户签名、验签、加密、解密等方法调用 根据项目工程的需要放置对应路径下 用于提供商户签名、验签、加密、解密等方法调用 可以放置到任意路径下,但是需要调用方法指定文件位置和名称 商户签名证书(控台申请) cp.cer 可以放置到任意路径下,但是需要调用方法指定文件位置和名称 ChinaPay签名证书 security.properties 安全配置文件,根据项目工程的需要放置对应路径下 指定签名验签证书文件存放路径等 第 18 页 共 35 页
http://www.ChinaPay.com Chinapay新一代商户接入手册
3.4.3.2 方法说明
方法名 init sign getSign verify encryptData encryptPin getEncPin getEncValue getErrCode getErrMsg 用途 用于创建证书对象,初始化安全加密控件并初始化公私钥信息 用于对商户报文进行签名 获取商户签名后生成的字符串 验证chinapay返回的应答数据 对交易过程中的敏感数据进行加密 对密码进行加密 获取加密后的密码字符串 获取加密后的密文字符串 获取商户签名、验签、加密及解密的处理结果 获取对响应码的中文描述 ?
初始化安全控件方法:init 方法说明:
public void init(string securityPropFile) 作用:
用于创建证书对象,初始化安全加密控件并初始化公私钥信息。
使用此方法需要将security.properties放在.NET项目路径下,并配置如下: #交易证书路径
sign.file=D:/cert_cp/000000000000001.pfx #交易证书密码
sign.file.password=XXXXXX #交易证书的密钥容器格式 sign.cert.type=PKCS12
#报文中不参与签名的字段名称,多个字段用逗号进行分隔 sign.invalid.fields=Signature,CertId #验签证书路径
verify.file=D:/cert_cp/cp_test.cer #签名值字段名称
signature.field=Signature 参数说明:
securityPropFile:security.properties文件全路径
security.properties文件中,商户只需要修改sign.file、sign.file.password、verify.file三项。 返回值:
true :表示正确初始化证书文件,并且可以调用签名方法签名或者签名验证方法验证签名; false:表示初始化证书文件失败,不可以使用签名方法和签名验证方法。 ?
订单签名方法:sign 方法说明:
public void sign((Hashtable srcMsg)
第 19 页 共 35 页
http://www.ChinaPay.com Chinapay新一代商户接入手册
作用:
用于对商户报文进行签名。 参数说明:
Hashtable srcMsg为商户交易数据。 返回值: 无 ?
获取签名结果字符串方法:getSign 方法说明:
public string getSign() 作用:
获取商户签名后生成的字符串。 参数说明: 无 返回值:
商户签名结果字符串。 ?
验证交易应答方法:verify 方法说明:
public void verify(Hashtable srcMsg) 作用:
验证chinapay返回的应答数据。 参数说明:
srcMsg返回商户报文中的所有参数。 返回值: 无 ?
敏感数据加密方法:encryptData 方法说明:
public void encryptData(string encContent) 作用:
对交易过程中的敏感数据进行加密。 参数说明:
encContent 待加密的明文字符串 返回值: 无 ?
密码加密方法:encryptPin 方法说明:
public void encryptPin(string aPin, string aCardNO) 作用:
对密码进行加密。 参数说明: aPin银行卡密码 aCardNO卡号 返回值:
第 20 页 共 35 页
http://www.ChinaPay.com Chinapay新一代商户接入手册
无 ?
获取加密后的密码:getEncPin 方法说明:
public string getEncPin() 作用:
获取加密后的密码字符串。 参数说明: 无 返回值:
加密后的密码字符串。 ?
获取加密后的密文字符串:getEncValue 方法说明:
public string getEncValue() 作用:
获取加密后的密文字符串。 参数说明: 无 返回值:
加密后的密文字符串。 ?
获取商户签名、验签、加密及解密的处理结果的方法:getErrCode 方法说明:
public string getErrCode() 作用:
获取商户签名、验签、加密及解密的处理结果。 参数说明: 无 返回值:
00表示处理成功,其他表示处理失败。 ?
响应码描述信息:getErrMsg 方法说明:
Public string getErrMsg() 作用:
获取对响应码的中文描述。 参数说明: 无 返回值:
响应码的中文描述。
3.4.3.3 使用示例代码
(以下代码未经测试,仅供参考)
?
签名示例代码
第 21 页 共 35 页
http://www.ChinaPay.com Chinapay新一代商户接入手册
Hashtable myMap = new Hashtable(); myMap.Add(\ myMap.Add(\ myMap.Add(\ myMap.Add(\ myMap.Add(\ myMap.Add(\ myMap.Add(\ myMap.Add(\
myMap.Add(\
myMap.Add(\ myMap.Add(\
\
myMap.Add(\
myMap.Add(\ myMap.Add(\ myMap.Add(\ myMap.Add(\ myMap.Add(\ myMap.Add(\
myMap.Add(\测试-商品信息\ myMap.Add(\测试-商户保留域\ myMap.Add(\
\moteputr\\\
SecssUtil obj = new SecssUtil();
obj.init(string securityPropFile); //初始化安全控件:
obj.sign(myMap);
String chkValue = obj.getSign(); if(\
Console.writeLine(\签名过程发生错误,错误信息为-->\ }
String signature = obj.getSign();
Console.writeLine(\ ?
验证签名示例代码
Hashtable myMap = new Hashtable();
myMap.Add(\ myMap.Add(\ myMap.Add(\ myMap.Add(\
第 22 页 共 35 页
return;
http://www.ChinaPay.com Chinapay新一代商户接入手册
myMap.Add(\ myMap.Add(\ myMap.Add(\ myMap.Add(\
myMap.Add(\
myMap.Add(\ myMap.Add(\
\
myMap.Add(\
myMap.Add(\ myMap.Add(\ myMap.Add(\ myMap.Add(\ myMap.Add(\ myMap.Add(\
myMap.Add(\测试-商品信息\ myMap.Add(\测试-商户保留域\ myMap.Add(\
\moteputr\\\
myMap.Add(\
SecssUtil obj = new SecssUtil();
obj.init(string securityPropFile); //初始化安全控件: obj.verify(myMap); if(\
Console.writeLine(\验签过程发生错误,错误信息为-->\ }
Console.writeLine(\验签通过。\?
敏感数据加密示例代码 string
securityPropFile=\erties\
string plainData=\SecssUtil obj = new SecssUtil();
obj.init(securityPropFile); //初始化安全控件: obj.encryptData (plainData); if(\
Console.writeLine(\加密过程发生错误,错误信息为\ }
第 23 页 共 35 页
return; return;
http://www.ChinaPay.com Chinapay新一代商户接入手册
Console.writeLine(\加密后的密文为:\
?
密码加密示例代码 String
securityPropFile=\erties\
String card=\String pin=\
SecssUtil obj = new SecssUtil();
obj.init(securityPropFile); //初始化安全控件: obj.encryptPin(pin, card);
if(\
Console.writeLine(\密码加密过程发生错误,错误信息为\ }
Console.writeLine(\加密后的PIN密文为:\3.4.4
NetPayClient for C使用说明 return;
3.4.4.1 核心文件清单
名 称 SecssUtil.h libsecss.a或.so Mer.pfx 放置的路径 根据项目工程的需要放置对应路径下 根据项目工程的需要放置对应路径下 可以放置到任意路径下,但是需要调用方法指定文件位置和名称 用 途 用于C语言开发的应用头文件 签名数据和签证签名的主体方法库 商户签名证书(控台申请) cp.cer 可以放置到任意路径下,但是需要调用方法指定文件位置和名称 ChinaPay签名证书 3.4.4.2 方法说明
? 数据构造函数: build_data
方法说明:
bool build_data(KEY_VALUE_PAIR* from, size_t flen, char* to, size_t* tlen); 作用:
输入键值对的结构体数组生成排序后的字符串 参数说明:
from:输入键值对结构体数组 flen:输入的数组长度 to:用于存放输出字符串的地址 tlen:输出的字符串长度 返回值:
第 24 页 共 35 页
http://www.ChinaPay.com Chinapay新一代商户接入手册
1:成功 0:失败
?
数据签名函数: sign 方法说明:
bool sign(const char* filename, const char* password,
const unsigned char* unSignData, size_t uslen, unsigned char* signData, size_t* slen);
作用:
对传入的字符串进行数字签名 参数说明:
filename:秘钥文件路径 password:秘钥文件密码 unSignData:待签名字符串 uslen:代签名字符串长度
signData:存放签名结果的缓存地址
slen:存放签名结果的缓存长度,输入长度不可太短,否则函数返回失败。函数返回时此参数为实际签名结果的长度。
返回值: 1:成功 0:失败
?
数据签名验证函数: verify
size_t uslen, const unsigned char* signData, size_t slen);
bool verify(const char* filename, const unsigned char* unSignData, 作用:
验证目标字符串的签名是否正确 参数说明:
filename:秘钥文件路径 unSignData:源字符串地址 uslen:源字符串长度 signData:签名字符串地址 slen:签名字符串长度 返回值: 1:成功 0:失败
?
文件签名验证函数: verifyFile
bool verifyFile(const char* certpath, const char* filepath); 作用:
验证文件的签名是否正确 参数说明:
certpath:秘钥文件路径
第 25 页 共 35 页
http://www.ChinaPay.com Chinapay新一代商户接入手册
filepath:交易证书路径 返回值: 1:成功 0:失败
?
数据加密函数: encrypt
unsigned char* to, size_t* tlen);
bool encrypt(const char* filename, unsigned char* from, size_t flen, 作用: 对数据进行加密 参数说明:
filename:秘钥文件路径 from:待加密字符串 flen:待加密字符串长度 to:存放密文的缓存地址
tlen:存放密文的缓存长度,输入长度不可太短,否则函数返回失败。函数返回时此参数为实际密文的长度。
返回值: 1:成功 0:失败
?
数据解密函数: decrypt
size_t flen, unsigned char* to, size_t* tlen);
bool decrypt(const char* filename, const char* password, unsigned char* from, 作用: 对密文进行解密 参数说明:
filename:秘钥文件路径 password:秘钥文件密码 from:密文字符串 flen:密文字符串长度
to:存放解密后字符串的缓存长度,输入长度不可太短,否则函数返回失败。函数返回是次参数为实际解密后的字符串的长度。
返回值: 1:成功 0:失败
3.4.4.3 使用示例代码
#include \#define KEY_LEN 6 #define MEM_LEN 1024 * 4
第 26 页 共 35 页
http://www.ChinaPay.com Chinapay新一代商户接入手册
int main(int argc, char* argv[]) {
if (sign(pfxfile, passwd, buff, buff_len, sign_buf, &sign_len)) {
printf((char*) sign_buf);
第 27 页 共 35 页
printf(\数据签名==========\\n\size_t sign_len = MEM_LEN;
unsigned char sign_buf[MEM_LEN]; // 签名字符串 memset(sign_buf, 0, sign_len);
if (build_data(p, KEY_LEN, (char*) buff, &buff_len)) { }
printf((char*) buff);
printf(\字串长度==========\\n\printf(\printf(\失败\return 0;
printf(\构造字符串==========\\n%unsigned char buff[MEM_LEN]; // 签名原文 size_t buff_len = MEM_LEN; memset(buff, 0, buff_len); KEY_VALUE_PAIR p[KEY_LEN]; p[0].key = \
//商 户 号
p[0].value = \p[1].key = \订 单 号 p[1].value = \p[2].key = \商户日期 p[2].value = \
p[3].key = \商户时间 p[3].value = \
p[4].key = \订单金额 p[4].value = \
p[5].key = \交易类型 p[5].value = \
const char* pfxfile = \const char* passwd = \
const char* cerfile = \
const char* filepath = \
} else {
http://www.ChinaPay.com Chinapay新一代商户接入手册
}
第 28 页 共 35 页
return 0; printf(\
if (decrypt(pfxfile, passwd, enc_buf, enc_len, dec_buf, &dec_len)) { }
printf((char*) dec_buf); printf(\失败\} else {
if (encrypt(cerfile, buff, buff_len, enc_buf, &enc_len)) { }
printf(\解密==========\\n\size_t dec_len = MEM_LEN; unsigned char dec_buf[MEM_LEN]; memset(dec_buf, 0, dec_len);
printf((char*) enc_buf); printf(\失败\} else {
printf(\加密==========\\n\size_t enc_len = MEM_LEN; unsigned char enc_buf[MEM_LEN]; memset(enc_buf, 0, enc_len);
printf(\文件验签==========\\n\if (verifyFile(cerfile, filepath)) { }
printf(\成功\printf(\失败\} else {
printf(\数据验签==========\\n\
if (verify(cerfile, buff, buff_len, sign_buf, sign_len)) { }
printf(\成功\printf(\失败\} else { } else { }
printf(\失败\
http://www.ChinaPay.com Chinapay新一代商户接入手册
4
交易流程说明
4.1 消费类交易流程
个人网银消费
持卡人从商户网站中生成订单信息,通过支付交易平台进行支付的过程,其交易流程包括订单确认、支付处理、支付完成三个部分,具体流程说明如下: 【流程一】订单确认
1. 持卡人浏览商户网站,选择支付项目,生成订单信息。 2. 持卡人确认订单信息,开始支付。 【流程二】支付处理
3. 持卡人确认支付信息,商户网站开始向支付交易平台申请支付,支付交易平台验证商户身份合法性和订单报文的完整性。
4. 支付交易平台向持卡人显示支付机构选择界面,持卡人选择支付机构。
5. 持卡人在所选择支付机构支付页面上,输入用户帐号、密码及其他安全验证信息。 6. 持卡人的安全认证信息得到确认后,进行支付。 【流程三】支付完成
7. 支付机构向支付交易平台返回支付结果。
8. 支付交易平台向持卡人显示支付结果,同时通知商户网站支付结果。 9. 商户网站向持卡人显示商户交易结果。 10.支付操作完成。
企业网银消费
持卡人从商户网站中生成订单信息,通过公共支付交易平台进行支付的过程,其交易流程包括订单确认、支付处理、支付完成三个部分,具体流程说明如下: 【流程一】订单确认
1. 持卡人浏览商户网站,选择支付项目,生成订单信息。 2. 持卡人确认订单信息,开始支付。 【流程二】订单处理
3. 持卡人确认支付信息,商户网站开始向支付交易平台申请支付,支付交易平台验证商户身份合法性和订单报文的完整性。
4. 支付交易平台向持卡人显示支付机构选择界面,持卡人选择支付机构,并提交订单。 5. 持卡人在支付交易平台输入其在对应的支付信息(如:卖方企业客户号、下单员名称)。 6. 持卡人的安全认证信息得到确认后,登录对应支付机构的企业网银账户,确认订单信息,并支付。 【流程三】支付完成
7. 支付机构向支付交易平台返回支付结果。
8. 支付机构向持卡人显示支付结果,同时通知商户网站支付结果。 9. 商户网站向持卡人显示商户交易结果。 10.支付操作完成。 认证支付
持卡人从商户网站中生成订单信息,通过公共支付交易平台进行支付的过程,其交易流程包括订单确
第 29 页 共 35 页
http://www.ChinaPay.com Chinapay新一代商户接入手册
认、支付处理、支付完成三个部分,具体流程说明如下: 【流程一】订单确认
1. 持卡人浏览商户网站,选择支付项目,生成订单信息。 2. 持卡人确认订单信息,开始支付。 【流程二】订单处理
3. 持卡人确认支付信息,商户网站开始向支付交易平台申请支付,支付交易平台验证商户身份合法性和订单报文的完整性。
4. 支付交易平台显示收集支付要素页面信息。
5. 若持卡人未开通UPOP2.0认证支付,需要先开通UPOP2.0认证支付。
6. 持卡人已开通UPOP2.0认证支付,持卡人在支付页面输入卡号信息、短信验证码信息,完成支付。 【流程三】支付完成
7. 支付交易平台向持卡人显示支付结果,同时通知商户网站支付结果。 8. 商户网站向持卡人显示商户交易结果。 9. 支付操作完成。 快捷支付
持卡人从商户网站中生成订单信息,通过公共支付交易平台进行支付的过程,其交易流程包括订单确认、支付处理、支付完成三个部分,具体流程说明如下: 【流程一】订单确认
1. 持卡人浏览商户网站,选择支付项目,生成订单信息。 2. 持卡人确认订单信息,开始支付。 【流程二】订单处理
3. 持卡人确认支付信息,商户网站开始向支付交易平台申请支付,支付交易平台验证商户身份合法性和订单报文的完整性。
4. 持卡人在支付交易平台选择快捷支付。
5. 持卡人输入已注册的账号、支付密码完成快捷支付操作,若未注册快捷支付账户,则需要注册快捷支付账号。
6. 持卡人选择已绑定的快捷支付银行卡,输入短信验证码,完成支付,若未绑定快捷支付银行卡则先绑定快捷支付银行卡。 【流程三】支付完成
7. 支付交易平台向持卡人显示支付结果,同时通知商户网站支付结果。 8. 商户网站向持卡人显示商户交易结果。 9. 支付操作完成。 4.2 后续类交易流程 退款流程:
在支付交易完成之后,商户根据支付交易的结果生成交易退款订单,通过ChinaPay系统进行退款操作,其退款处理流程包括退款确认、退款应答、退款处理、退款完成四个环节,具体流程说明如下: 【流程一】退款确认
1. 商户根据支付交易完成情况,选择退款项目,生成退款订单或者退款账单信息。 2. 商户确认退款信息,开始发起退款交易。 【流程二】退款应答
3. 商户确认退款交易数据,以ChinaPay规范的数据格式向ChinaPay申请退款,ChinaPay证商户合
第 30 页 共 35 页
http://www.ChinaPay.com Chinapay新一代商户接入手册
法性。
4. ChinaPay接受到退款订单后,即时地会返回给商户“退款接收成功”的应答。 【流程三】退款处理
5. ChinaPay与银行之间完成退款操作,其中会有人工干预操作过程,最终会产生退款结果信息。 6. 退款成功/失败应答会在退款处理后通过商户在提交退款信息时所填写的ReturnURL通知给商户。 7. 商户可以在控台上查看退款的进度及退款结果信息。 【流程四】退款完成
8. 退款操作完成。 4.3 查询交易流程
商户根据支付交易明细信息,组合符合ChinaPay规范的查询订单信息,通过ChinaPay系统进行交易明细查询操作,其查询处理流程包括查询确认、查询处理、查询完成三个部分,具体流程说明如下: 【流程一】查询确认
1. 商户形成查询订单信息。
2. 商户确认查询订单信息,该订单信息要符合ChinaPay的规范要求。 【流程二】查询处理
3. 商户确认查询订单后,以ChinaPay规范的数据格式向ChinaPay申请交易明细查询,ChinaPay验证商户合法性。
4. ChinaPay 按照商户信息及提交的查询订单信息进行交易明细查询处理。 【流程三】查询完成
5. ChinaPay服务器端程序在处理完交易明细查询请求之后即时地会返回给商户“查询结果”的应答。
6. 交易明细查询完成 。 4.4 对账处理流程
ChinaPay平台在每日对账完成后,会生成每个商户的对账文件,然后后台通知商户对账文件已经生成,文件的存放地址会在通知的URL地址中传递给商户。商户根据获得的对账文件地址,到该地址上去下载对账文件。
4.5 结算处理流程
ChinaPay平台在每日对账完成后,会生成每个商户的对账文件,然后后台通知商户对账文件已经生成,文件的存放地址会在通知的URL地址中传递给商户。商户根据获得的对账文件地址,到该地址上去下载对账文件。
5 数据类型定义
Ax
x字节定长的字母字符
x字节定长的字母或数字字符
x字节定长的字母、数字或特殊符号字符
第 31 页 共 35 页
Ax..y 长度为x-y字节的变长字母字符 ANx
ANx..y 长度为x-y字节的变长字母或数字字符 ANSx
http://www.ChinaPay.com Chinapay新一代商户接入手册
ANSx..y ASx Nx
长度为x-y字节的变长字母、数字或特殊符号字符 x字节定长的字母或特殊符号字符
x字节定长的整型数值,若表示金额,则以分为单位 x字节定长的数字符或特殊字符 x字节定长的特殊符号字符 秒 日 时 月 分
年(2字节) 年(4字节)
ASx..y 长度为x-y字节的变长字母或特殊符号字符
Nx..y 长度为x-y字节的整型数值,若表示金额,则以分为单位 NSx Sx ss DD hh MM mm YY
特殊符号说明:特殊符号仅限“{”、“}”、“[”、”]”、单引号、双引号、等号、逗号、冒号。
NSx..y 长度为x-y字节的数字字符或特殊字符 Sx..y 长度为x-y字节的变长特殊符号字符
YYYY
6 消费类交易接口
6.1 接入地址
ChinaPay的网上支付服务采用WEB服务的方式允许商户接入,接收交易数据的地址为: ?
测试环境请求地址: 1.
前台交易URL:
http://newpayment-test.chinapay.com/CTITS/service/rest/page/nref/000000000017/0/0/0/0/0 2. /0
说明:测试环境需要配置hosts,见附录A ?
生产环境请求地址: 1.
前台交易URL: 后台交易URL:
http://newpayment-test.chinapay.com/CTITS/service/rest/forward/sta/000000000017/0/0/0/0
https://payment.chinapay.com/CTITS/service/rest/page/nref/000000000017/0/0/0/0/0 2.
后台交易URL:
https://payment.chinapay.com/CTITS/service/rest/forward/sta/000000000017/0/0/0/0/0 说明:
走前台地址的交易:0001个人网银支付、0002企业网银支付、0004快捷支付、0005账单支付、0006认证支付、0007分期付款、0201预授权交易。
走后台地址的交易:0003授信交易。
第 32 页 共 35 页
http://www.ChinaPay.com Chinapay新一代商户接入手册
6.2 请求报文
商户向ChinaPay的支付接入地址提交订单信息,表单采用“post”方式提交,提交页面中表单(FORM)的应该包括如下(注意各字段的大小写,编码方式统一用UTF-8): 字段中文描述 版本号 接入类型 收单机构号 商户号 字 段 Version AccessType AcqCode MerId 是否必填 Y N N Y 长度 AN8 N1 N15 N15 AN1..32 N8 N6 N1..20 备注 固定值:20140728 0:商户身份接入(默认) 1:机构身份接入 ChinaPay分配 由ChinaPay分配的15位定长数字,用于确认商户身份 必填,变长 32位,同一商户同一交易日期内不可重复 商户提交交易的日期,例如交易日期为2015年1月2日,则值为20150102 商户提交交易的时间,例如交易时间10点11分22秒,则值为101122 单位:分 前台页面方式提交交易:商户可以不填此域,ChinaPay会根据商户交易配置在持卡人页面显示商户开通的交易类型,由持卡人选择商户已开通的交易类型完成支付 后台方式提交交易或支付机构号域有值,此域必填 交易类型 TranType N N4 此接口TranType填值范围: 0001个人网银支付 0002企业网银支付 0003授信交易 0004快捷支付 0005账单支付 0006认证支付 0007分期付款 0201预授权交易 业务类型 交易币种 BusiType CurryNo Y N N4 A3 固定值:0001 默认为人民币:CNY 不分账不填写此域; 分账类型 SplitType N N4 如需要分账,填写格式如下: 0001:实时分账 0002:延时分账 分账方式 SplitMethod N N1 订单分账方式 0:按金额分账 商户订单号 MerOrderNo Y 商户交易日期 TranDate Y 商户交易时间 订单金额 TranTime OrderAmt Y Y 第 33 页 共 35 页
http://www.ChinaPay.com Chinapay新一代商户接入手册
1:按比例分账 商户订单分账信息 支付机构号 商户前台通知地址 分账数据,使用规则: MerSplitMsg N ANS0..512 AN15 ANS0..256 商户号^金额或比例;商户号^金额或比例 BankInstNo MerPageUrl N N 取值参见附录C 页面接受应答地址,用于引导使用者支付后返回商户网站页面 商户后台交易应答接收地址,ChinaPay商户后台通知地址 MerBgUrl Y ANS0..256 会根据后台商户响应来判定是否重新发送后台应答流水,以确保后台应答的接收 商品信息 商户私有域 CommodityMsg MerResv N N ANS0..128 用来描述购买商品的信息,ChinaPay原样返回 ANS0..1024 商户自定义,ChinaPay原样返回 交易扩展域,JSON格式填写,如:{\BusiId \P2\。商户自定义使用,商户可根据商户自定义业务字段BusiId来填写P1到P10参数, 系统会存储P1到P10参数数据,可供商户查询使用。 BusiId业务编号ANS0..8 商户根据自身业务情况,由CP分配业务编号,供商户使用,此域可和P1至P10配合使用,可以使P1至P10代表不同的业务含义 P1-P10业务参数ANS0..512 商户自定义使用 商户页面收集卡号的交易必填(如:0003授信交易、0006认证支付、0007分期付款、0008后台消费、0201预授权交易),JSON格式填写,如:{\CertType \ CertNo \CVV2\CardNo \ ANS0..1024 Password \,根据不同交易类型填写不同的卡信息,填写后进行BASE64编码,编码后采用RSA加密。包含字段:CertType、CertNo、CVV2、CardNo、Password、CardValidityPeriod 单位:分钟,以ChinaPay接收交易的N6 时间为准,超过此时间段后用户支付成功的交易,不通知商户,系统自动退款 交易扩展域 TranReserved N ANS0..1024 有卡交易信息域 CardTranData N 支付超时时间 PayTimeOut N 防钓鱼时间戳 TimeStamp N ANS0..20 商户系统时间毫秒数,如商户开户时开通了时间戳防钓鱼校验,ChinaPay系统第 34 页 共 35 页
http://www.ChinaPay.com Chinapay新一代商户接入手册
配置商户系统时间和商户系统时间的时间差(以分钟为单位),如时间超过系统配置的间隔,则会进行防钓鱼提示或拦截交易 客户浏览器端IP,如商户开通校验IP防钓鱼客户浏览器IP 防钓鱼验证,可填写此域做防钓鱼使RemoteAddr N ANS0..128 用。ChinaPay会获取持卡人访问IP和该字段进行比较,如果不一致,则会进行防钓鱼提示或拦截交易 Json格式,填写后进行BASE64编码,编码后采用RSA加密,加密后采用BASE64编码进行传输 MerUserId:商户端用户ID MerRegTime:商户端用户注册时间 MerRegEmail:商户端用户注册邮箱 MerRegMobileNo:商户端用户注册手机风控数据 RiskData N ANS0..1024 号 HDSerialNo:支付时使用的PC 硬盘序列号 Mac: 支付时使用的PC mac地址 IMEI: 支付时使用的手机串号IMEI Coordinate:支付时经纬度信息 BSSerialNo:支付时手机所在基站序列号 SmsFeture:短信验证码输入操作特征 签名 说明: ? ?
BankInstNo为可选项,表示 “支付机构号”,如填写BankInstNo(支付机构号),则消费者将直接进入支付页面,否则进入支付机构选择页面。 请求数据的签名验证
商户发送给ChinaPay的交易数据均需要进行数字签名。对于版本号为20140728的签名数据使用客户端chinapaysecure或SecssUtil进行签名、验签。 6.3 应答报文
当消费支付交易完成时,ChinaPay会将交易应答信息发送给商户,应答的数据域段包括如下内容:(以页面Form数据为例,注意大小写,编码方式统一用UTF-8,后台应答数据的发送的域段名和下面的一致) 字段中文描述 版本号 接入类型 收单机构号 字 段 Version AccessType AcqCode 是否必填 长度 Y N N AN8 N1 N15 备注 固定值:20140728 0:商户身份接入(默认) 1:机构身份接入 ChinaPay分配 Signature Y 商户报文签名信息,报文中的所有字段都参与签名(Signature除外) 第 35 页 共 35 页
http://www.ChinaPay.com Chinapay新一代商户接入手册
商户号 MerId Y N15 AN1..32 N8 N6 N1..20 由ChinaPay分配的15位定长数字,用于确认商户身份 必填,变长 32位,同一商户同一交易日期内不可重复 商户提交交易的日期,例如交易日期为2015年1月2日,则值为20150102 商户提交交易的时间,例如交易时间10点11分22秒,则值为101122 单位:分 此接口TranType填值范围: 0001个人网银支付 0002企业网银支付 0003授信交易 交易类型 TranType Y N4 0004快捷支付 0005账单支付 0006认证支付 0007分期付款 0201预授权交易 业务类型 交易币种 BusiType CurryNo Y N N4 A3 AN4 N4 N1 ANS0..512 AN16 AN8 N8 N8 N6 N1..20 AN15 ANS0..128 固定值:0001 默认为人民币:CNY 0000为支付成功状态,0001为未支付,订单支付状态 OrderStatus Y 其它为失败状态,响应码列表参见附录B 分账类型 分账方式 商户订单分账信息 收单流水号 收单日期 渠道流水号 渠道日期 渠道时间 支付账单号 支付机构号 商品信息 商户私有域 交易扩展域 SplitType SplitMethod N N 原样返回交易请求数据 原样返回交易请求数据 分账数据,使用规则: MerSplitMsg N 商户号^金额或比例;商户号^金额或比例 AcqSeqId AcqDate ChannelSeqId ChannelDate ChannelTime PayBillNo BankInstNo CommodityMsg MerResv TranReserved N N N N N N N Y N N ChinaPay收单系统交易受理流水号 ChinaPay系统收单交易受理日期,格式:YYYYMMDD 支付渠道返回给ChinaPay的订单号 支付渠道返回给ChinaPay的交易日期 支付渠道返回给ChinaPay的交易时间 交易类型为账单支付时,下单时返回给商户的账单号 取值参见附录C 用来描述购买商品的信息,ChinaPay原样返回 商户订单号 MerOrderNo Y 商户交易日期 TranDate Y 商户交易时间 订单金额 TranTime OrderAmt Y Y ANS0..1024 商户自定义,ChinaPay原样返回 ANS0..1024 交易扩展域,JSON格式填写,商户交易请求内容原样返回 第 36 页 共 35 页
http://www.ChinaPay.com Chinapay新一代商户接入手册
有卡交易必填,JSON格式,根据不同交有卡交易信息域 CardTranData N ANS0..1024 易类型填写不同的卡信息;填写后采用RSA加密 单位:分钟,以ChinaPay接收交易的支付超时时间 PayTimeOut N N6 时间为准,超过此时间段后用户支付成功的交易,不通知商户,系统自动退款 商户系统时间毫秒数,如商户开户时开通了时间戳防钓鱼校验,ChinaPay系统防钓鱼时间戳 TimeStamp N ANS0..20 配置商户系统时间和商户系统时间的时间差(以分钟为单位),如时间超过系统配置的间隔,则会进行防钓鱼提示或拦截交易 客户浏览器端IP,如商户开通校验IP防钓鱼客户浏览器IP 防钓鱼验证,可填写此域做防钓鱼使RemoteAddr N ANS0..128 用。ChinaPay会获取持卡人访问IP和该字段进行比较,如果不一致,则会进行防钓鱼提示或拦截交易 订单完成日期 CompleteDate N N8 N6 YYYYMMDD,支付完成后,ChinaPay返回支付完成日期 hhmmss,支付完成后,ChinaPay返回支付完成时间 商户报文签名信息,报文中的所有字段都参与签名(Signature除外) 订单完成时间 CompleteTime N 签名 说明: ?
Signature Y 应答数据的签名验证
支付交易完成后,支付应答会分前台页面跳转和后台Http通知方式返回给商户,商户需要对ChinaPay
返回报文签名进行验签,以确定此报文是由ChinaPay发出。
注:
后台返回字段需要通过urldecode进行解码后还原原始报文,前台返回报文无需此操作。 JAVA解码方法:URLDecoder.decode(value, \PHP解码方法:urldecode(value)
.NET解码方法:HttpUtility.UrlDecode(value,\
7 后续类交易接口
后续类交易主要是指对已发生的交易,做后续的相关的交易处理;包括:退款、退款撤销、退款重汇、消费撤销、预授权撤销、预授权完成撤销、预授权完成、通知分账。退款的相关操作也可以在企业门户系统中进行操作,但是商户只能选择一种方式进行操作。 7.1 接入地址
ChinaPay的网上支付服务采用WEB服务的方式允许商户接入,其中: ?
0401退款、0402退款撤销、0409退款重汇、9908通知分账的交易接收地址如下:
第 37 页 共 35 页
http://www.ChinaPay.com Chinapay新一代商户接入手册
?
测试环境请求地址:
http://newpayment-test.chinapay.com/CTITS/service/rest/forward/syn/000000000065/0/0/0/0/0 ?
生产环境请求地址:
https://payment.chinapay.com/CTITS/service/rest/forward/syn/000000000065/0/0/0/0/0 ? ?
0403消费撤销、0203预授权撤销、0204预授权完成撤销、0202预授权完成的交易接收地址如下:
测试环境请求地址:
http://newpayment-test.chinapay.com/CTITS/service/rest/page/nref/000000000017/0/0/0/0/0
? 生产环境请求地址:
https://payment.chinapay.com/CTITS/service/rest/page/nref/000000000017/0/0/0/0/0
7.2 请求报文
商户向ChinaPay的交易平台提交订单,表单采用“post”方式提交,提交页面中表单(FORM)的应该包括如下(注意各字段的大小写,编码方式统一用UTF-8): 字段中文描述 版本号 接入类型 收单机构号 商户号 商户订单号 商户交易日期 字 段 Version AccessType AcqCode MerId MerOrderNo TranDate 是否必填 长度 Y N N Y Y Y AN8 N1 N15 N15 AN1..32 N8 N6 AN1..32 N8 备注 固定值:20140728 0:商户身份接入(默认) 1:机构身份接入 ChinaPay分配 由ChinaPay分配的15位定长数字,用于确认商户身份 退款订单号 商户提交交易的日期,例如交易日期为2015年1月2日,则值为20150102 商户提交交易的时间,例如交易时间10点11分22秒,则值为101122 原始交易订单号 商户原始支付交易日期 单位:分 当TranType=0401退款交易时 退款金额 RefundAmt N N1..20 RefundAmt必填 当TranType为其他值时,交易时不能传RefundAmt 单位:分 当TranType=0202或9908时,OrderAmt订单金额 OrderAmt N N1..20 必填 当TranType为其他值,交易时不能传OrderAmt 交易类型 TranType Y N4 第 38 页 共 35 页
此接口TranType填值范围: 商户交易时间 商户交易订单号 原始商户交易日期 TranTime OriOrderNo OriTranDate Y Y Y
http://www.ChinaPay.com Chinapay新一代商户接入手册
0403消费撤销 0401退款交易 0202预授权完成 0203预授权撤销 0204预授权完成撤销 0402 退款撤销 0409 退款重汇 9908 通知分账 业务类型 BusiType Y N4 固定值:0001 商户后台交易应答接收地址,ChinaPay商户后台通知地址 MerBgUrl N ANS0..256 会根据后台商户响应来判定是否重新发送后台应答流水,以确保后台应答的接收 交易币种 CurryNo N A3 默认为人民币:CNY 不分账不填写此域; 如需要分账,填写格式如下: 分账类型 SplitType N N4 0001:实时分账 0002:延时分账 分账交易退款,此字段传0001 订单分账方式 分账方式 SplitMethod N N1 0:按金额分账 1:按比例分账 商户订单分账信息 商户私有域 分账数据,使用规则: MerSplitMsg N ANS0..512 商户号^金额或比例;商户号^金额或比例 MerResv N ANS0..1024 商户自定义,ChinaPay原样返回 交易扩展域,JSON格式填写,如:{\BusiId \P2\。商户自定义使用,商户可根据商户自定义业务字段BusiId来填写P1到P10参数, 系统会存储P1到P10参数数据,可供商户交易扩展域 TranReserved N ANS0..1024 查询使用。 BusiId业务编号ANS0..8 商户根据自身业务情况,由CP分配业务编号,供商户使用,此域可和P1至P10配合使用,可以使P1至P10代表不同的业务含义 P1-P10业务参数ANS0..512 商户自定义使用 签名 说明:
第 39 页 共 35 页
Signature Y 商户报文签名信息,报文中的所有字段都参与签名(Signature除外)
http://www.ChinaPay.com Chinapay新一代商户接入手册
?
交易数据的数字签名
商户发送给ChinaPay的交易数据均需要进行数字签名。对于版本号为20140728的签名数据使用客户端chinapaysecure或SecssUtil进行签名、验签。 7.3 同步响应
对于0401退款、0402退款撤销、0409退款重汇、9908通知分账的交易,当ChinaPay交易平台接收商户提交的订单后,会返回商户同步处理结果。包括如下(响应数据以key=value形式,用”&”符号分隔): 字段中文描述 字 段 是否必填 长度 备注 0000:成功 响应码 respCode Y AN4 1003:商户已审核 其他为失败。 响应码描述 签名 说明: ?
交易数据的数字签名
ChinaPay返回给商户同步应答时,会对响应码、响应码描述进行签名,商户需要进行验签。 7.4 应答报文
当ChinaPay交易平台处理完成时,ChinaPay会将订单信息发送给商户,应答的数据域段包括如下内容:(以页面Form数据为例,注意大小写,编码方式统一用UTF-8,后台应答数据的发送的域段名和下面的一致) 字段中文描述 版本号 接入类型 收单机构号 商户号 商户订单号 商户交易日期 商户交易时间 商户交易订单号 原始商户交易日期 退款金额 字 段 Version AccessType AcqCode MerId MerOrderNo TranDate TranTime OriOrderNo OriTranDate 是否必填 长度 Y N N Y N Y Y Y Y AN8 N1 N15 N15 AN1..32 N8 N6 AN1..32 N8 N1..20 N1..20 N4 N4 A3 第 40 页 共 35 页
备注 固定值:20140728 0:商户身份接入(默认) 1:机构身份接入 ChinaPay分配 由ChinaPay分配的15位定长数字,用于确认商户身份 退款订单号 年月日 时分秒 原始交易订单号 商户原始支付交易日期 单位:分 当TranType=0401退款交易时返回 单位:分 当TranType=0202预授权完成时返回 0401 0001 默认为人民币:CNY respMsg Signature Y Y ANS0..128 响应码描述 商户报文签名信息,respCode+respMsg的签名 RefundAmt N 订单金额 交易类型 业务类型 交易币种 OrderAmt TranType BusiType CurryNo N Y Y N
正在阅读:
新一代商户接入手册V2.704-30
霸王珠作文300字07-10
施工组织设计(辛庄)07-04
法庭审判法官言语行为研究01-07
无锡市中考英语试卷及答案解析审批稿08-07
建筑设计企业质量管理体系表格04-29
人教版语文四年级下册看拼音写词语田字格04-08
XXX同志在南关街道基层党组织和党员深入开展创先争优、强堡垒做先锋活动部署会上的讲话09-15
作文指导六景物06-17
- 多层物业服务方案
- (审判实务)习惯法与少数民族地区民间纠纷解决问题(孙 潋)
- 人教版新课标六年级下册语文全册教案
- 词语打卡
- photoshop实习报告
- 钢结构设计原理综合测试2
- 2014年期末练习题
- 高中数学中的逆向思维解题方法探讨
- 名师原创 全国通用2014-2015学年高二寒假作业 政治(一)Word版
- 北航《建筑结构检测鉴定与加固》在线作业三
- XX县卫生监督所工程建设项目可行性研究报告
- 小学四年级观察作文经典评语
- 浅谈110KV变电站电气一次设计-程泉焱(1)
- 安全员考试题库
- 国家电网公司变电运维管理规定(试行)
- 义务教育课程标准稿征求意见提纲
- 教学秘书面试技巧
- 钢结构工程施工组织设计
- 水利工程概论论文
- 09届九年级数学第四次模拟试卷
- 商户
- 接入
- 新一代
- 手册
- 2.7
- 质量管理的常用工具与手法(含试题及答案) - 图文
- 51单片机RC522射频卡驱动
- 浅谈船检质量管理体系的建立与运行11
- 机械设计基础-习题解答
- 高二物理:7电路分析和多用表
- 新视野大学英语1教案U4
- 资格认证小抄知识点证券从业资格考试《证券交易》重难点(考试必
- 基于KPI卓越绩效管理体系建设
- 人教版小学四年级数学下册全册教案 - (1)
- 学前教育巡回支教申请
- 2015年比武 矿井维修钳工、机修钳工、车工大纲要点
- 2018秋人教版语文八上第21课《桃花源记》练习题
- 美国高中留学的好处有哪几方面
- 现代切削加工技术与刀具习题答案
- MATLAB课程论文
- 垃圾填埋场监理规划
- PDMS管道建模操作心得
- 食用香料香精产品生产许可实施细则(2008) - 图文
- 《C++程序设计》实验指导书(2)
- 让语言文字之花开遍城南校园--语言文字规范示范校汇报材料