中国银联全渠道系统商户接入测试指引-银联网关支付产品

Love The Way You Lie 2022-08-09 03:19 1417阅读 0赞

直接把银联的联调测试文档贴来了

<table> 
 <tbody> 
 <tr> 
 <td> 
 <div> 
 中国银联股份有限公司规范性文档 
 </div> </td> 
 </tr> 
 </tbody> 
</table>

<table> 
 <tbody> 
 <tr> 
 <td> 
 <div> 
 中国银联股份有限公司 发布 
 </div> </td> 
 </tr> 
 </tbody> 
</table>

<table> 
 <tbody> 
 <tr> 
 <td> &nbsp; 中国银联全渠道系统商户接入 测试指引-银联网关支付产品 </td> 
 </tr> 
 </tbody> 
</table>

版本修订信息

<table> 
 <thead> 
 <tr> 
 <td> 版本号 </td> 
 <td> 完成日期 </td> 
 <td> 发布日期 </td> 
 <td> 变更说明 </td> 
 </tr> 
 </thead> 
 <tbody> 
 <tr> 
 <td> 1.0.0 </td> 
 <td> 2014-7-03 </td> 
 <td> 2014-7-03 </td> 
 <td> 初稿 </td> 
 </tr> 
 <tr> 
 <td> 1.0.1 </td> 
 <td> 2014-11-04 </td> 
 <td> 2014-11-05 </td> 
 <td> 修改文档格式，新增测试地址与测试卡号等信息 </td> 
 </tr> 
 <tr> 
 <td> &nbsp; </td> 
 <td> &nbsp; </td> 
 <td> &nbsp; </td> 
 <td> &nbsp; </td> 
 </tr> 
 <tr> 
 <td> &nbsp; </td> 
 <td> &nbsp; </td> 
 <td> &nbsp; </td> 
 <td> &nbsp; </td> 
 </tr> 
 <tr> 
 <td> &nbsp; </td> 
 <td> &nbsp; </td> 
 <td> &nbsp; </td> 
 <td> &nbsp; </td> 
 </tr> 
 <tr> 
 <td> &nbsp; </td> 
 <td> &nbsp; </td> 
 <td> &nbsp; </td> 
 <td> &nbsp; </td> 
 </tr> 
 <tr> 
 <td> &nbsp; </td> 
 <td> &nbsp; </td> 
 <td> &nbsp; </td> 
 <td> &nbsp; </td> 
 </tr> 
 <tr> 
 <td> &nbsp; </td> 
 <td> &nbsp; </td> 
 <td> &nbsp; </td> 
 <td> &nbsp; </td> 
 </tr> 
 <tr> 
 <td> &nbsp; </td> 
 <td> &nbsp; </td> 
 <td> &nbsp; </td> 
 <td> &nbsp; </td> 
 </tr> 
 <tr> 
 <td> &nbsp; </td> 
 <td> &nbsp; </td> 
 <td> &nbsp; </td> 
 <td> &nbsp; </td> 
 </tr> 
 </tbody> 
</table>

1     文档说明... 6

1.1       导读... 6

1.2       阅读对象... 6

1.3       业务术语... 7

1.4       技术服务... 7

1.4.1        测试模式划分... 7

1.4.2        支持获取途径... 8

2     联调步骤向导... 9

2.1       交易开发... 9

2.2       测试联调... 9

2.3       切换上线... 9

3     测试参数与产品相关交易... 9

3.1       测试与生产地址... 9

3.2       测试卡号... 9

3.3       产品相关交易... 10

3.4       产品介绍... 11

4     交易模式说明... 11

4.1       通讯方式... 12

4.2       前台交易流程... 12

4.3       后台资金类交易流程... 13

4.4       后台非资金类交易流程... 15

4.5       查询交易流程... 15

5     开发步骤向导... 16

5.1       前台交易开发步骤... 16

5.2       后台类异步交易接口开发步骤... 17

5.3       后台类同步交易接口开发步骤... 17

5.4       单笔查询交易接口开发步骤... 18

5.5       文件传输类交流开发步骤... 18

6     前台应答与后台通知说明... 19

7     查询接口说明... 21

7.1       前台交易... 21

7.2       后台资金交易... 21

7.3       后台非资金交易... 21

7.4       查询交易... 21

8     签名机制... 22

9     加密机制... 22

10            证书相关说明... 23

10.1         概述... 23

10.2         证书下载及导出流程(ok)23

10.2.1     证书下载流程... 23

10.2.2证书导出流程...27

11            开发包插件使用... 32

11.1         JSP/JAVA.. 32

11.1.1     配置文件说明... 32

11.1.2     主要类和方法说明... 35

11.1.3     配置文件加载说明... 38

11.2         PHP. 38

11.2.1     配置文件说明... 38

11.2.2     主要类与方法说明... 43

11.3         ASP.NET. 48

11.3.1     配置文件说明... 49

11.3.2     主要类和方法说明... 52

12            常见问题问答... 57

# 1     文档说明 #

## 1.1   导读 ##

网关产品主要适用于持卡人在商户网站B2C购物支付场景，持卡通过点击银联在线支付logo，并在银联在线支付网关完成支付信息录入，最终完成支付。

从PC端发起的交易为WEB网关支付交易，从移动端发起的交易为WAP网关支付交易以及APP网关交易。

首次接入测试先了解前台交易与后台交易的区别，可参考第1.3章节业务术语描述，随后可从第5章节开发步骤向导开始阅读，了解开发过程中的具体操作步骤，此章节中提到的签名机制请参照第8章节。开发过程中需要用到的测试与生产交易地址请参考第11章节配置文件。交易测试卡号请参考第3.2章节。如开发与测试过程中遇到了解决不了的问题可在第12章节FAQ中查找解决方案，也可通过第1.4.2章节中的方法来获取测试支持。

## 1.2   阅读对象 ##

《中国银联全渠道系统商户接入测试指引》文档是面向具有一定的网站开发能力的网站开发、维护和管理人员。

具体交易的接口、报文规范、响应码说明，请阅读开发包中接口文档。

<table> 
 <tbody> 
 <tr> 
 <td style="background:#4F81BD"> 参与方描述 </td> 
 <td style="background:#4F81BD"> &nbsp; </td> 
 </tr> 
 <tr> 
 <td> 商户 </td> 
 <td> 指加入银联网络，与银联签订《银联卡无卡支付业务合作协议》等协议开展银联无卡支付以及行业类应用业务的商户。 </td> 
 </tr> 
 <tr> 
 <td> 收单机构 </td> 
 <td> 指加入银联网络，与银联签订《银联卡无卡支付业务合作协议》开展银联无卡支付收单业务的境内成员机构。 </td> 
 </tr> 
 </tbody> 
</table>

## 1.3   业务术语 ##

<table> 
 <tbody> 
 <tr> 
 <td style="background:#4F81BD"> 术语 </td> 
 <td style="background:#4F81BD"> 解释 </td> 
 </tr> 
 <tr> 
 <td style="background:#D3DFEE"> 请求 </td> 
 <td style="background:#D3DFEE"> 通过 HTTP/HTTPS协议把需要传输的数据发送给接收方的过程。 </td> 
 </tr> 
 <tr> 
 <td> 应答 </td> 
 <td> 通过 HTTP/HTTPS协议把需要传输的数据返回给接收方的过程。 </td> 
 </tr> 
 <tr> 
 <td style="background:#D3DFEE"> 后台通知 </td> 
 <td style="background:#D3DFEE"> 服务器后台通知。中国银联全渠道系统根据得到的数据处理完成后，全渠道系统主动发起通知给商户的网站，同时携带处理完成的结果信息反馈给商户网站。 </td> 
 </tr> 
 <tr> 
 <td> 前台类交易 </td> 
 <td> 主要指用户需要参与交互的支付类交易，包括消费、预授权/担保消费交易。 </td> 
 </tr> 
 <tr> 
 <td style="background:#D3DFEE"> 后台类交易 </td> 
 <td style="background:#D3DFEE"> 主要指用户不需要参与交互，由商户后续发起的交易，包括消费撤销、退货、预授权撤销、预授权完成、预授权完成撤销等交易。 </td> 
 </tr> 
 <tr> 
 <td> 全渠道系统/ACP </td> 
 <td> 中国银联全渠道系统，是整合了银联在线和银联移动支付功能的新交易处理系统。 </td> 
 </tr> 
 </tbody> 
</table>

## 1.4   技术服务 ##

### 1.4.1 测试模式划分 ###

接入网关支付产品的商户为选测。

**注：**

必测是指提交了入网申请表、必须测试通过才能投产上线的，选测是指不需要入网申请表可以直接投产上线的，是否在测试环境测试由商户自己决定。

### 1.4.2 支持获取途径 ###

业务问题详见开发包中《中国银联全渠道系统业务运营服务指引》相关人员联系方式。

测试问题支持人员联系方式详见下表：

<table> 
 <tbody> 
 <tr> 
 <td style="background:#4F81BD"> 必测 </td> 
 <td style="background:#4F81BD"> 选测 </td> 
 </tr> 
 <tr> 
 <td> 收单机构可联系银联服务专员，并且在提交了入网申请后银联服务专员会主动联系商定窗口并提供测试支持服务 </td> 
 <td> <a href="mailto:%E5%95%86%E6%88%B7%E5%8F%AF%E5%8F%91%E9%80%81%E9%82%AE%E4%BB%B6%E5%88%B0acpservice@unionpay.com" rel="nofollow">商户可发送邮件到acpservice@unionpay.com</a>邮箱（邮件标题为：商户号+商户名称+联系QQ），提供商户号和联系QQ，银联测试服务专员会将商户接口人的联系QQ加入到银联统一服务QQ中提供支持服务（商户也可以通过服务电话021-38929999-2049来提供自己的商户号和联系QQ） </td> 
 </tr> 
 <tr> 
 <td> 银联市场服务代表在为商户提交了入网申请后，会有银联服务专员主动联系（一般为QQ）商定联调窗口并提供测试支持服务 </td> 
 </tr> 
 </tbody> 
</table>

**注：**

服务邮箱和服务电话仅供选测类商户联系测试支持人员，并且邮箱和电话不直接反馈支持问题，支持服务均在银联统一服务QQ中提供。

# 2     联调步骤向导 #

## 2.1   交易开发 ##

商户或收单机构全渠道系统开发包和本测试指引进行接入开发。

## 2.2   测试联调 ##

本步骤可选。开发完成后可通过银联提供的联调测试环境进行联机接口验证测试，测试地址参考测第11章节配置文件说明。

## 2.3   切换上线 ##

在测试环境完成联调测试后，由银联业务运营人员(联系方式参见《中国银联全渠道系统业务运营服务指引》)引导协助商户完成生产交易证书的申请，商户将接口更新部署到生产环境和银联生产环境完成对接。

# 3     测试参数与产品相关交易 #

## 3.1  测试与生产地址 ##

测试地址详见第11章节配置文件描述。

## 3.2  测试卡号 ##

<table> 
 <tbody> 
 <tr> 
 <td style="background:#4F81BD"> 测试卡号 </td> 
 </tr> 
 <tr> 
 <td style="background:#D3DFEE"> 平安银行借记卡：6216261000000000018 证件号：341126197709218366 手机号：13552535506 密码：123456 姓名：全渠道 </td> 
 </tr> 
 <tr> 
 <td> 平安银行贷记卡：6221558812340000 姓名：互联网 证件号：341126197709218366 手机号：13552535506 cvn2:123 有效期：1711 </td> 
 </tr> 
 </tbody> 
</table>

## 3.3  产品相关交易 ##

<table> 
 <tbody> 
 <tr> 
 <td style="background:#4F81BD"> 序号 </td> 
 <td style="background:#4F81BD"> 接口名称 </td> 
 <td style="background:#4F81BD"> 功能说明 </td> 
 <td style="background:#4F81BD"> 交易模式 </td> 
 </tr> 
 <tr> 
 <td style="background:#D3DFEE"> 1 </td> 
 <td style="background:#D3DFEE"> 消费类交易（前台类） </td> 
 <td style="background:#D3DFEE"> 持卡人进支付时，由银联或发卡行展示支付页面，引导持卡人完成后续支付的交易。 </td> 
 <td style="background:#D3DFEE"> 前台资金类交易 </td> 
 </tr> 
 <tr> 
 <td> 2 </td> 
 <td> 消费撤销类交易 </td> 
 <td> 指因人为原因而撤销已完成的消费；消费撤销必须是撤销CUPS当日当批的消费 </td> 
 <td> 后台资金类交易 </td> 
 </tr> 
 <tr> 
 <td style="background:#D3DFEE"> 3 </td> 
 <td style="background:#D3DFEE"> 退货类交易 </td> 
 <td style="background:#D3DFEE"> 对于已结算的消费交易，通过该交易发起退款交易。 </td> 
 <td style="background:#D3DFEE"> 后台资金类交易 </td> 
 </tr> 
 <tr> 
 <td> 4 </td> 
 <td> 交易状态查询类交易 </td> 
 <td> 对未收到应答的或交易状态未知的交易，可通过该交易进行查询。 </td> 
 <td> 查询类交易 </td> 
 </tr> 
 <tr> 
 <td style="background:#D3DFEE"> 5 </td> 
 <td style="background:#D3DFEE"> 文件传输类交易 </td> 
 <td style="background:#D3DFEE"> 联机下载对账文件等文件下载类交易 </td> 
 <td style="background:#D3DFEE"> 后台非资金交易 </td> 
 </tr> 
 <tr> 
 <td> 6 </td> 
 <td> 预授权类交易 </td> 
 <td> 预授权交易用于受理方向持卡人的发卡方确认交易许可。受理方将预估的消费金额作为预授权金额，发送给持卡人的发卡方。 </td> 
 <td> 前台或后台资金类交易 </td> 
 </tr> 
 <tr> 
 <td style="background:#D3DFEE"> 7 </td> 
 <td style="background:#D3DFEE"> 授权撤销类交易 </td> 
 <td style="background:#D3DFEE"> 对已成功的预授权交易，在结算前使用该交易进行取消。 </td> 
 <td style="background:#D3DFEE"> 后台资金类交易 </td> 
 </tr> 
 <tr> 
 <td> 8 </td> 
 <td> 授权完成类交易 </td> 
 <td> 对已批准的预授权交易，用该交易进行支付结算； </td> 
 <td> 后台资金类交易 </td> 
 </tr> 
 <tr> 
 <td style="background:#D3DFEE"> 9 </td> 
 <td style="background:#D3DFEE"> 授权完成撤销类交易 </td> 
 <td style="background:#D3DFEE"> 预授权完成撤销交易必须是对原始预授权完成交易的全额撤销。预授权完成撤销后的预授权仍然有效。 </td> 
 <td style="background:#D3DFEE"> 后台资金类交易 </td> 
 </tr> 
 <tr> 
 <td> 10 </td> 
 <td> 余额查询 </td> 
 <td> &nbsp; </td> 
 <td> 后台非资金类交易 </td> 
 </tr> 
 <tr> 
 <td style="background:#D3DFEE"> 11 </td> 
 <td style="background:#D3DFEE"> 电子现金非指定账户圈存 </td> 
 <td style="background:#D3DFEE"> &nbsp; </td> 
 <td style="background:#D3DFEE"> 后台资金类交易 </td> 
 </tr> 
 <tr> 
 <td> 12 </td> 
 <td> 电子现金指定账户圈存 </td> 
 <td> &nbsp; </td> 
 <td> 后台资金类交易 </td> 
 </tr> 
 <tr> 
 <td style="background:#D3DFEE"> 13 </td> 
 <td style="background:#D3DFEE"> 圈存脚本通知 </td> 
 <td style="background:#D3DFEE"> &nbsp; </td> 
 <td style="background:#D3DFEE"> 后台资金类交易 </td> 
 </tr> 
 <tr> 
 <td> 14 </td> 
 <td> IC卡脱机消费通知 </td> 
 <td> &nbsp; </td> 
 <td> 后台资金类交易 </td> 
 </tr> 
 </tbody> 
</table>

## 3.4  产品介绍 ##

产品介绍详见《网关支付产品入网材料》包中的《银联全渠道系统网关产品.pptx》。

# 4     交易模式说明 #

从技术实现方式上交易大致可划分为前台类交易、后台资金类类交易、后台非资金类交易、查询类交易、批量类交易。本节将描述各种交易的大致流程。

## 4.1   通讯方式 ##

所有报文域以key/value的表单方式通过HTTP Post到银联全渠道系统支付平台。对于前台类需要持卡人交互的交易，交易通过异步跳转的方式完成，对于涉及资金的前台类交易，银联全渠道系统支付平台可通过商户后台通知地址向商户发送后台通知。对于后台类涉及资金清算类无需持卡人交互的交易，交易结果异步响应给商户，商户通过接受后台通知或者发起交易查询获取交易处理结果。对于后台类非资金类无需持卡人交互的交易，交易结果同步响应给商户。对应交易状态查询类交易，交易结果同步响应给商户。

## 4.2  前台交易流程 ##

前台类交易是指交易请求方（如商户、收单机构）与ACP之间的交易信息通过用户浏览器进行传递的交易，是一种异步的、需要持卡人参与完成的交易类型。对于涉及金额的前台类交易（即交易请求中有金额字段）ACP系统均会给请求方后台通知(后台通知报文要素同前台应答的要素)，请求方也必须实现接收后台通知。对于交易状态未知的交易请求方必须发起交易状态查询交易。

图 1‑1

注意点：

1.      每个交易需要的报文要素是不一样的，具体每个交易需要的要求，请参考接口文档；

2.      图1‑1中第8步前台应答返回的URL为请求报文中的“frontUrl”字段指定的URL；

3.      图1‑1中第7步后台应答返回的URL为请求报文中的“backUrl”字段指定的URL；

## 4.3   后台资金类交易流程 ##

后台类资金类交易是指交易请求方（如商户、收单机构），将交易信息（涉及资金清算的交易）直接通过请求方服务器发送至ACP服务器的交易方式。是一种异步的、不需要持卡人参与完成的交易类型。因涉及资金的清算，ACP系统均会给请求方后台通知(后台通知报文要素同前台应答的要素)，请求方也必须实现接收后台通知。对于交易状态未知的交易请求方必须发起交易状态查询交易。

图 1‑3

<table> 
 <tbody> 
 <tr> 
 <td style="background:#4F81BD"> 注意： </td> 
 </tr> 
 <tr> 
 <td style="background:#D3DFEE"> 1.&nbsp;&nbsp;&nbsp;&nbsp; 每个交易需要的报文要素是不一样的，具体每个交易需要的要求，请参考开发包中接口规范文档； </td> 
 </tr> 
 <tr> 
 <td> 2.&nbsp;&nbsp;&nbsp;&nbsp; 图1-3中第4步中的应答仅代表该笔后台请求交易已经受理，不代表全部处理成功；是否处理成功，需通过接受后台通知或者发起“交易状态查询交易”进行查询； </td> 
 </tr> 
 <tr> 
 <td style="background:#D3DFEE"> 3.&nbsp;&nbsp;&nbsp;&nbsp; 第5步后台应答返回的URL为请求报文中的“backUrl”字段指定的URL。 </td> 
 </tr> 
 </tbody> 
</table>

## 4.4   后台非资金类交易流程 ##

后台类非资金类交易是指交易请求方（如商户、收单机构）将交易信息（不涉及资金清算的交易）直接通过请求方服务器发送至ACP服务器的交易方式。后台非资金类交易均为同步短连接方式，不需要持卡人参与完成的交易类型。若通讯超时，则交易请求方可以重复发起交易。

图1‑4

## 4.5   查询交易流程 ##

查询交易是指交易请求方（如商户、收单机构）将交易查询报文信息直接通过请求方服务器发送至ACP服务器的交易方式。查询类交易均为同步短连接方式，不需要持卡人参与完成的交易类型。，若通讯超时，则交易请求方可以重复发起交易。

图 1‑5

# 5    开发步骤向导 #

## 5.1   前台交易开发步骤 ##

1. 以表单的方式组装要发送给银联全渠道系统的数据对象（包括IC卡交易信息域，VPC交易信息域，风控信息域等各域）。每个域填写方法可参考文档开发包中接口文档。

2. 将组装好的数据排序好并用&连接后签名，生成signature字段，可使用插件包提供的方法“SDKUtil.*sign*(未签名报文, 报文字符集);”具体签名机制请参照第8章节。可通过调用插件包提供的签名方法来完成签名。

3. 把所有要发送给银联全渠道系统的域包括signature和signMethod，组成表单以POST方式送给银联全渠道系统前台交易的地址。

4. 交易完成后，银联全渠道系统将把交易结果分别返回通知到商户通的前台应答地址和后台应答地址上，商户接收到交易通知后可分别调用“SDKUtil.*convertResultStringToMap*(应答报文);”方法进行应答报文解析，和“SDKUtil.*validate*(应答报文, 报文字符集)”方法进行签名验证。

## 5.2   后台类异步交易接口开发步骤 ##

1. 商户按照不同的交易组装报文，交易报文请参考开发包中接口规范。

2. 把组装好的数据排序好并用&连接后签名，生成signature字段，可使用插件包提供的方法“SDKUtil.*sign*(未签名报文, 报文字符集);”，具体签名机制请参照第7章节。

3. 把所有数据，包括signature和signMethod用key=value并用&符号链接的方式组装成字符串，通过插件包提供的方法进行发送。

4. 接收到返回报文后，通过插件包提供的方法进行验证签名，调用“SDKUtil.*convertResultStringToMap*(应答报文);”方法进行应答报文解析，和“SDKUtil.*validate*(应答报文, 报文字符集)”方法进行签名验证。

## 5.3   后台类同步交易接口开发步骤 ##

1. 商户按照不同的交易组装报文，交易报文请参考开发包中接口规范。

2. 把组装好的数据排序好并用&连接后签名，生成signature字段，可使用插件包提供的方法“SDKUtil.*sign*(未签名报文, 报文字符集);”，具体签名机制请参照第8章节。

3. 数据，包括signature和signMethod用key=value并用&符号链接的方式组装成字符串，通过插件包提供的方法进行发送。

4. 返回报文后，通过插件包提供的方法进行验证签名，调用“SDKUtil.*convertResultStringToMap* (应答报文);”方法进行应答报文解析，和“SDKUtil.*validate* (应答报文, 报文字符集)”方法进行签名验证。

## 5.4  单笔查询交易接口开发步骤 ##

1.照单笔查询交易的规范组装报文，交易报文请参考开发包中接口文档

2.好的数据排序好并用&连接后签名，生成signature字段，可使用插件包提供的方法“SDKUtil.*sign*(未签名报文, 报文字符集);”，具体签名机制请参照第7章节。

3.数据，包括signature和signMethod用key=value并用&符号链接的方式组装成字符串，通过SDK提供的方法进行发送。

4.返回报文后，通过插件包提供的方法进行验证签名，调用“SDKUtil.*convertResultStringToMap*(应答报文);”方法进行应答报文解析，和“SDKUtil.*validate*(应答报文, 报文字符集)”方法进行签名验证。

## 5.5  文件传输类交流开发步骤 ##

文件的格式，参照接口文档，文件名，文件头，文件，文件以inputfilepost方式提交到服务器，以文件流的方式获取字节流信息，先需要解压缩文件内容的byte\[\]数组，用SecureUtil.deflater方法，后BASE64编码，用SecureUtil.base64Encode方法，返回，最终以字符串方式提交到处理服务器，服务器响应报文里有filecontent字段，先用SecureUtil.base64Decode解码，后用SecureUtil.inflater方法解压缩，返回byte\[\],接下来就可以通过文件输出的方法，生成文件。

文件转字符串

图2‑1

# 6     前台应答与后台通知说明 #

前台交易，商户或机构需要提供两个地址frontUrl和backUrl（通过报文域上送），分别接收银联全渠道系统的前台应答和后台通知。前台应答是通过浏览器，用户点击“返回商户”按钮发送给商户的，后台通知是银联全渠道系统异步把交易状态为成功的交易通知给商户。具体详细关于前台应答和后台通知请参照接口文档。不管收到前台应答还是后台通知，商户都需要验签。

在交易结束后，银联全渠道系统通过后台通知将交易结果发给商户或机构。后台通知以标准的HTTP协议的POST方法向商户的后台通知URL发送，并设置一个超时计时器，通常设置为10s。商户在收到通知，解析后应立即返回应答报文。仅当POST返回码为200时，才认为商户已经成功收到并且能正确解析后台通知，其他返回码则被认为通知失败。如果计时器超时，没有收到应答报文，也被认为通知失败。  
第一次通知失败后，会通过退避策略进行通知重发，最多发送五次。由于网络等原因，商户会收到重复的后台通知。

商户或机构在接收到银联全渠道系统的前台应答或后台通知后，首先必须验证该消息的签名，然后根据订单号等信息，更新相应系统中的订单支付状态。前台通知因存在用户支付完毕后直接关闭浏览器的情况，而不能保证每次都送达。后台通知由银联银联全渠道系统通知服务器主动发起，若发送失败，银联全渠道系统会继续发送，一共发送5次，若还是发送失败，也不继续发送。商户在未收到后台应答，建议请求20分钟后主动发起交易查询交易来查询交易状态。

另外，退货等后台类交易（若有开发）是异步过程，银联全渠道系统收到后台类交易请求后会回复一个请求已接受的应答。在交易处理后，银联全渠道系统会发送后台通知给商户，建议商户无论是否收到后台通知，在请求2分钟后主动发起交易查询交易来查询交易状态。

注：银联全渠道系统只针对成功交易会发送后台通知，失败交易不发送后台通知。因此，如未收到后台通知，建议商户主动发起交易查询交易，查询交易状态。

另外后台通知接收需要注意以下几点：

1.后台通知采用POST的方式来发送，POST的地址是商户上送的backUrl域，backUrl域需要保证该地址的正确性。

2.后台通知中，只要是非通信类错误（如通信超时，无法解析域名，没有路由等），都认为商户已经收到，不会进行重发。如果商户因为非通信类问题没有及时收到应答（比如应用切换等情况），或者收到应答时处理失败（处理逻辑的验证应该在测试环境下已经验证通过），商户应该对没有及时收到应答的交易通过查询接口来查询该交易的状态。

3.确定通知成功由以下几个要素

a)     通知URL填写正确（商户必须要保证URL的正确性）

b)     通信正确（通信失败时必须重发）

c)      商户能够正确验签（测试环境要测试通过）

因此，只要生产上能够证明通信是正确的，即可认为通知成功。如果商户端因为某种特殊原因，没有正确处理后台通知，可以通过交易查询接口来纠正交易的状态。

# 7    查询接口说明 #

## 7.1   前台交易 ##

1.      如果已收到后台通知，则不需要发起查询。

2.      在订单发起后半小时未收到后台通知，则需要发起查询。

3.      具体的查询交易开发方法可参考5.4章节。

## 7.2   后台资金交易 ##

1.      如果已收到后台通知，则不需要发起查询。

2.      在订单发起后半小时未收到后台通知，则需要发起查询。

3.      具体的查询交易开发方法可参见第4.5章节。

## 7.3   后台非资金交易 ##

后台交易采用同步机制，交易结果同步返回。

## 7.4   查询交易 ##

1.      如果已接收到明确的交易结果应答，则不需要发起查询。

2.      前台交易，若未接收到全渠道系统的明确交易应答时需发起单笔查询交易，查询明确的交易结果。

3.      后台交易，若出现交易超时的情况则需要发起单笔查询交易，查询明确的交易结果。

# 8    签名机制 #

对于报文的签名处理机制如下：

首先，对报文中出现签名域（signature）之外的所有数据元采用key=value的形式按照名称排序，然后以&作为连接符拼接成待签名串。其次，对待签名串使用SHA-1算法做摘要，并转成16进制，再使用银联颁发给商户的商户RSA私钥证书对摘要做签名操作（签名时算法选择SHA-1）。最后，对签名做Base64编码，将编码后的签名串放在签名（signature）表单域里和其他表单域一起通过HTTP Post的方式传输给银联全渠道系统支付平台。

对于报文的验签处理机制如下：

首先，对报文中出现签名域（signature）之外的所有数据元采用key=value的形式按照名称排序，然后以&作为连接符拼接成待签名串。其次，对待签名串使用SHA-1算法做摘要，并转成16进制，再使用商户入网时银联提供的银联全渠道系统支付通讯RSA公钥证书对摘要和报文中的签名信息做签名验证操作。

# 9     加密机制 #

对于持卡人密码银联全渠道系统支付平台使用RSA公钥证书对ANSI X9.8带主帐号格式的PIN加密并做Base64编码后传输，以保障密码的安全性。依据商户可选配置，对于CVN2、有效期、卡号使用RSA公钥证书分别做加密并Base64处理。

对于敏感信息银行卡验证信息及身份信息部分内容，采用Base64编码后传输，以做数据屏蔽。

对于文件内容，使用DEFLATE压缩算法压缩后，Base64编码的方式传输，压缩编码后的内容参与签名摘要运算。

# 10        证书相关说明 #

## 10.1     概述 ##

1. 商户签名证书：商户接入银联支付后会收到两码，通过在CFCA网站下载pfx证书。此证书用于请求报文的签名。测试证书随开发包提供。

2. 商户的密码加密证书：商户会收到一个密码加密的公钥证书，此证书用于对银行卡密码的加密、cvn2、有效期及卡号等的加密。测试证书随开发包提供。

3. 商户的交易报文验证签名证书：验证银联支付返回的报文是否合法。测试证书随开发包提供。

## 10.2     证书下载及导出流程(ok) ##

### 10.2.1        证书下载流程 ###

1.     登入CFCA官网网址：[www.cfca.com.cn][]，点击“生产系统证书下载”；

2.     在生产证书下载选项中点击 à 证书下载；

3.     首次下载证书,请按照页面提示安装相应程序，以保证证书顺利下载；

4.     点击左侧“用户证书下载”，并点击“接受此协议”；

5.     输入CFCA提供的两码（用户参考号、用户授权码），制证方式默认，软件CSP默认，点击下

6.     完成下载操作后，页面会出现下载成功的提示。下载的证书自动存放在IE中。

### 10.2.2证书导出流程 ###

1. 打开浏览器，点选 工具 à Internet选项 à 内容 à 证书；

2. 以商户号：700000000000001为例说明整个导出流程

在个人证书中找到相对应的证书，点选导出；

** **

3.跳出证书导出向导对话框，点击下一步；

** **

4.      选择导出私钥（如需要在服务网站上传证书公钥，请选择第二个选项以下载公钥证书，后续操作选择默认方式，再选择路径导出），点击下一步；

5.      导出文件格式默认点击下一步；

6.      键入证书私钥，建议不要超过6位；

7.      指定导出证书的文件名，并选择目录存放证书，点击下一步；

8.      点击完成，证书导出成功。

# 11        开发包插件使用 #

插件包只是为了方便商户测试而提供的样例代码，商户可以根据自己网站的需要，按照技术文档编写,并非一定要使用该代码。代码仅供参考

## 11.1     JSP/JAVA ##

插件以JAR包的形式提供给商户，工程名称为upacp\_sdk\_java。

### 11.1.1        配置文件说明 ###

1.  log4j.properties:插件的日志机制使用log4j实现，可将提供的配置文件合并到项目的log4j配置中，并根据环境需要修改日志路径；

2. acp\_sdk.properties:测试环境参数配置文件（不含手机控件支付）

<table> 
 <tbody> 
 <tr> 
 <td style="background:#4F81BD"> 具体配置： </td> 
 </tr> 
 <tr> 
 <td> ######&nbsp; SDK 配置文件配置文件中日志和证书的存放路径根据实际情况配置，交易地址和证书根据测试环境、生产环境配套配置##### #SDK 日志目录配置 log.back.rootPath=d://log ##########################交易发送地址配############################# ######(以下配置为认证环境：入网测试环境用，生产环境配置见文档说明)####### ##前台交易请求地址 acpsdk.frontTransUrl=https://101.231.204.80:5000/gateway/api/frontTransReq.do ##&nbsp;app&nbsp;交易请求地址 ##&nbsp;acpsdk.appTransUrl=https://101.231.204.80:5000/gateway/api/appTransReq.do ##后台交易请求地址 acpsdk.backTransUrl=https://101.231.204.80:5000/gateway/api/backTransReq.do ##后台交易请求地址(若为有卡交易配置该地址) #acpsdk.cardTransUrl=https://101.231.204.80:5000/gateway/api/cardTransReq.do ##单笔查询请求地址 acpsdk.singleQueryUrl=https://101.231.204.80:5000/gateway/api/queryTrans.do ##批量交易请求地址 acpsdk.batchTransUrl=https://101.231.204.80:5000/gateway/api/batchTrans.do ##文件传输类交易地址 acpsdk.fileTransUrl=https://101.231.204.80:9080/ ########################签名证书配置################################ ######(以下配置为测试环境：入网测试环境用，生产环境配置见下述文档说明)####### ##签名证书路径 acpsdk.signCert.path=d:\\certs\\700000000000001_acp.pfx ##签名证书密码 acpsdk.signCert.pwd=000000 ##签名证书类型 acpsdk.signCert.type=PKCS12 ##########################加密证书配置################################ ##密码加密证书路径 acpsdk.encryptCert.path=d:\\certs\\encrypt.cer </td> 
 </tr> 
 </tbody> 
</table>

3.acp\_sdk.properties:生产环境参数配置文件

<table> 
 <tbody> 
 <tr> 
 <td style="background:#4F81BD"> 具体配置： </td> 
 </tr> 
 <tr> 
 <td> ##########################交易发送地址配############################# ######(以下配置为生产环境用)####### ##前台交易请求地址 acpsdk.frontTransUrl=https://gateway.95516.com/gateway/api/frontTransReq.do ##&nbsp;app&nbsp;交易请求地址 ##&nbsp;acpsdk.appTransUrl=https://gateway.95516.com /gateway/api/appTransReq.do ##后台交易请求地址 acpsdk.backTransUrl=https://gateway.95516.com/gateway/api/backTransReq.do ##后台交易请求地址(若为有卡交易配置该地址) #acpsdk.cardTransUrl=https://gateway.95516.com /gateway/api/cardTransReq.do ##单笔查询请求地址 acpsdk.singleQueryUrl=https://gateway.95516.com/gateway/api/queryTrans.do ##批量交易请求地址 acpsdk.batchTransUrl=https://gateway.95516.com/gateway/api/batchTrans.do ##文件传输类交易地址 acpsdk.fileTransUrl=https://filedownload.95516.com/ &nbsp;########################签名证书配置################################ ##签名证书路径（请拿到生产环境证书后修改签名路径、证书名称、证书密码） acpsdk.signCert.path=d:\\certs\\700000000000001_acp.pfx ##签名证书密码 acpsdk.signCert.pwd=123456 ##签名证书类型 acpsdk.signCert.type=PKCS12 ##########################加密证书配置################################ ##密码加密证书路径 acpsdk.encryptCert.path=d:\\certs\\encrypt.cer </td> 
 </tr> 
 </tbody> 
</table>

### 11.1.2        主要类和方法说明 ###

<table> 
 <tbody> 
 <tr> 
 <td style="background:#4F81BD"> 主要类与方法说明 </td> 
 </tr> 
 <tr> 
 <td style="background:#D3DFEE"> com.unionpay.acp.sdk.SDKUtil.java：主要负责组装报文、证书签名、发送报文、接收报文、验证签名、加密解密等操作，具体请查看代码。 </td> 
 </tr> 
 <tr> 
 <td> 方法：publicstatic String send(String url, Map&lt;String, String&gt; data, String encoding,intconnectionTimeout, intreadTimeout) 发送后台交易。 &nbsp; 方法：publicstaticboolean sign(Map&lt;String, String&gt; data, String encoding) 生成签名。 &nbsp; 方法：publicstaticboolean validate(Map&lt;String, String&gt; resData, String encoding) 验证签名。 &nbsp; 方法：publicstatic String coverMap2String(Map&lt;String, String&gt; data) 将Map形式的表单交易数据转换为key1=value1&amp;key2=value2的形式 &nbsp; 方法：publicstatic Map&lt;String, String&gt; coverResultString2Map(String result) 将形如key=value&amp;key=value的字符串转换为相应的Map对象 &nbsp; 方法：publicstatic String encryptPin(String card, String pwd, String encoding) 密码加密，输入参数依次为卡号、密码、字符集。 </td> 
 </tr> 
 </tbody> 
</table>

<table> 
 <tbody> 
 <tr> 
 <td style="background:#4F81BD"> 主要类与方法说明 </td> 
 </tr> 
 <tr> 
 <td style="background:#D3DFEE"> com.unionpay.acp.sdk.SDKConstants.java：常量类。 定义可能用到的各种常量和所有域名。 </td> 
 </tr> 
 </tbody> 
</table>

<table> 
 <tbody> 
 <tr> 
 <td style="background:#4F81BD"> 主要类与方法说明 </td> 
 </tr> 
 <tr> 
 <td style="background:#D3DFEE"> com.unionpay.acp.sdk.CertUtil.java： 证书操作工具类，主要是导入pfx、cer等证书与获取获取私钥、获取公钥操作。 </td> 
 </tr> 
 </tbody> 
</table>

<table> 
 <tbody> 
 <tr> 
 <td style="background:#4F81BD"> 主要类与方法说明 </td> 
 </tr> 
 <tr> 
 <td style="background:#D3DFEE"> com.unionpay.acp.sdk.SecureUtil.java主要负责报文的签名、验证签名及加密解密； 提供MD5、SHA-1以及RSA签名的方法类。 </td> 
 </tr> 
 </tbody> 
</table>

<table> 
 <tbody> 
 <tr> 
 <td style="background:#4F81BD"> 主要类与方法说明 </td> 
 </tr> 
 <tr> 
 <td style="background:#D3DFEE"> com.unionpay.acp.sdk.HttpClient.java 是通信类，具体请参考代码的说明。 提供和服务器通信的HTTP客户端类。 </td> 
 </tr> 
 <tr> 
 <td> 方法：publicint send(Map&lt;String, String&gt; data, String encoding) throwsException 将请求参数以HTTP表单的方式进行一次HTTP POST通信。 </td> 
 </tr> 
 </tbody> 
</table>

<table> 
 <tbody> 
 <tr> 
 <td style="background:#4F81BD"> Sample说明 </td> 
 </tr> 
 <tr> 
 <td style="background:#D3DFEE"> com.unionpay.acp.sdksample.front：包下为前台交易demo </td> 
 </tr> 
 <tr> 
 <td> 方法：com.unionpay.acp.sdksample.back：包下为后台交易demo 具体内容见DEMO代码中的注释和说明。 </td> 
 </tr> 
 </tbody> 
</table>

### 11.1.3        配置文件加载说明 ###

<table> 
 <tbody> 
 <tr> 
 <td style="background:#4F81BD"> 配置文件加载说明 </td> 
 </tr> 
 <tr> 
 <td style="background:#D3DFEE"> 1)&nbsp;&nbsp;&nbsp; acp_sdk.properties </td> 
 </tr> 
 <tr> 
 <td> i.&nbsp;&nbsp;&nbsp;&nbsp; 从classpath加载 SDKConfig.getConfig().loadPropertiesFromSrc(); ii.&nbsp;&nbsp;&nbsp; 从properties对象中加载 SDKConfig.getConfig().loadProperties(pro); iii.&nbsp;&nbsp; 从指定目录下加载rootPath不包含文件名 SDKConfig.getConfig().loadPropertiesFromPath(rootPath); </td> 
 </tr> 
 <tr> 
 <td style="background:#D3DFEE"> 2)&nbsp;&nbsp;&nbsp; log4j.properties:放在工程的classpath目录下，系统自动加载 </td> 
 </tr> 
 </tbody> 
</table>

## 11.2     PHP ##

插件按编码为gbk编写，工程名称为upacp\_sdk\_php，供系统集成。

openssl证书需下载使用 其中的php\_openssl.dll,ssleay32.dll,libeay32.dll3个文件拷到  windows/system32/文件夹下，在重启Apache服务

### 11.2.1      配置文件说明 ###

1. SDKConfig.php测试环境配置文件：具体配置项和说明如下；

<table> 
 <tbody> 
 <tr> 
 <td style="background:#4F81BD"> 具体配置： </td> 
 </tr> 
 <tr> 
 <td> ######&nbsp; SDK 配置文件配置文件中日志和证书的存放路径根据实际情况配置，交易地址和证书根据测试环境、生产环境配套配置##### ##########################交易发送地址配############################# ######(以下配置为认证环境：入网测试环境用，生产环境配置见文档说明)####### ##前台交易请求地址 const SDK_FRONT_TRANS_URL = 'https://101.231.204.80:5000/gateway/api/frontTransReq.do'; ##后台交易请求地址 const SDK_BACK_TRANS_URL = 'https://101.231.204.80:5000/gateway/api/backTransReq.do'; ##后台交易请求地址(若为有卡交易配置该地址) constSDK_Card_Request_Url = 'https://101.231.204.80:5000/gateway/api/cardTransReq.do'; ##单笔查询请求地址 const SDK_SINGLE_QUERY_URL = 'https://101.231.204.80:5000/gateway/api/queryTrans.do'; ##批量交易请求地址 const SDK_BATCH_TRANS_URL = 'https://101.231.204.80:5000/gateway/api/batchTrans.do'; ##文件传输类交易地址 const SDK_FILE_QUERY_URL = 'https://101.231.204.80:9080/'; ##APP交易地址 constSDK_App_Request_Url = 'https://101.231.204.80:5000/gateway/api/appTransReq.do'; ########################签名证书配置################################ ######(以下配置为测试环境：入网测试环境用，生产环境配置见下述文档说明)####### ##签名证书路径 const SDK_SIGN_CERT_PATH = 'D:/certs/PM_700000000000001_acp.pfx'; ##签名证书密码 const SDK_SIGN_CERT_PWD = '000000'; ##签名证书类型 acpsdk.signCert.type=PKCS12 ##验签 const SDK_VERIFY_CERT_PATH = 'D:/certs/verify_sign_acp.cer'; ##前台通知地址 (商户自行配置通知地址) const SDK_FRONT_NOTIFY_URL = 'http://127.0.0.1/upacp_sdk_php/demo/response.php'; // 后台通知地址 (商户自行配置通知地址) const SDK_BACK_NOTIFY_URL = 'http://127.0.0.1/upacp_sdk_php/demo/response.php'; //文件下载目录 const SDK_FILE_DOWN_PATH = 'd:/file/'; //日志 目录 const SDK_LOG_FILE_PATH = 'D:/logs/'; //日志级别 const SDK_LOG_LEVEL = 'INFO'; &nbsp; ##########################加密证书配置################################ ##密码加密证书路径 const SDK_ENCRYPT_CERT_PATH = 'D:/certs/encrypt.cer'; </td> 
 </tr> 
 </tbody> 
</table>

** **

2. SDKConfig.php ，生产测试环境配置文件：具体配置项和说明如下；

** **

<table> 
 <tbody> 
 <tr> 
 <td style="background:#4F81BD"> 具体配置： </td> 
 </tr> 
 <tr> 
 <td> ##########################交易发送地址配############################# ######(以下配置为生产环境用)####### ##前台交易请求地址 const SDK_FRONT_TRANS_URL = 'https://gateway.95516.com/gateway/api/frontTransReq.do'; ##后台交易请求地址 const SDK_BACK_TRANS_URL = 'https://gateway.95516.com/gateway/api/backTransReq.do'; ##后台交易请求地址(若为有卡交易配置该地址) constSDK_Card_Request_Url = 'https://gateway.95516.com/gateway/api/cardTransReq.do'; ##单笔查询请求地址 const SDK_SINGLE_QUERY_URL = 'https://gateway.95516.com/gateway/api/queryTrans.do'; ##批量交易请求地址 const SDK_BATCH_TRANS_URL = 'https://gateway.95516.com/gateway/api/batchTrans.do'; ##文件传输类交易地址 const SDK_FILE_QUERY_URL = 'https://filedownload.95516.com/'; ##APP交易地址 constSDK_App_Request_Url = 'https://gateway.95516.com/gateway/api/appTransReq.do'; &nbsp; ##前台通知地址 (商户自行配置通知地址) const SDK_FRONT_NOTIFY_URL = 'http://127.0.0.1/upacp_sdk_php/demo/response.php'; ##后台通知地址 (商户自行配置通知地址) const SDK_BACK_NOTIFY_URL = 'http://127.0.0.1/upacp_sdk_php/demo/response.php'; ##文件下载目录 const SDK_FILE_DOWN_PATH = 'd:/file/'; ##日志 目录 const SDK_LOG_FILE_PATH = 'D:/logs/'; ##日志级别 const SDK_LOG_LEVEL = 'INFO'; ########################签名证书配置################################ ##签名证书路径（请拿到生产环境证书后修改签名路径、证书名称、证书密码） const SDK_SIGN_CERT_PATH = 'D:/certs/PRO_700000000000001_acp.pfx'; ##签名证书密码 const SDK_SIGN_CERT_PWD = '000000'; ##签名证书类型 acpsdk.signCert.type=PKCS12 ##验签 const SDK_VERIFY_CERT_PATH = 'D:/certs/UPOP_VERIFY.cer'; ##验签证书路径 const SDK_VERIFY_CERT_PATH = 'D:/certs/'; ##########################加密证书配置################################ ##密码加密证书路径 const SDK_ENCRYPT_CERT_PATH = 'D:/certs/RSA2048_PROD_index_22.cer'; </td> 
 </tr> 
 </tbody> 
</table>

** **

### 11.2.2        主要类与方法说明 ###

<table> 
 <tbody> 
 <tr> 
 <td style="background:#4F81BD"> 主要类与方法说明 </td> 
 </tr> 
 <tr> 
 <td style="background:#D3DFEE"> upacp_sdk_php.gbk.common.php:负责将请求报文排序后转化为字符串、将字符串转为数组 解压、压缩、构建自动提交表单等 </td> 
 </tr> 
 <tr> 
 <td style="background:#D3DFEE"> function coverParamsToString($params) 功能: 将请求报文排序后转化为字符串 输入: 请求数组 输出: 排序后的 key1=val1&amp;key2=val2&amp;.... function coverStringToArray($str) 功能: 将字符串转为数组 输入: key1=val1&amp;key2=val2&amp;.... 输出: 数组元素 array(key1=&gt;val1,key2=&gt;val2...) &nbsp; function deal_params(&amp;$params) 功能: 处理返回报文 解码客户信息 输入: 客户信息 输出: 将客户信息组装成customerInfo项 &nbsp; function deflate_file(&amp;$params) 功能: 压缩文件 输入: 带有文件上传的请求报文 输出: 将上传文件压缩后组装进报文 &nbsp; function deal_file($params) 功能: 解压缩文件 输入: 带有文件下载的返回报文 输出: 处理文件内容并保存到指定目录下 &nbsp; function create_html($params, $action) 功能: 构造自动提交的表单 输入: 请求数组($params) ,请求的远程url 输出: 自动提交的form表单字符串 &nbsp; </td> 
 </tr> 
 <tr> 
 <td style="background:#4F81BD"> 主要类与方法说明 </td> 
 </tr> 
 <tr> 
 <td style="background:#D3DFEE"> upacp_sdk_php.gbk.httpClient.php:后台交易 客户端通信等 </td> 
 </tr> 
 <tr> 
 <td style="background:#D3DFEE"> &nbsp; httpClient.php function sendHttpRequest($params, $url) 功能: 后台交易 HttpClient通信 输入: 请数据,及远程通信url 输出: 后台交易响应信息 &nbsp; function getRequestParamString($params) 功能: 请求数据 urlencode处理后转为key=val&amp;...串 输入: 请求数组 输出: urlencode处理后的key=val&amp;...串 </td> 
 </tr> 
 </tbody> 
</table>

** **

<table> 
 <tbody> 
 <tr> 
 <td style="background:#4F81BD"> 主要类与方法说明 </td> 
 </tr> 
 <tr> 
 <td style="background:#D3DFEE"> upacp_sdk_php.gbk.secureUtil.php:负责签名，验签，加载证书，取公钥/私钥，加密卡号/cvn2/有效期等方法类 </td> 
 </tr> 
 <tr> 
 <td style="background:#D3DFEE"> secureUtil.php function sign(&amp;$params) 功能: 请求数据签名 输入: 请求数组 输出: 带签名的请求数组 &nbsp; function verify($params) 功能: 验签 输入: 返回报文 输出: 成功/失败 &nbsp; function getPulbicKeyByCertId($certId) 功能: 根据证书ID 加载 证书 输入: 证书ID 输出: 证书公钥信息 &nbsp; function getCertId($cert_path) 功能: 取私钥证书ID 输入: 私钥证书路径 输出: 证书ID &nbsp; function getCertIdByCerPath($cert_path) 功能: 取公钥证书ID 输入: 公钥证书路径 输出: 证书ID &nbsp; &nbsp; function getSignCertId() 功能: 取签名证书ID 输入: 签名证书路径 输出: 证书ID &nbsp; function getPublicKey($cert_path) 功能: 获取证书公钥 输入: 证书路径 输出: 公钥 &nbsp; function getPrivateKey($cert_path) 功能: 获取证书私钥 输入: 证书路径 输出: 私钥 &nbsp; function encryptPan($pan) 功能: 加密 卡号 输入: 卡号 输出: 加密后卡号 &nbsp; function encryptPin($pan, $pwd) 功能: pin 加密 输入: 卡号,密码 输出: 加密后密码 &nbsp; function encryptCvn2($cvn2) 功能: cvn2 加密 输入: cvn2 输出: 加密后cvn2 &nbsp; function encryptDate($certDate) 功能: 有效期 加密 输入: 有效期 输出: 加密后有效期 &nbsp; </td> 
 </tr> 
 </tbody> 
</table>

** **

<table> 
 <tbody> 
 <tr> 
 <td style="background:#4F81BD"> 主要类与方法说明 </td> 
 </tr> 
 <tr> 
 <td style="background:#D3DFEE"> upacp_sdk_php.gbk.PublicEncrypte.php:密码加密 </td> 
 </tr> 
 <tr> 
 <td style="background:#D3DFEE"> upacp_sdk_php.gbk.PinBlock.php:密码转pin </td> 
 </tr> 
 <tr> 
 <td style="background:#D3DFEE"> upacp_sdk_php.gbk.log.class.php:日志类 </td> 
 </tr> 
 </tbody> 
</table>

## 11.3     ASP.NET ##

插件.net Framework4.0环境以上编写，ICSharpCode.SharpZipLib手动添加，引用工程名称为upacp\_sdk\_php，供系统集成。

### 11.3.1        配置文件说明 ###

1.  Web.config:入网测试环境参数配置文件

<table> 
 <tbody> 
 <tr> 
 <td style="background:#4F81BD"> 具体配置： </td> 
 </tr> 
 <tr> 
 <td> ######&nbsp; SDK 配置文件配置文件中日志和证书的存放路径根据实际情况配置，交易地址和证书根据测试环境、生产环境配套配置##### ##########################交易发送地址配############################# ######(以下配置为认证环境：入网测试环境用，生产环境配置见文档说明)####### ##前台交易请求地址 &lt;add key="sdk.frontTransUrl" value="https://101.231.204.80:5000/gateway/api/frontTransReq.do" /&gt; ##后台交易请求地址 &lt;add key="sdk.backTransUrl" value="https://101.231.204.80:5000/gateway/api/backTransReq.do" /&gt; ##后台交易请求地址(若为有卡交易配置该地址) &lt;add key="sdk.cardRequestUrl" value="https://101.231.204.80:5000/gateway/api/cardTransReq.do" /&gt; ##批量交易请求地址 &lt;add key="sdk.batTransUrl" value="https://101.231.204.80:5000/gateway/api/batchTrans.do" /&gt; ##查询地址 &lt;add key="sdk.singleQueryUrl" value="https://101.231.204.80:5000/gateway/api/queryTrans.do" /&gt; ##文件传输类交易地址 &lt;add key="sdk.fileTransUrl" value="https://101.231.204.80:9080/" /&gt; ##APP交易地址 &lt;add key="sdk.appRequestUrl" value="https://101.231.204.80:5000/gateway/api/appTransReq.do" /&gt; ########################签名证书配置################################ ######(以下配置为测试环境：入网测试环境用，生产环境配置见下述文档说明)####### ##签名证书路径 &lt;add key="sdk.signCert.path" value="d:\certs\PM_700000000000001_acp.pfx" /&gt; ##签名证书密码 &lt;add key="sdk.signCert.pwd" value="000000" /&gt; ##签名证书类型 &lt;add key="sdk.signCert.type" value="PKCS12" /&gt; ##验签 &lt;add key="sdk.validateCert.dir" value="d:\certs\" /&gt; ##########################加密证书配置################################ ##密码加密证书路径 &lt;add key="sdk.encryptCert.path" value="d:\certs\encrypt.cer" /&gt; </td> 
 </tr> 
 </tbody> 
</table>

** **

**2.**  Web.config: 生产环境参数配置文件

<table> 
 <tbody> 
 <tr> 
 <td style="background:#4F81BD"> 具体配置： </td> 
 </tr> 
 <tr> 
 <td> ##########################交易发送地址配############################# ######(以下配置为生产环境用)####### ##前台交易请求地址 &lt;add key="sdk.frontTransUrl" value="https://gateway.95516.com/gateway/api/frontTransReq.do" /&gt; ##后台交易请求地址 &lt;add key="sdk.backTransUrl" value="https://gateway.95516.com/gateway/api/backTransReq.do" /&gt; ##后台交易请求地址(若为有卡交易配置该地址) &lt;add key="sdk.cardRequestUrl" value="https://gateway.95516.com/gateway/api/cardTransReq.do" /&gt; ##单笔查询请求地址 &lt;add key="sdk.singleQueryUrl" value="https://gateway.95516.com/gateway/api/queryTrans.do" /&gt; ##批量交易请求地址 &lt;add key="sdk.batTransUrl" value="https://gateway.95516.com/gateway/api/batchTrans.do" /&gt; ##文件传输类交易地址 &lt;add key="sdk.fileTransUrl" value="https://filedownload.95516.com/" /&gt; ##APP交易地址 &lt;add key="sdk.appRequestUrl" value="https://gateway.95516.com/gateway/api/appTransReq.do" /&gt; ########################签名证书配置################################ ##签名证书路径（请拿到生产环境证书后修改签名路径、证书名称、证书密码） &lt;add key="sdk.signCert.path" value="d:\certs\PRO_700000000000001_acp.pfx" /&gt; ##签名证书密码 &lt;add key="sdk.signCert.pwd" value="000000" /&gt; ##签名证书类型 acpsdk.signCert.type=PKCS12 ##验签 &lt;add key="sdk.validateCert.dir" value="d:\certs\" /&gt; ##########################加密证书配置################################ ##密码加密证书路径 &lt;add key="sdk.encryptCert.path" value="d:\certs\RSA2048_PROD_index_22.cer" /&gt; </td> 
 </tr> 
 </tbody> 
</table>

### 11.3.2        主要类和方法说明 ###

<table> 
 <tbody> 
 <tr> 
 <td style="background:#4F81BD"> 主要类与方法说明 </td> 
 </tr> 
 <tr> 
 <td style="background:#D3DFEE"> com.unionpay.acp.sdk.SDKConfig.cs:负责读取web.config </td> 
 </tr> 
 <tr> 
 <td style="background:#D3DFEE"> //功能：读取配置文件获取签名证书路径 private static string signCertPath = config.AppSettings.Settings["sdk.signCert.path"].Value; //功能：读取配置文件获取签名证书密码 private static string signCertPwd = config.AppSettings.Settings["sdk.signCert.pwd"].Value; //功能：读取配置文件获取验签目录 private static string validateCertDir = config.AppSettings.Settings["sdk.validateCert.dir"].Value; //功能：加密公钥证书路径 private static string encryptCert = config.AppSettings.Settings["sdk.encryptCert.path"].Value; //功能：有卡交易路径;&nbsp; private static string cardRequestUrl = config.AppSettings.Settings["sdk.cardRequestUrl"].Value; //功能：app交易路径;&nbsp; private static string appRequestUrl = config.AppSettings.Settings["sdk.appRequestUrl"].Value; //功能：读取配置文件获取交易查询地址&nbsp; private static string singleQueryUrl = config.AppSettings.Settings["sdk.singleQueryUrl"].Value; //功能：读取配置文件获取文件传输类交易地址 private static string fileTransUrl = config.AppSettings.Settings["sdk.fileTransUrl"].Value;&nbsp; 功能：读取配置文件获取前台交易地址 private static string frontTransUrl = config.AppSettings.Settings["sdk.frontTransUrl"].Value; 功能：读取配置文件获取后台交易地址 private static string backTransUrl = config.AppSettings.Settings["sdk.backTransUrl"].Value; //功能：读取配批量交易地址 private static string batTransUrl = config.AppSettings.Settings["sdk.batTransUrl"].Value; &nbsp; </td> 
 </tr> 
 </tbody> 
</table>

<table> 
 <tbody> 
 <tr> 
 <td style="background:#4F81BD"> 主要类与方法说明 </td> 
 </tr> 
 <tr> 
 <td style="background:#D3DFEE"> com.unionpay.acp.sdk.SDKUtil.cs：主要负责组装报文、证书签名、发送报文、接收报文、验证签名、加密解密等操作，具体请查看代码。 </td> 
 </tr> 
 <tr> 
 <td style="background:#D3DFEE"> 获取签名。 public static bool Sign(Dictionary&lt;string, string&gt; data, Encoding encoder) </td> 
 </tr> 
 <tr> 
 <td> 验证签名 public static bool Validate(Dictionary&lt;string, string&gt; data, Encoding encoder) </td> 
 </tr> 
 <tr> 
 <td style="background:#D3DFEE"> 组装报文 public static string CreateAutoSubmitForm(string url, Dictionary&lt;string, string&gt; data, Encoding encoder) </td> 
 </tr> 
 <tr> 
 <td> 将Dictionary内容排序后输出为键值对字符串,供打印报文使用 &nbsp;public static string PrintDictionaryToString(Dictionary&lt;string, string&gt; data) </td> 
 </tr> 
 <tr> 
 <td style="background:#D3DFEE"> 将形如key=value&amp;key=value的字符串转换为相应的Dictionary对象 public static Dictionary&lt;string, string&gt; CoverstringToDictionary(string data) </td> 
 </tr> 
 <tr> 
 <td> pinblock 16进制计算 public static string printHexString(byte[] b) </td> 
 </tr> 
 <tr> 
 <td> 密码加密，输入参数依次为卡号、密码、字符集 Publicstatic string encryptPin(string card, string pwd, string encoding) </td> 
 </tr> 
 <tr> 
 <td> 数据加密，输入参数依次为数据、字符集 Publicstatic string encryptData(string data，string encoding) </td> 
 </tr> 
 </tbody> 
</table>

<table> 
 <tbody> 
 <tr> 
 <td style="background:#4F81BD"> 主要类与方法说明 </td> 
 </tr> 
 <tr> 
 <td style="background:#D3DFEE"> com.unionpay.acp.sdk.CertUtil.cs： 证书操作工具类，主要是导入pfx证书与获取获取私钥操作。 </td> 
 </tr> 
 <tr> 
 <td> 获取签名证书私钥 public static RSACryptoServiceProvider GetSignProviderFromPfx() </td> 
 </tr> 
 <tr> 
 <td> 获取签名证书的证书序列号 &nbsp;public static string GetSignCertId() </td> 
 </tr> 
 <tr> 
 <td> 通过证书id，获取验证签名的证书 public static RSACryptoServiceProvider GetValidateProviderFromPath(string certId) </td> 
 </tr> 
 </tbody> 
</table>

<table> 
 <tbody> 
 <tr> 
 <td style="background:#4F81BD"> 主要类与方法说明 </td> 
 </tr> 
 <tr> 
 <td style="background:#D3DFEE"> com.unionpay.acp.sdk.SecureUtil.cs主要负责报文的软签名、验证签名、加密； 压缩、解压、Base64编码/解码,pinblock计算等提供SHA-1及RSA的方法类。 </td> 
 </tr> 
 <tr> 
 <td> 摘要计算 </td> 
 </tr> 
 <tr> 
 <td> &nbsp;public static byte[] Sha1X16(string dataStr, Encoding encoding) </td> 
 </tr> 
 <tr> 
 <td> 软签名 &nbsp;public static byte[] SignBySoft(RSACryptoServiceProvider provider, byte[] data) </td> 
 </tr> 
 <tr> 
 <td> 验证签名 &nbsp;public static bool ValidateBySoft(RSACryptoServiceProvider provider, byte[] base64DecodingSignStr, byte[] srcByte) </td> 
 </tr> 
 <tr> 
 <td> Base64编码 public static string EncodeBase64(Encoding encode, string source) </td> 
 </tr> 
 <tr> 
 <td> Base64解码 &nbsp;public static string DecodeBase64(Encoding encode, string result) </td> 
 </tr> 
 <tr> 
 <td> Inflater解压缩 public static byte[] inflater(byte[] inputByte) </td> 
 </tr> 
 <tr> 
 <td> deflater压缩 &nbsp;public static byte[] deflater(byte[] inputByte) </td> 
 </tr> 
 <tr> 
 <td> 密码计算 private static byte[] pin2PinBlock(string aPin) </td> 
 </tr> 
 <tr> 
 <td> 获取卡号密码pinblock计算 public static byte[] pin2PinBlockWithCardNO(string aPin, string aCardNO) </td> 
 </tr> 
 <tr> 
 <td> &nbsp;卡号计算 private static byte[] formatPan(string aPan) </td> 
 </tr> 
 <tr> 
 <td> 加密 public static byte[] encryptedData(byte[] encData) </td> 
 </tr> 
 </tbody> 
</table>

<table> 
 <tbody> 
 <tr> 
 <td style="background:#4F81BD"> 主要类与方法说明 </td> 
 </tr> 
 <tr> 
 <td style="background:#D3DFEE"> com.unionpay.acp.sdk.HttpClient.cs 是通信类，具体请参考代码的说明。 提供和服务器通信的HTTP客户端类。 </td> 
 </tr> 
 <tr> 
 <td style="background:#D3DFEE"> 将请求参数以HTTP表单的方式进行一次HTTP POST通信。 Publicint Send(Dictionary&lt;string, string&gt;sParaTemp, Encoding encoding) </td> 
 </tr> 
 </tbody> 
</table>

# 12        常见问题问答 #

**Q：如何获取测试商户号与测试证书？**

A：测试环境申请测试用户后点击“我的测试>测试参数”中查看商户号，并点击下载测试证书，注册地址：[https://open.unionpay.com/ajweb/register][https_open.unionpay.com_ajweb_register]，生产环境请联系业务部门，具体联系方式如下：

发送邮件至： operation@unionpay.com进行业务申请和咨询，银联有专门的人员进行处理。

其他专项服务：请见《业务运营服务指引（商户） 》日常业务运营服务。

**Q：如何签名？**

A：对报文中出现签名域（signature）之外的所有数据元采用key=value的形式按照名称排序，然后以&作为连接符拼接成待签名串。其次，对待签名串使用SHA-1算法做摘要，并转成16进制，再使用银联颁发给商户的商户RSA私钥证书对摘要做签名操作（签名时算法选择SHA-1）。最后，对签名做Base64编码，将编码后的签名串放在签名（signature）表单域里和其他表单域一起通过HTTP Post的方式传输给银联全渠道系统支付平台。

**Q：报文域中frontUrl和backUrl要填什么？**

A:frontUrl和backUrl为报文上送要素**，**银联系统将前台通知报文返回到报文中的frontUrl地址，将后台通知报文返回到报文中的backUrl地址。

**Q：如何获取与配置银联入网测试环境地址？**

A : 可参见11章节测试环境参数配置，配置文件可在开发包中找到（开发包获取地址：https://open.unionpay.com/ajweb/help/file/）。具体接入地址如下：

<table> 
 <tbody> 
 <tr> 
 <td colspan="2" style="background:#4F81BD"> 银联入网测试环境地址： </td> 
 </tr> 
 <tr> 
 <td style="background:#D3DFEE"> 前台交易请求地址 </td> 
 <td style="background:#D3DFEE"> https://101.231.204.80:5000/gateway/api/frontTransReq.do </td> 
 </tr> 
 <tr> 
 <td> 后台交易请求地址（无卡） </td> 
 <td> https://101.231.204.80:5000/gateway/api/backTransReq.do </td> 
 </tr> 
 <tr> 
 <td style="background:#D3DFEE"> 后台交易请求地址（有卡） </td> 
 <td style="background:#D3DFEE"> https://101.231.204.80:5000/gateway/api/cardTransReq.do </td> 
 </tr> 
 <tr> 
 <td> 单笔查询请求地址 </td> 
 <td> https://101.231.204.80:5000/gateway/api/queryTrans.do </td> 
 </tr> 
 <tr> 
 <td style="background:#D3DFEE"> 批量交易请求地址 </td> 
 <td style="background:#D3DFEE"> https://101.231.204.80:5000/gateway/api/batchTrans.do </td> 
 </tr> 
 <tr> 
 <td> 文件传输类交易地址 </td> 
 <td> https://101.231.204.80:9080/ </td> 
 </tr> 
 <tr> 
 <td style="background:#D3DFEE"> APP交易请求地址 </td> 
 <td style="background:#D3DFEE"> https://101.231.204.80:5000/gateway/api/appTransReq.do </td> 
 </tr> 
 </tbody> 
</table>

**Q：银联全渠道系统商户接入生产环境地址？**

A : 可参见11章节生产环境参数配置，配置文件可在开发包中找到（开发包获取地址：https://open.unionpay.com/ajweb/help/file/）。将配置文件中测试地址修改为如下地址：

<table> 
 <tbody> 
 <tr> 
 <td colspan="2" style="background:#4F81BD"> 银联入网测试环境地址： </td> 
 </tr> 
 <tr> 
 <td style="background:#D3DFEE"> 前台交易请求地址 </td> 
 <td style="background:#D3DFEE"> https://gateway.95516.com/gateway/api/frontTransReq.do </td> 
 </tr> 
 <tr> 
 <td> 后台交易请求地址（无卡） </td> 
 <td> https://gateway.95516.com/gateway/api/backTransReq.do </td> 
 </tr> 
 <tr> 
 <td style="background:#D3DFEE"> 后台交易请求地址（有卡） </td> 
 <td style="background:#D3DFEE"> https://gateway.95516.com/gateway/api/cardTransReq.do </td> 
 </tr> 
 <tr> 
 <td> 单笔查询请求地址 </td> 
 <td> https://gateway.95516.com/gateway/api/queryTrans.do </td> 
 </tr> 
 <tr> 
 <td style="background:#D3DFEE"> 批量交易请求地址 </td> 
 <td style="background:#D3DFEE"> https://gateway.95516.com/gateway/api/batchTrans.do </td> 
 </tr> 
 <tr> 
 <td> 文件传输类交易地址 </td> 
 <td> https://filedownload.95516.com/ </td> 
 </tr> 
 <tr> 
 <td style="background:#D3DFEE"> APP交易请求地址 </td> 
 <td style="background:#D3DFEE"> https://gateway.95516.com /gateway/api/appTransReq.do </td> 
 </tr> 
 </tbody> 
</table>

**Q：商户接收到银联的前台通知和后台通知，以哪个为准？**

A：交易状态请以后台通知结果为准。银联系统会将后台通知结果以post的方式发送到报文中backUrl后台通知地址上，如商户未收到通知，系统会持续发送，如发送成功则不再发送，5次通知失败则不再发送，失败交易则不发送。

后台通知中，只要是非通信类错误（如通信超时，无法解析域名，没有路由等），都认为商户已经收到，不会进行重发。如果商户因为非通信类问题没有及时收到应答（比如应用切换等情况），或者收到应答时处理失败（处理逻辑的验证应该在测试环境下已经验证通过），商户应该对没有及时收到应答的交易通过查询接口来查询该交易的状态。具体参见第6章节。

**Q：上午做的交易，下午做撤销会报非当日交易不能撤销？**

A：测试环境的日切时间在下午1点半，早上的交易会归为前一日，下午的交易才是当日交易。

**Q：如果调用数次查询接口后，一直得到处理中状态，该怎么办？**

A：对于网银支付模式与非网银支付模式描述如下：

网银支付模式：跳转到银行后，订单状态为正在处理中。查询的结果为正在处理中。等银行有响应的时候，银联全渠道系统会根据银行的应答，修改订单状态为成功或失败。如用户在网银页面直接关闭浏览器，查询的结果则一直为处理中。若超过1小时，查询结果状态仍为处理中，一般可认为是用户关闭了浏览器，可当作失败处理。若产生单边账，可以第二天通过对账退还金额给用户。

非网银支付模式：银联全渠道系统会控制超时时间，一般用户支付2分钟后会有明确的状态，查询的结果不是成功就是失败，失败的交易允许用户重新支付，即如用户1点支付的时候失败，1点05分再次支付成功，则商户如果1点03分查询的时候结果为交易失败，1点06分查询的时候结果为成功。

**Q：消费撤销和退货有何不同？**

A：当天的交易可以执行消费撤销，消费撤销只能全额。

当天或隔天的交易都可以做退货，退货可以进行多次退货，每次金额小于原始金额，订单退款总金额不能大于此订单原始金额。

**Q：标准网关支付跳转银联页面HTTP400报错是什么原因？**

A：银联全渠道系统对报文校验较为严格，对未定义的报文域会提示http400报错，请核对产品接口规范文档（https://open.unionpay.com/ajweb/help?id=74&level=0&from=1）中的报文域。

**Q：什么是全渠道支付平台？**

A：全渠道支付平台是中国银联全渠道接入支付平台的简称，支持移动、互联网等渠道的收单业务，包含互联网支付产品（银联在线支付、预授权支付、B2B对公支付、跨境支付、无跳转支付）、移动终端渠道产品（手机安全支付控件、WAP页面支付、平板电脑（iPad）网关支付、预授权支付、跨境支付、无跳转支付（手机端暂无））、后台模式产品（ 订购、 代收、代付）。

**Q：银联全渠道入网测试的账号（卡号）是什么？**

A：接入银联全渠道入网测试环境需要使用银联提供的测试卡进行交易，当前仅提供两张可供测试的卡片，一张B2B企业网银的虚拟卡片，具体账号信息如下：

<table> 
 <tbody> 
 <tr> 
 <td style="background:#4F81BD"> 测试卡号 </td> 
 </tr> 
 <tr> 
 <td style="background:#D3DFEE"> 平安银行借记卡：6216261000000000018 证件号：341126197709218366 手机号：13552535506 密码：123456 姓名：全渠道 </td> 
 </tr> 
 <tr> 
 <td> 平安银行贷记卡：6221558812340000 姓名：互联网 证件号：341126197709218366 手机号：13552535506 cvn2:123 有效期：1711 </td> 
 </tr> 
 <tr> 
 <td style="background:#D3DFEE"> B2B企业网银农行虚拟卡 卡号：123456789001 密码：789001 </td> 
 </tr> 
 </tbody> 
</table>

**Q：银联全渠道相关接口文档在哪里获取？**

A：由银联提供的全渠道相关文档可在商户服务网站下载（https://merchant.unionpay.com/portal/pages/login/download.jsp?locale=zh\_CN），也可以在自助化测试平台首页 > 帮助中心 >下载（https://open.unionpay.com/ajweb/help/file）中获取。

[www.cfca.com.cn]: http://www.cfca.com.cn/
[https_open.unionpay.com_ajweb_register]: https://open.unionpay.com/ajweb/register