中國銀聯股份有限公司規範性文件

中國銀聯股份有限公司 釋出

中國銀聯全渠道系統商戶接入

測試指引-銀聯閘道器支付產品

1.0.0

2014-7-03

2014-7-03

初稿

1.0.1

2014-11-04

2014-11-05

修改文件格式，新增測試地址與測試卡號等資訊

參與方描述

商戶

指加入銀聯網路，與銀聯簽訂《銀聯卡無卡支付業務合作協議》等協議開展銀聯無卡支付以及行業類應用業務的商戶。

收單機構

指加入銀聯網路，與銀聯簽訂《銀聯卡無卡支付業務合作協議》開展銀聯無卡支付收單業務的境內成員機構。

術語

解釋

請求

通過 HTTP/HTTPS協議把需要傳輸的資料傳送給接收方的過程。

應答

通過 HTTP/HTTPS協議把需要傳輸的資料返回給接收方的過程。

後臺通知

伺服器後臺通知。中國銀聯全渠道系統根據得到的資料處理完成後，全渠道系統主動發起通知給商戶的網站，同時攜帶處理完成的結果資訊反饋給商戶網站。

前臺類交易

主要指使用者需要參與互動的支付類交易，包括消費、預授權/擔保消費交易。

後臺類交易

主要指使用者不需要參與互動，由商戶後續發起的交易，包括消費撤銷、退貨、預授權撤銷、預授權完成、預授權完成撤銷等交易。

全渠道系統/ACP

中國銀聯全渠道系統，是整合了銀聯線上和銀聯移動支付功能的新交易處理系統。

必測

選測

收單機構接入

商戶接入（接入產品為除無跳轉支付、後臺直接支付、代收和便民繳費以外的其他產品）

商戶接入（接入產品為無跳轉支付、後臺直接支付、代收和便民繳費）

必測

選測

收單機構可聯絡銀聯服務專員，並且在提交了入網申請後銀聯服務專員會主動聯絡商定視窗並提供測試支援服務

商戶可傳送郵件到[email protected]郵箱（郵件標題為：商戶號+商戶名稱+聯絡QQ），提供商戶號和聯絡QQ，銀聯測試服務專員會將商戶介面人的聯絡QQ加入到銀聯統一服務QQ中提供支援服務（商戶也可以通過服務電話021-38929999-2049來提供自己的商戶號和聯絡QQ）

銀聯市場服務代表在為商戶提交了入網申請後，會有銀聯服務專員主動聯絡（一般為QQ）商定聯調視窗並提供測試支援服務

測試卡號

平安銀行借記卡：6216261000000000018
證件號：341126197709218366
手機號：13552535506
密碼：123456

姓名：全渠道

平安銀行貸記卡：6221558812340000

姓名：網際網路

證件號：341126197709218366
手機號：13552535506
cvn2:123

有效期：1711

序號

介面名稱

功能說明

交易模式

1

消費類交易（前臺類）

持卡人進支付時，由銀聯或髮卡行展示支付頁面，引導持卡人完成後續支付的交易。

前臺資金類交易

2

消費撤銷類交易

指因人為原因而撤銷已完成的消費；消費撤銷必須是撤銷CUPS當日當批的消費

後臺資金類交易

3

退貨類交易

對於已結算的消費交易，通過該交易發起退款交易。

後臺資金類交易

4

交易狀態查詢類交易

對未收到應答的或交易狀態未知的交易，可通過該交易進行查詢。

查詢類交易

5

檔案傳輸類交易

聯機下載對賬檔案等檔案下載類交易

後臺非資金交易

6

預授權類交易

預授權交易用於受理方向持卡人的髮卡方確認交易許可。受理方將預估的消費金額作為預授權金額，傳送給持卡人的髮卡方。

前臺或後臺資金類交易

7

授權撤銷類交易

對已成功的預授權交易，在結算前使用該交易進行取消。

後臺資金類交易

8

授權完成類交易

對已批准的預授權交易，用該交易進行支付結算；

後臺資金類交易

9

授權完成撤銷類交易

預授權完成撤銷交易必須是對原始預授權完成交易的全額撤銷。預授權完成撤銷後的預授權仍然有效。

後臺資金類交易

10

餘額查詢

後臺非資金類交易

11

電子現金非指定賬戶圈存

後臺資金類交易

12

電子現金指定賬戶圈存

後臺資金類交易

13

圈存指令碼通知

後臺資金類交易

14

IC卡離線消費通知

後臺資金類交易

注意：

1.     每個交易需要的報文要素是不一樣的，具體每個交易需要的要求，請參考開發包中介面規範文件；

2.     圖1-3中第4步中的應答僅代表該筆後臺請求交易已經受理，不代表全部處理成功；是否處理成功，需通過接受後臺通知或者發起“交易狀態查詢交易”進行查詢；

3.     第5步後臺應答返回的URL為請求報文中的“backUrl”欄位指定的URL。

具體配置：

######  SDK 配置檔案配置檔案中日誌和證書的存放路徑根據實際情況配置，交易地址和證書根據測試環境、生產環境配套配置#####

#SDK 日誌目錄配置

log.back.rootPath=d://log

##########################交易傳送地址配#############################

######(以下配置為認證環境：入網測試環境用，生產環境配置見文件說明)#######

##前臺交易請求地址

acpsdk.frontTransUrl=https://101.231.204.80:5000/gateway/api/frontTransReq.do

## app 交易請求地址

## 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

具體配置：

##########################交易傳送地址配#############################

######(以下配置為生產環境用)#######

##前臺交易請求地址

acpsdk.frontTransUrl=https://gateway.95516.com/gateway/api/frontTransReq.do

## app 交易請求地址

## 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/

 ########################簽名證書配置################################

##簽名證書路徑（請拿到生產環境證書後修改簽名路徑、證書名稱、證書密碼）

acpsdk.signCert.path=d:\\certs\\700000000000001_acp.pfx

##簽名證書密碼

acpsdk.signCert.pwd=123456

##簽名證書型別

acpsdk.signCert.type=PKCS12

##########################加密證書配置################################

##密碼加密證書路徑

acpsdk.encryptCert.path=d:\\certs\\encrypt.cer

主要類與方法說明

com.unionpay.acp.sdk.SDKConfig.java:負責讀取acp_sdk.properties及設定引數。

方法：public void loadPropertiesFromSrc()

從標準CLASS類路徑下LOAD配置檔案。

方法：public void loadPropertiesFromPath(String rootPath)

從標準CLASS類路徑下LOAD配置檔案。

方法：public void loadProperties(Properties pro)

使用傳入的Properties物件LOAD配置。

主要類與方法說明

com.unionpay.acp.sdk.SDKUtil.java：主要負責組裝報文、證書籤名、傳送報文、接收報文、驗證簽名、加密解密等操作，具體請檢視程式碼。

方法：publicstatic String send(String url, Map<String, String> data, String encoding,intconnectionTimeout, intreadTimeout)

傳送後臺交易。

方法：publicstaticboolean sign(Map<String, String> data, String encoding)

生成簽名。

方法：publicstaticboolean validate(Map<String, String> resData, String encoding)

驗證簽名。

方法：publicstatic String coverMap2String(Map<String, String> data)

將Map形式的表單交易資料轉換為key1=value1&key2=value2的形式

方法：publicstatic Map<String, String> coverResultString2Map(String result)

將形如key=value&key=value的字串轉換為相應的Map物件

方法：publicstatic String encryptPin(String card, String pwd, String encoding)

密碼加密，輸入引數依次為卡號、密碼、字符集。

主要類與方法說明

com.unionpay.acp.sdk.SDKConstants.java：常量類。

定義可能用到的各種常量和所有域名。

主要類與方法說明

com.unionpay.acp.sdk.CertUtil.java： 證書操作工具類，主要是匯入pfx、cer等證書與獲取獲取私鑰、獲取公鑰操作。

主要類與方法說明

com.unionpay.acp.sdk.SecureUtil.java主要負責報文的簽名、驗證簽名及加密解密；

提供MD5、SHA-1以及RSA簽名的方法類。

主要類與方法說明

com.unionpay.acp.sdk.HttpClient.java 是通訊類，具體請參考程式碼的說明。

提供和伺服器通訊的HTTP客戶端類。

方法：publicint send(Map<String, String> data, String encoding) throwsException

將請求引數以HTTP表單的方式進行一次HTTP POST通訊。

Sample說明

com.unionpay.acp.sdksample.front：包下為前臺交易demo

方法：com.unionpay.acp.sdksample.back：包下為後臺交易demo

具體內容見DEMO程式碼中的註釋和說明。

配置檔案載入說明

1)    acp_sdk.properties

i.     從classpath載入

SDKConfig.getConfig().loadPropertiesFromSrc();

ii.    從properties物件中載入

SDKConfig.getConfig().loadProperties(pro);

iii.   從指定目錄下載入rootPath不包含檔名

SDKConfig.getConfig().loadPropertiesFromPath(rootPath);

2)    log4j.properties:放在工程的classpath目錄下，系統自動載入

具體配置：

######  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';

##########################加密證書配置################################

##密碼加密證書路徑

const SDK_ENCRYPT_CERT_PATH = 'D:/certs/encrypt.cer';

具體配置：

##########################交易傳送地址配#############################

######(以下配置為生產環境用)#######

##前臺交易請求地址

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';

##前臺通知地址 (商戶自行配置通知地址)

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';

主要類與方法說明

upacp_sdk_php.gbk.common.php:負責將請求報文排序後轉化為字串、將字串轉為陣列

解壓、壓縮、構建自動提交表單等

function coverParamsToString($params)

功能: 將請求報文排序後轉化為字串

輸入: 請求陣列

輸出: 排序後的 key1=val1&key2=val2&....

function coverStringToArray($str)

功能: 將字串轉為陣列

輸入: key1=val1&key2=val2&....

輸出: 陣列元素 array(key1=>val1,key2=>val2...)

function deal_params(&$params)

功能: 處理返回報文 解碼客戶資訊

輸入: 客戶資訊

輸出: 將客戶資訊組裝成customerInfo項

function deflate_file(&$params)

功能: 壓縮檔案

輸入: 帶有檔案上傳的請求報文

輸出: 將上傳檔案壓縮後組裝進報文

function deal_file($params)

功能: 解壓縮檔案

輸入: 帶有檔案下載的返回報文

輸出: 處理檔案內容並儲存到指定目錄下

function create_html($params, $action)

功能: 構造自動提交的表單

輸入: 請求陣列($params) ,請求的遠端url

輸出: 自動提交的form表單字串

主要類與方法說明

upacp_sdk_php.gbk.httpClient.php:後臺交易 客戶端通訊等

httpClient.php

function sendHttpRequest($params, $url)

功能: 後臺交易 HttpClient通訊

輸入: 請資料,及遠端通訊url

輸出: 後臺交易響應資訊

function getRequestParamString($params)

功能: 請求資料 urlencode處理後轉為key=val&...串

輸入: 請求陣列

輸出: urlencode處理後的key=val&...串

主要類與方法說明

upacp_sdk_php.gbk.secureUtil.php:負責簽名，驗籤，載入證書，取公鑰/私鑰，加密卡號/cvn2/有效期等方法類

secureUtil.php

function sign(&$params)

功能: 請求資料簽名

輸入: 請求陣列

輸出: 帶簽名的請求陣列

function verify($params)

功能: 驗籤

輸入: 返回報文

輸出: 成功/失敗

function getPulbicKeyByCertId($certId)

功能: 根據證書ID 載入 證書

輸入: 證書ID

輸出: 證書公鑰資訊

function getCertId($cert_path)

功能: 取私鑰證書ID

輸入: 私鑰證書路徑

輸出: 證書ID

function getCertIdByCerPath($cert_path)

功能: 取公鑰證書ID

輸入: 公鑰證書路徑

輸出: 證書ID

function getSignCertId()

功能: 取簽名證書ID

輸入: 簽名證書路徑

輸出: 證書ID

function getPublicKey($cert_path)

功能: 獲取證書公鑰

輸入: 證書路徑

輸出: 公鑰

function getPrivateKey($cert_path)

功能: 獲取證書私鑰

輸入: 證書路徑

輸出: 私鑰

function encryptPan($pan)

功能: 加密 卡號

輸入: 卡號

輸出: 加密後卡號

function encryptPin($pan, $pwd)

功能: pin 加密

輸入: 卡號,密碼

輸出: 加密後密碼

function encryptCvn2($cvn2)

功能: cvn2 加密

輸入: cvn2

輸出: 加密後cvn2

function encryptDate($certDate)

功能: 有效期 加密

輸入: 有效期

輸出: 加密後有效期

主要類與方法說明

upacp_sdk_php.gbk.PublicEncrypte.php:密碼加密

upacp_sdk_php.gbk.PinBlock.php:密碼轉pin

upacp_sdk_php.gbk.log.class.php:日誌類

具體配置：

######  SDK 配置檔案配置檔案中日誌和證書的存放路徑根據實際情況配置，交易地址和證書根據測試環境、生產環境配套配置#####