ChinaPay收付捷平台 - 单笔代付接口文档V2.1

http://www.chinapay.com

ChinaPay收付捷平台

单笔代付接口文档

（Version: 2.1）

上海银联电子支付服务有限公司

地址：上海浦东新区东方路800号 宝安大厦29楼-30楼 (200122)

Tel: (86-021)60872088 Fax: (86-021)60872000Website: http://www.ChinaPay.com

?Copyright 2014 ChinaPay e-Payment Service Co.,Ltd. All rights reserved

第 1 页 共 36 页

http://www.chinapay.com

第 2 页 共 36 页

http://www.chinapay.com

修订历史记录

日期 版本 说明 修改代付版本，将代付交易接口中的交易模式字2016-05-30 V2.1 段由非必填改为必填 修改代付版本，备付金明细查询接口应答报文的2016-05-20 V2.0 note字段增加到50位长 2016-02-03 2015-12-17 V1.9 V1.8 修改代付版本，增加多个风险监控字段 增加6.2章节-测试环境相关说明 修改代付版本，增加代付交易接口中交易模式字2015-12-08 V1.7 段 修改代付版本，增加代付交易接口中渠道类型字2015-05-13 V1.6 段 2015-04-08 V1.5 耿翔 张学媛 张学媛 张学媛 张学媛 张学媛 作者 purpose字段长度增加到99位 张胜 2014-04-28 V1.4 修改备付金明细查询汇总行描述 耿翔 2014-02-14 V1.3 统一修改文档名称 1.补充代付交易处理逻辑及交易状态的说明 耿翔 2013-12-13 V1.2 2.补充3.4超时时间设定及3.5章节域长度计算说明 3.文档更名为“收付捷平台_单笔代付接口文档” 耿翔 2013-02-22 V1.10 修改代付各接口提交地址 1.修改各接口返回报文chkValue值说明 2.补充备付金余额查询接口返回数据code说明 耿翔 2012-04-05 V1.09 黄旭婷

第 3 页 共 36 页

http://www.chinapay.com

2012-02-09 V1.08 补充批量退单查询接口和备付金明细查询接口返回报文验签示例 更新附录中代付银行列表内容 1.修改批量退单查询接口退单日期的查询范围 2.增加批量退单查询接口验签方法说明 1.修改对chkValue的描述 黄旭婷 2011-12-30 V1.07 黄旭婷 2011-12-07 V1.06 黄旭婷 2011-11-23 V1.05 2.修改字段usrName长度为变长60位 3.附录中加入代付银行列表 文档接口改造 1.调整框架 余珊珊 2011-10-15 V1.04 2.修改NetPayClient for Java使用说明 3.商户提交表单中加入signFlag的字段，调整签名方法说明 余珊珊 2010-05-10 V1.03 1.增加windows版本的api的描述 2.修改单笔查询的例子 1.增加备付金明细查询接口 2.交易接口增加b2b代付标志 增加备付金余额查询接口 创建接口文档初稿 钱斌 2009-10-19 2009-05-14 2009-04-21 V1.02 V1.01 V1.0 钱斌 钱斌 钱斌

第 4 页 共 36 页

http://www.chinapay.com

目录

1. 概述 ............................................................................................................................................. 7 2. 适用范围 ..................................................................................................................................... 7 3. 对接口的统一说明...................................................................................................................... 7

3.1. 参数 .................................................................................................................................. 7 3.2. 调用方式 .......................................................................................................................... 7 3.3. IP限制 .............................................................................................................................. 7 3.4. 超时时间设定 .................................................................................................................. 7 3.5. 单位说明 .......................................................................................................................... 7 3.6. 域长度计算说明 .............................................................................................................. 8 4. 总述 ............................................................................................................................................. 8

4.1. 使用对象 .......................................................................................................................... 8 4.2. 运行及开发环境 .............................................................................................................. 8 4.3. 术语 .................................................................................................................................. 8 4.4. NetPayClient在各系统下的安装及调用 ......................................................................... 8

4.4.1. NetPayClient for Java 使用说明............................................................................ 9 4.4.2. NetPayClient for Win32使用说明 ....................................................................... 11 4.4.3. NetPayClient for C#使用说明 .............................................................................. 15 4.4.4. NetPayClient for PHP使用说明 .......................................................................... 17

5 ...................................................................................................................................................... 17 6 ...................................................................................................................................................... 17

6 .............................................................................................................................................. 17 6 .............................................................................................................................................. 17 6 .............................................................................................................................................. 17 6 .............................................................................................................................................. 17 6 .............................................................................................................................................. 17

6.5.1. .............................................................................................................................. 17 6.5.2. .............................................................................................................................. 17 6.5.3. .............................................................................................................................. 17 6.5.4. .............................................................................................................................. 17 6.5.5. .............................................................................................................................. 17

5.接口描述...................................................................................................................................... 20

5.1.交易接口 ........................................................................................................................... 20

5.1.1.代付交易处理流程 ................................................................................................ 20 5.1.2.建议商户交易处理流程 ........................................................................................ 21 5.1.3.概要说明 ................................................................................................................ 21 5.1.4.请求数据示例 ........................................................................................................ 21 5.1.5.请求url .................................................................................................................. 22 5.1.6.商户端提交的数据内容 ........................................................................................ 22 5.1.7.cp应答数据描述 ................................................................................................... 26 5.2.单笔查询接口 ................................................................................................................... 27

5.2.1.概要说明 ................................................................................................................ 27 5.2.2.请求数据示例 ........................................................................................................ 27

第 5 页 共 36 页

http://www.chinapay.com

5.2.3.请求url .................................................................................................................. 27 5.2.4.商户端提交的数据内容 ........................................................................................ 28 5.2.5.cp返回的数据内容 ............................................................................................... 28 5.3.批量退单查询接口 ........................................................................................................... 30

5.3.1.概要说明 ................................................................................................................ 30 5.3.2.请求数据示例 ........................................................................................................ 30 5.3.3.请求url .................................................................................................................. 30 5.3.4.商户端提交的数据内容 ........................................................................................ 31 5.3.5.cp返回的查询结果 ............................................................................................... 31 5.4.备付金余额查询接口 ....................................................................................................... 33

5.4.1.概要说明 ................................................................................................................ 33 5.4.2.请求数据示例 ........................................................................................................ 33 5.4.3.请求url .................................................................................................................. 34 5.4.4.商户端提交的数据内容 ........................................................................................ 34 5.4.5.cp返回的数据内容 ............................................................................................... 34 5.5.备付金明细查询接口 ....................................................................................................... 35

5.5.1.概要说明 ................................................................................................................ 35 5.5.2.请求数据示例 ........................................................................................................ 35 5.5.3.请求url .................................................................................................................. 35 5.5.4.商户端提交的数据内容 ........................................................................................ 35 5.5.5.cp返回的查询结果 ............................................................................................... 36

6.附录 ............................................................................................................................................. 38

6.1.代码表 ............................................................................................................................... 38

6.1.1.请求响应码(responseCode)表 ............................................................................... 38 6.1.2.交易状态码（stat）表 .......................................................................................... 38 6.2.测试环境相关说明 ........................................................................................................... 39

6.2.1.奇偶数规则 ............................................................................................................ 39 6.2.2.测试卡要求 ............................................................................................................ 39

第 6 页 共 36 页

http://www.chinapay.com

1. 概述

本文档对商户采用单笔模式接入收付捷平台的代付通信接口进行了详细的描述，商户端程序如需要进行开发可以此文档为依据。

2. 适用范围

通过单笔接口模式接入银联电子支付收付捷平台的代付商户。

3. 对接口的统一说明

3.1. 参数

接口传输的所有参数（特别是一些中文，非ASCII字符集字符）都使用GBK进行编

码，包括签名、验签。

3.2. 调用方式

接口采用http/https连接方式进行通讯，接口提供的签名验签API是在客户端直接调用。

3.3. IP限制

允许对接口的请求IP进行限制。代付商户在开通时可以向ChinaPay提供一个或者多个固定IP用于做交易和查询。

3.4. 超时时间设定

商户接收ChinaPay接口应答的超时时间不得少于60s。

3.5. 单位说明

接口中所有交易金额和手续费的货币种类均为人民币，并采用“分”为单位。

第 7 页 共 36 页

http://www.chinapay.com

3.6. 域长度计算说明

所有参数的长度均以字节为单位，每个中文汉字占两个字节，每个英文字母、字符或数字占一个字节。

4. 总述 4.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.2. 运行及开发环境

商户可根据自己的实际情况，选用合适的开发平台和运行平台。ChinaPay将提供对应的版本的签名、验签插件（NetPayClient）。目前ChinaPay签名、验签主要支持的开发语言有JAVA、ASP、C#、PHP。

4.3. 术语

商户具有电子商务功能的商店和企业。

持卡人银行卡的拥有者。

开户行指持卡人卡账户或企业资金账户所在的商业银行。

4.4. NetPayClient在各系统下的安装及调用

NetPayClient是一个安装在ChinaPay商户会员侧的应用编程接口函数库（API LIB）。 它与商户网上柜面系统相集成，实现消费者、商户和银行间的网上安全支付。提供如下功能：

商户对订单关键信息进行数字签名 商户验证ChinaPay发送的交易应答 商户对一段字符串的签名

第 8 页 共 36 页

http://www.chinapay.com

商户对一段字符串的签名验证

4.4.1. NetPayClient for Java 使用说明 4.4.1.1核心文件清单

名 称 MerPrk.key PgPubk.key 放置的路径 可以放置到任意路径下，但是需要调用方法指定文件位置和名称 可以放置到任意路径下，但是需要调用方法指定文件位置和名称 用 途 用于提供数字签名的方法调用 商户签名私钥 ChinaPay签名公钥 netpayclinet.jar 根据项目工程的需要放置对应路径下 4.4.1.2方法说明

创建公/私钥对象buildKey

方法说明：

public booleanbuildKey (String MerId, int KeyUsage, String KeyFile) 作用：

用于创建私/公钥的对象，用于签名或者验证签名。 参数说明：

String MerId 商户号，长度为15个字节的数字串，由ChinaPay分配。 int KeyUsage 使用私/公钥的方式，固定为 0 。

String KeyFile私/公钥的文件路径（包含文件名称）。例如：\MerPrk.key” 返回值：

true 表示找到正确的私/公钥文件,并且可以调用签名方法签名或者签名验证方法验证签名， false 表示创建私/公钥对象失败，不可以使用签名方法和签名验证方法。 注：该方法在类chinapay. PrivateKey中。

对一段字符串的签名函数Sign

方法说明：

public String Sign (String SignMsg) 作用：

对传入的参数字符串进行数字签名。 参数说明：

String SignMsg 用于要签名的字符串 返回值：

String CheckValue[256]即NetPayClient根据上述输入参数生成的商户数字签名，长度为256字节的 字符串。

注：该方法在类chinapay. SecureLink中。

第 9 页 共 36 页

http://www.chinapay.com

对一段字符串的签名验证函数verifyAuthToken

方法说明：

public boolean verifyAuthToken (StringPlainData, String CheckValue) 作用：

验证目标字符串的数字签名是否正确。 参数说明：

String PlainData 用于数字签名的字符串。

String CheckValue 校验值，要验证的字符串的数字签名，长度为256字节的字符串。 返回值：

true 表示验证通过成功；否则表示失败。 注：该方法在类chinapay. SecureLink中。

4.4.1.3使用示例代码

（以下代码未经测试，仅供参考）

签名示例代码

//初始化key文件：

chinapay.PrivateKey key=new chinapay.PrivateKey(); boolean flag1; String msg,priKeyPath;

msg = merId+ merDate + merSeqId +cardNo +usrName+openBank

+prov +city +transAmt+purpose+subBank+flag+version ;

System.out.println(\要签名的数据:\

// 将要签名的数据传给msg

//对签名的数据进行Base64编码

String msg1 = new String(Base64.encode(msg.toString().getBytes()));

System.out.println(\要签名的数据进行Base64编码后为:\flag1=key.buildKey(merId,0,\

if (flag1==false)

{

System.out.println(\ return; }

//签名

chkValue = s.Sign(msg1);

System.out.println(\时签名内容:\

}

SecureLink s = new SecureLink(key);

第 10 页 共 36 页

http://www.chinapay.com

对一段字符串的签名函数Sign

方法说明：

public String Sign (String SignMsg) 作用：

对传入的参数字符串进行数字签名。 参数说明：

String SignMsg 用于要签名的字符串 返回值：

String CheckValue[256]即NetPayClient根据上述输入参数生成的商户数字签名，长度为256字节的 字符串。

注：该方法在netpay.NETPAY中。

对一段字符串的签名验证函数verifyAuthToken

方法说明：

public boolean verifyAuthToken (StringPlainData, String CheckValue) 作用：

验证目标字符串的数字签名是否正确。 参数说明：

String PlainData 用于数字签名的字符串。

String CheckValue 校验值，要验证的字符串的数字签名，长度为256字节的字符串。 返回值：

true 表示验证通过成功；否则表示失败。 注：该方法在netpay.NETPAY中。

4.4.3.4使用示例代码

（以下代码未经测试，仅供参考） 签名示例代码

string MerId, OrdId, TransAmt, CuryId, TransDate, TransType,ChkValue; string plainData, ChkValue2 ;

//初始化key文件：

if (NetPay.NETPAY.buildKey(\{

showInfo(\设置私钥：成功。\\r\\n\\r\\n\}

// 对一段字符串的签名

string plainData = \if (NetPay.NETPAY.PrivateKeyFlag) {

string ChkValue2 = NetPay.NETPAY. Sign(plainData); showInfo(\明文：\

showInfo(\密文：\

第 16 页 共 36 页

http://www.chinapay.com

}

验证签名示例代码

String MerId, OrdId, TransAmt, CuryId, TransDate, TransType,ChkValue; String plainData, ChkValue2 //初始化key文件：

if (NetPay.NETPAY.buildKey(\{

showInfo(\设置公钥：成功。\\r\\n\\r\\n\}

// 对一段字符串的签名验证 plainData = \

if (NetPay.NETPAY.PublicKeyFlag) {

bool result = NetPay.NETPAY.verifyAuthToken(plainData, ChkValue2); // ChkValue2为ChinaPay应答传回的域段

showInfo(\明文：\showInfo(\密文：\showInfo(\验签：\if(!flag) { //签名验证错误处理 } }

4.4.4. NetPayClient for PHP使用说明

4.4.4.1核心文件清单

名 称 netpayclient.php MerPrk.key PgPubk.key 所在的路径 用户自己决定放置位置 可以放置到任意路径下，但是需要调用方法指定文件位置和名称 可以放置到任意路径下，但是需要调用方法指定文件位置和名称 用 途 签名数据和验证签名的主体方法库 商户签名私钥 ChinaPay签名公钥

第 17 页 共 36 页

http://www.chinapay.com

4.4.4.2方法说明

创建公/私钥对象buildKey

方法说明：

function buildKey ($keyfile) 作用：

用于创建私/公钥的对象，用于签名或者验证签名。 参数说明：

$keyfile私/公钥的文件路径（包含文件名称）。例如：\MerPrk.key”, 支持相对路径。 返回值：

如创建成功，返回15位长的商户号，如失败返回false。

对一段字符串的签名函数sign

方法说明： function sign ($msg) 作用：

对传入的参数字符串进行数字签名。 参数说明：

$msg 用于要签名的字符串 返回值：

NetPayClient根据上述输入参数生成的商户数字签名，长度为256字节的字符串。

对一段字符串的签名验证函数verify

方法说明：

function verify ($plain, $checkvalue) 作用：

验证目标字符串的数字签名是否正确。 参数说明： $plain 返回值：

true 表示验证通过成功；否则表示失败。

用于数字签名的字符串。

$checkvalue校验值，要验证的字符串的数字签名，长度为256字节的字符串。

4.4.4.3使用示例代码

? 签名示例代码

（以下代码未经测试，仅供参考）

include_once(\

$merid = buildKey(“MerPrk.key”); if(!$merid) {

第 18 页 共 36 页

http://www.chinapay.com

?>

}

$ordid = \$transamt = padstr('1',12); $curyid = \$transdate = date('Ymd'); $transtype = \$version = \

$pagereturl = \$bgreturl = \

$chkvalue = sign($merid, $ordid, $transamt, $curyid, $transdate, $transtype); //对一段字符串的签名 $chkvalue = sign($plain); if (!$chkvalue) { }

echo \签名失败！\exit;

echo \导入私钥文件失败！\exit;

? 验证签名示例代码

（以下代码未经测试，仅供参考）

include_once(\

$flag = buildKey(“PgPubk.key”); if(!$flag) { }

$merid = $_REQUEST[\$orderno = $_REQUEST[\$transdate = $_REQUEST[\$amount = $_REQUEST[\

$currencycode = $_REQUEST[\$transtype = $_REQUEST[\$status = $_REQUEST[\

$checkvalue = $_REQUEST[\$gateId = $_REQUEST[\$priv1 = $_REQUEST[\

第 19 页 共 36 页

echo \导入公钥文件失败！\exit;

http://www.chinapay.com

$flag = verifyTransResponse($merid, $orderno, $amount, $currencycode, $transdate, $transtype,

$status, $checkvalue);

$flag = verify($plain, $checkvalue); if(!flag) { echo \验证签名失败！\ exit;

}

?>

5.接口描述 5.1.交易接口

5.1.1.代付交易处理流程

第 20 页 共 36 页

http://www.chinapay.com

2. fromDate 开始日期 数字 定长，8位 必填 查询起始日期，仅能查询最近一个月的数据 3. toDate 4. type 结束日期 数字 定长，8位 查询类别 数字 定长，2位 必填 查询结束日期。 必填 查询类别。 00：直接划入 01：网上支付结算款划入 02：转出 5. version 6. signFlag 7. chkValue 版本号 数字 变长，8位 必填 固定为“20160530” 必填 固定为“1” 签名标志 字符 定长，1位 签名值 字符 定长，256位 必填 签名字段,具体见下方。 chkValue 为签名数据, 将参与签名的字段内容按顺序连接起来，组成一个签名字符串明文，对该签名字符串进行BASE64编码，再调用NetPayClient提供的签名方法，对BASE64编码后的字符串进行签名。参与签名的字段及顺序为: merId + fromDate +toDate +type + version

5.5.5.cp返回的查询结果

cp返回一个字符串，第一行为汇总信息，元素有：应答码（000：成功，001：无记录。002：查询出错。），总笔数，总金额，用‘|’分隔。第二至第n行为具体记录，每条记录带有如下信息，每个信息字段用‘|’分隔。在整个记录的最后一行，有对整个文件的签名信息，附在最后一行的结尾。

信息字段如下： No 字段名称 项目描述 商户号 交易日期 类别 格式 长度 说明 商户在收付捷平台中的唯一id 标志该笔交易发生的日期 查询类别。 00：直接划入 01：结算款划入 02：转出 4. transAmt 金额 数字 变长，12位 发生金额 1. merId 2. cpDate 3. type 数字 定长，15位 数字 定长，8位 数字 定长，2位

第 36 页 共 36 页

http://www.chinapay.com

5. note 6. chkValue 说明 签名值 字符 变长，50位 操作说明 字符 定长，256位 除了报文尾部的256位以上的都是作为签名的明文。明文需进行BASE64编码，具体见下方。y 返回报文示例：

●查询成功返回报文： 000|4|200000002

606060103099001|20100402|00|100000000| 606060103099001|20100402|00|1|swk 606060103099001|20100402|00|100000000|

606060103099001|20100402|00|1|swk2730274788A4F183B9C7C25957327A7DA9C0A4F9C15D494120D083DA384FB7B32BDC6F3EAE7AB5710D61EAAAB8A8291919C78FA27746CEE62CD5539777EEB40724E28A75D651705328019B5B381123543479AC03831B5D1ABF97B14A9DEF3718F167B92D4A2141E638E9645B05F523AD92F992C80CF858F449730A371B244B36需要验签的字段： 000|4|200000002

606060103099001|20100402|00|100000000| 606060103099001|20100402|00|1|swk

606060103099001|20100402|00|100000000| 606060103099001|20100402|00|1|swk

●查询无记录返回报文

001||C59173CCE0C661785FFED1ED728E379C55B6AC0407852B0B049D2EC03831C5B2A0D05D8EEFD429CC69E2C9EE2E30CFC4A21296F740B79AB6BC11E2101B3DC3E7F6C125317138A04B8C287747059979867AABFC12D9D41581C1636952361968150AE4D8119AFB67B3D635018EC775968EDF58DA29D1D1B159B0450BCA06049637

需要验签的字段：001||

●查询出错返回报文

002||8B8BAEAD10A96041854770CDEDAE7803E5708B94DC52C0DE73B694EEEB84E4666556FF7DCD900403B31E5DC1CC774819877297142A9C19ECB78067690A8E9855557E2C8D1CB00CB73380E2C7276A2F83AB49E2B99198E23A5513AAAC6F52E21635D4118FB63D51F1CCF4E2ACD9B9336037B69483B2507985D9EB7E284802A2B9

需要验签的字段：002||

第 37 页 共 36 页

http://www.chinapay.com

6.附录 6.1.代码表

6.1.1.请求响应码(responseCode)表

响应码 0000 0100 0101 0102 0103 0104 0105 接收状态 接收成功 接收失败 提交成功 描述 商户提交的字段长度、格式错误 商户验签错误 手续费计算出错 商户备付金帐户金额不足 操作拒绝 待查询 重复交易 6.1.2.交易状态码（stat）表

状态码 s 2 3 4 5 交易状态 成功 处理中 处理中 处理中 处理中 含义 交易成功 交易已接受 财务已确认 财务处理中 已发往银行 状态码为小写字母s 描述 ChinaPay已将代付交易发往银行。后续若银行返回结果，该状态会相应更新。 6 7 8 失败 处理中 处理中 银行已退单 重汇已提交 重汇已发送 银行退单，交易失败。 ChinaPay已将代付交易发往银行。后续若银行返回结果，该状态会相应更新。

第 38 页 共 36 页

http://www.chinapay.com

9 失败 重汇已退单 银行对重汇的代付交易退单，交易失败。 6.2.测试环境相关说明

6.2.1.奇偶数规则

我司测试环境单笔代付的奇偶数规则为：

对于代付来说，当交易金额小于5万元且为对私代付时， 交易金额为奇数返回0000&S的成功应答，交易金额为偶数返回0104&6的失败应答。同时我司交易金额是以分为单位的。 对于代付来说，当交易金额大于5万元或为对公代付时，交易发过来都是处理中，需由我处手动改交易状态。贵司若要改交易状态，请回邮告知商户号+流水号+交易日期+需要更新的交易状态，由我处手动为贵司操作。

6.2.2.测试卡要求

单笔代付测试卡要求卡前6位与真实银联卡前6位相同即可，其余卡号信息可自行编写。

第 39 页 共 36 页

http://www.chinapay.com

5.1.2.建议商户交易处理流程

1、商户向CP发起代付请求，CP同步向商户返回交易应答。 2、商户若收到应答，先对CP返回的数据进行验签；进入步骤3

若接收应答超时，请商户调用单笔查询接口查询订单状态和处理结果。 3、商户验签通过后，先判定responseCode

a）若responseCode的接收状态为“接收成功”，表示ChinaPay系统已接收商户代付交易请求；进入步骤4

b）若responseCode的接收状态为“接收失败”，表示ChinaPay系统接收商户代付请求失败；

c）若responseCode的接收状态为“待查询”，需调用单笔查询接口查询订单状态和处理结果；

d）其余应答，需调用单笔查询接口查询订单状态和处理结果； 4、商户判定交易状态stat a）若stat为明确的成功/失败结果，商户记录订单结果，并进行后续处理。 b）stat没有返回明确的成功/失败结果，表示代付处理中，后续需要通过查询订单状态；部分银行无法返回明确的回盘结果，可通过批量退单查询/控台查询等方式获取结果。

5.1.3.概要说明

该接口定义商户交易的数据传输，商户通过该接口进行交易。接口基于http post方式提交交易参数和数字签名，收付捷平台处理完毕后，通过http同步应答方式返回带签名的处理结果。

5.1.4.请求数据示例

5.1.5.请求url

生产：http://sfj.chinapay.com/dac/SinPayServletGBK（支持https） 测试：http://sfj-test.chinapay.com/dac/SinPayServletGBK

5.1.6.商户端提交的数据内容

No 字段名称 字段描述 1 merId 格式 长度 出现要求 在收付捷平台中开通的商户编号 说明 商户号 数字 定长，必填 15位 2 merDate 商户日期 数字 定长，必填 8位 标志该笔交易发生的日期,格式为YYYYMMDD，请填写当天的日期。

第 22 页 共 36 页

http://www.chinapay.com

3 merSeqId 商户流水号 数字 变长，必填 16位 数字 变长，必填 32位 字符 变长，必填 100位 商户号+商户流水号+商户日期唯一标示一笔交易订单 银行卡号或者存折号 4 cardNo 收款账号 5 usrName 收款人姓名 收款人在银行开户时留存的开户姓名 6 certType 收款人证件类型 字符 定长，非必填 身份证01； 军官证02 ； 2位 护照03 ； 户口簿04 ； 回乡证05 ； 其他06； 7 certId 收款人证件号 字符 变长，非必填 收款人在银行开户时留存的开户25位 字符 变长，必填 50位 证件号 开户银行名称 银行支持情况及银行名称填写内容请参看《收付捷商户操作使用手册（代付商户）》 8 openBank 开户银行 9 prov 省份 字符 变长，必填 20位 收款人开户行所在省， 请参看《收付捷商户操作使用手册（代付商户）》 10 city 城市 字符 变长，必填 40位 收款人开户行所在地区， 请参看《收付捷商户操作使用手册（代付商户）》 11 transAmt 金额 数字 变长，必填 12位 整数，货币种类为人民币，以分为单位 存款用途。 12 purpose 用途 字符 变长，必填 99位 13 subBank 支行 字符 变长，选填 80位

第 23 页 共 36 页

开户支行名称。 http://www.chinapay.com

14 flag 付款标志 字符 定长，选填 2位 对公对私标记。“00”对私，“01”对公。该字段可以不填，如不填则默认为对私。 15 version 版本号 字符 变长，必填 8位 固定为“20160530” 16 signFlag 签名 标志 字符 定长，必填 1位 数字 定长，必填 2位 固定为“1” 17 termType 渠道 类型 18 payMode 交易 模式 数字 定长，必填 1位 表示商户代付业务使用场景，（业务参数） 07：互联网 08：移动端 表示商户代付业务交易模式 （业务参数） 0：被动发起代付 1：主动发起代付 19 userId 用户ID 字符 变长，非必填 持卡人ID 64位 20 userRegisterTime 字符 定长，非必填 持卡人注册时间，格式为YYYYMMDDHHMMSS 册时间 14位 用户注用户注册邮箱 字符 变长，非必填 持卡人注册邮箱 128位 字符 变长，非必填 持卡人注册手机号 32位 21 userMail 22 userMobile 用户注册手机号 23 diskSn PC 硬盘序列号 字符 变长，非必填 64位 代付操作使用的PC 硬盘序列号 24 mac PC mac地址 字符 变长，非必填 32位 代付操作使用的PC mac地址 25 imei 手机串号字符 变长，非必填 16位 代付时使用的手机串号

第 24 页 共 36 页

http://www.chinapay.com

IMEI 26 ip 登录IP 字符 变长，非必填 进行代付操作时使用的IP 64位 27 coordinates 代付时经纬度信息 28 baseStationSn 手机所在基站序列号 29 codeInputType 短信验证码输入操作特征 字符 定长，非必填 当移动端持卡人所用APP能够从短信记录中读取短信验证码自动2位 填写并记录用户操作特征时上送 00 短信验证码根据接收验证短信自动填写，并经商户校验通过（自动填写用户未修改验证码文本框中内容） 01 短信验证码非自动填写（包括无法读取短信记录，验证码用户手工输入等情况） 字符 变长，非必填 32位 字符 变长，非必填 商品名称 512位 签名字段，具体见下方 银行卡预留手机号 字符 变长，非必填 示例+37/+122 北纬、东经为+，南纬、西经为-，使用纬度、经度16位 的方式，中间用/隔开，支持上送精度达到小数点后8位。 字符 变长，非必填 支付时手机所在基站序列号 16位 30 mobileForBank 预留手机号 31 desc 购买商品明细 32 chkValue 签名值 字符 定长，必填 256位 chkValue 为签名数据, 将参与签名的字段内容按顺序连接起来，组成一个签名字符串明文，对该签名字符串进行BASE64编码，再调用NetPayClient提供的签名方法，对BASE64编码后的字符串进行签名。参与签名的字段及顺序为: merId + merDate +merSeqId +cardNo + usrName+certType+certId+ openBank +prov +city + transAmt + purpose + subBank + flag + version + termType+payMode+userId+userRegisterTime+userMail+userMobile+diskSn+mac+imei+ip+coordinates+baseStationSn+codeInputType+mobileForBank+desc

第 25 页 共 36 页

http://www.chinapay.com

5.1.7.cp应答数据描述

No 字段名称 长度 是否必然出现 是 否 否 否 否 否 否 否 否 是 项目描述 请求应答码，具体请见附录6.1.1 同请求报文参数中的商户号 同请求报文参数中的商户日期 同请求报文参数中的商户流水号 ChinaPay接收到交易的日期 ChinaPay系统内部流水 同请求报文参数中的金额 交易状态码，具体请参看附录6.1.2 同请求报文参数中的收款账号 对返回字串的签名。返回应答报文中最后一个“&”符号以前的都是作为签名的明文。明文需进行BASE64编码，具体见下方。 ●CP

1. responseCode 4位 2. merId 3. merDate 4. merSeqId 5. cpDate 6. cpSeqId 7. transAmt 8. stat 9. cardNo 10. chkValue 15位 8位 16位 8位 6位 12位 1位 32位 256位 应答数据示例

●交易接收成功应答

responseCode=0000&merId=606060103099001&merDate=20120530&merSeqId=0020120530100521&cpDate=20120530&cpSeqId=372782&transAmt=000000000001&stat=X&cardNo=97891……&chkValue= X……256位……..X 验签明文：

responseCode=0000&merId=606060103099001&merDate=20120530&merSeqId=0020120530100521&cpDate=20120530&cpSeqId=372782&transAmt=000000000001&stat=X&cardNo=97891……

“stat=X”，其中X代表交易状态响应码。具体请见6.1.1

●交易接收失败应答

responseCode=XXXX&merId=606060103099001&merDate=20120530&merSeqId=0020120530100521&cpDate=20120530&cpSeqId=372782&transAmt=000000000001&stat=X&cardNo=97891&chkValue= X……256位……..X

第 26 页 共 36 页

http://www.chinapay.com

验签明文：

responseCode=XXXX&merId=606060103099001&merDate=20120530&merSeqId=0020120530100521&cpDate=20120530&cpSeqId=372782&transAmt=000000000001&stat=X&cardNo=97891

参数具体出现情况根据实际情况而定，出现顺序可参看CP应答数据描述。

“responseCode=XXXX”，其中XXXX代表交易状态响应码。具体请见6.1.2

5.2.单笔查询接口

5.2.1.概要说明

该接口定义商户查询的数据传输，商户通过该接口进行交易的单笔查询，chinapay收到商户查询请求返回查询结果。如果没有则会在code字段中对应相应的错误码。此功能为辅助功能。

系统会对查询间隔做频率限制，前后两次查询的时间间隔不得少于3秒；同一笔订单查询间隔不得少于30秒。

当查询结果为没有记录时，如商户需要对原交易订单再次提交付款，请使用原交易订单信息（商户号+商户流水号+商户日期）重新提交代付请求。

5.2.2.请求数据示例

5.2.3.请求url

生产：http://sfj.chinapay.com/dac/SinPayQueryServletGBK（支持https） 测试：http://sfj-test.chinapay.com/dac/SinPayQueryServletGBK

第 27 页 共 36 页

http://www.chinapay.com

5.2.4.商户端提交的数据内容

No 字段名称 项目描述 格式 长度 出现要求 1 2 merId merDate 商户号 数字 定长，15位 必填 在收付捷平台中开通的商户编号 必填 标志该笔交易发生的日期,格式为YYYYMMDD。仅允许查询最近一个月的交易订单 3 merSeqId 流水号 数字 变长，16位 必填 商户号+商户流水号+商户日期唯一标示一笔交易订单 4 5 6 version signFlag chkValue 版本号 数字 变长，8位 必填 固定为“20090501” 必填 固定为“1” 说明 商户日期 数字 定长，8位 签名标志 字符 定长，1位 签名值 字符 定长，256位 必填 签名字段,具体见下方。 chkValue 为签名数据, 将参与签名的字段内容按顺序连接起来，组成一个签名字符串明文，对该签名字符串进行BASE64编码，再调用NetPayClient提供的签名方法，对BASE64编码后的字符串进行签名。参与签名的字段及顺序为: merId + merDate +merSeqId +version

5.2.5.cp返回的数据内容

cp返回一个字符串，带有如下信息。每个信息字段用‘|’分隔。具体如下： No 字段名称 项目描述 应答信息 格式 长度 说明 000表示成功。001表示没有记录。002表示查询出错。查询频率超限也为002 2. merId 3. merDate 4. merSeqId 商户号 商户日期 流水号 数字 定长，15位 数字 定长，8位 数字 变长，16位 同请求报文参数中商户号 原始订单交易日期 交易记录流水号，同商户日期，商户号一起唯一标识报文中的一

第 28 页 共 36 页

1. code 数字 定长，3位 http://www.chinapay.com

笔交易(merId + merDate + merSeqId唯一确定一条记录) 5. cpDate 6. cpSeqId 7. bankName 8. cardNo Cp日期 Cp流水 开户银行 收款账号 数字 定长，8位 数字 定长，6位 字符 变长，50位 数字 只取后5位 ChinaPay接收到交易的日期 ChinaPay系统内部流水 原始订单参数中的开户银行 原始订单参数中的收款账号，仅显示后5位 9. usrName 10. transAmt 11. feeAmt 12. prov 13. city 14. purpose 15. stat 收款人姓名 金额 手续费 省份 城市 用途 交易状态 字符 变长，100位 原始订单参数中收款人姓名 数字 变长，12位 数字 变长，12位 字符 变长，20位 字符 变长，40位 字符 变长，99位 数字 定长，1位 原始订单参数中的金额 整数，以分为单位 原始订单参数中的省份 原始订单参数中的城市 原始订单参数中的用途 交易状态码，具体请参看附录6.1.2 16. backDate 17. chkValue 退单日期 签名值 数字 定长，8位 银行退单日期 字符 定长，256位 除了报文尾部的256位以上的都是作为签名的明文。明文需进行BASE64编码，具体见下方。 返回报文示例：

●查询成功返回报文

000|606060081799247|20110830|0020110830161537|20110830|290149|工商银行|97891|赵钱孙|000000000001|500|上海|上海|稿费

|2||20D1783E38B93B1EF395D43A7C10E50CFEB5CB64810957B1B626DAFDD4D92C67EE56512881672511690EFD1BAFE4FCBE9289C6E55615650F1D2ED0E2C28701A611BD45FA15B40A2795A4ADA7A881833D2FF1A5CA947F3E935AB1B92DDF3129D04DA8EFB544B6D034EB5F3ACEEB076EE314E874AD57035289AD087B46ED8B4DA5 需要验签的字段：

000|606060081799247|20110830|0020110830161537|20110830|290149|工商银行|97891|赵钱孙|000000000001|500|上海|上海|稿费|X||

●查询无记录返回报文

001|||||||||||||||||8297EA9B6F391D7A128B3741005D45D9885F925AD3BBE51B109662E9E417FA

第 29 页 共 36 页

http://www.chinapay.com

C58025FB9F1A93FB210598C718B78A6AEF69D98688C542C53B513CBC491DA3F4BFD135E6409AF5304B2628A5128DD2BF53B0AE7BBB770871A2A7B8C9BFFDB00D4AAECF279CFC494D41EA133327C2530DB60BF9AE9156AE24124609ACEAF406139A 需要验签的字段： 001|||||||||||||||||

●查询出错返回报文

002|||||||||||||||||82C0969197E61824D94FA49A495F229013EFC27A53870474DC8D8B0A9E3B1267E08BB5712E9B99F039EACE908D4F1D73F35ED46CC032ABBCC417F5DFBBBE67F675163881B4BA590A48107828A9E9392523FD73998B51BD270DD6A397AAAF46202468A4F27F888CED5E62FF6252C646EFACCE7483B2E15EBB44D1F5769A3915C2 需要验签的字段： 002|||||||||||||||||

“stat=X”，其中X代表交易状态响应码。具体请见6.1.1

5.3.批量退单查询接口

5.3.1.概要说明

商户通过http post方式提交交易参数和数字签名，根据退单日期的范围来进行退单查询。收付捷平台处理完毕通过http post方式返回。

5.3.2.请求数据示例

5.3.3.请求url

生产：http://sfj.chinapay.com/dac/FailureTradeQueryGBK（支持https）

第 30 页 共 36 页

本文来源：https://www.bwwdw.com/article/tkkh.html