开放平台文档中心

本开发文档的阅读对象为:具有一定开发能力，了解PHP、JAVA、.NET等开发语言的开发、维护或管理人员。

本文档定义CHINAPNR支付网关商户接入接口规范，提供接口报文参数说明、示例报文、信息安全解决方案，并给出相关问题说明等，以帮助商户技术人员接入，便于尽快投入使用。

版本号	更新说明	更新日期
V1.0	创建	2019.01.10

商户会员号

Chinapnr网关支付时提交的为商户会员号,并非商户号,会员号=商户号+"01"(如商户号为abc时，会员号为abc01)

商户接入Chinapnr网关支付时，调用API须遵循以下规则：

传输方式	为保证交易安全性，采用 HTTPS 传输
提交方式	采用 POST 方法提交
数据格式	HTTP KEY=VALUE 格式
字符编码	支持 UTF-8 字符编码
签名算法	商户生成签名字符串，现支持的签名算法类型为 RSA-SHA1
签名要求	请求和接收数据均需要校验签名

场景介绍

人民币收款接口，收款资金可以按商户要求结算至境外或境内银行账户。支持网银、微信扫码、支付宝扫码等支付方式。适用于PC端。

可参考人民币网关模拟下单

第一步：消费者击进入商户网页购物进行支付

图3.0 商户网页下单

第二步：商户调用跨境系统网关，消费者跳转到人民币网关页面。消费者选择支付方式和银行，发起支付。

注意：如果调用接口选择直连模式，即调用时直接指定bankId,则不会显示此网关页面，直接跳转到网银。

图3.1 调用人民币网关支付

第三步：消费者根据选择支付方式和银行跳转到银行页面，如网银支付-招商银行，消费者输入卡号密码等支付完成。

图3.2 网银完成支付

第四步：支付成功，商户后台得到支付成功的通知。并且Chinapnr返回商户页面，显示购买成功。该页面由商户自定义。

图3.3 返回商户页面

概述

本文档展示了如何从零开始，与Chinapnr跨境系统网关对接的流程。

第一步：获取账号信息

商户需与前端销售沟通开通测试账号或生产账号，并提供接受邮箱地址。
1-2个工作日内由开通组负责将开通的账号信息发送至商户邮箱。

第二步：配置密钥

开发者调用接口前需要先生成RSA密钥，RSA密钥包含私钥、公钥。生成密钥后在商户后台进行密钥配置，配置完成后可发起交易。详细步骤请参考《配置密钥》。

第三步：搭建和配置开发环境

下载示例代码Demo
为了帮助开发者调用开放接口，我们提供了示例代码下载，包含JAVA、PHP和.NET三语言版本，封装了签名&验签、HTTP接口请求等基础功能。请先下载对应语言版本的Demo并引入您的开发工程《Demo下载》。
将Demo运行成功，并将代码集成到您的项目中，记得修改商户号，终端号，和私钥证书。如生产环境，还需更换Chinapnr生产公钥证书。

调用流程

接口调用时序图：

图1.1

注意：为确保安全，商户在收到汇付查询结果通知后，务必先验证返回的签名字段。

概述

Chinapnr开放平台采用了 RSA 安全签名机制，开发者可以通过Chinapnr公钥验证消息来源，同时可使用自己的私钥对信息进行加密。RSA 算法及数字签名机制是Chinapnr平台与开发者网关安全通信的基础，若开发者不熟悉 RSA 及数字签名，请先查阅相关资料。

RSA 私钥及公钥生成

1. 生成 RSA 私钥及公钥，请详见“附录一:私钥公钥生成及范例”。生成的文件格式如：客户私钥private-rsa.pfx，客户公钥public-rsa.cer。

商户上传公钥

注意：

上传商户公钥前需先联系前端获取商户后台账号和密码，并将客户公钥public-rsa.cer文件前缀名称修改为商户号。如开通的商户号为10012159865，则证书修改为10012159865.cer上传。

商户平台登录地址测试环境 / 生产环境进入Platform Management菜单下Certificate Management菜单，转入如下界面:

图5.1 上传公钥

在证书管理，输入邮箱，点击Do Upload上传证书。页面提示上传成功，证书列表中可以查看新增证书，状态为1有效。

下载Chinapnr公钥

点击Download下载系统公钥用于接收跨境系统返回时验签。

图5.2 下载Chinapnr公钥

注意：

不同环境Chinapnr公钥证书需在不对环境的商户后台下载。

Chinapnr网关与开发者的通信主要由开发者主动调用Chinapnr网关接口(下文简称OpenAPI)实现。其中Chinapnr网关地址：
测试环境：https://hfgj.testpnr.com/pay/idAuth.htm
生产环境：https://global.chinapnr.com/pay/idAuth.htm

接口参数说明请参见《身份鉴权接口说明》

API请求

Chinapnr开放平台的OpenAPI调用采取POST方式（application/x-www-form-urlencoded），内容通过键值对（Key-Value）的形式作为参数传入。

请求示例：

id=32012500002313
name=张三
memberCode=10012159865
terminalId=IDCK001
orderId=20190114113505903
trxRef=4
trxProductCode=IDAUTH
trxProductAcceptance=null
trxPayType=null
operator=system
authNetId=null
extMap={idAuthGwOrder=GW4, source=IDCHECKGW}

在提交参数中需要对传入的数据进行签名组成signMsg字段，签名方法如下：

1.将所有非空参数（sign除外）按照signMsg签名串:

version={version}&signType={signType}&merchantAcctId={merchantAcctId}&terminalId={terminalId}&trxId={trxId}&idType={idType}&name={name}&idNumber={idNumber}

按顺序用&连接起来组成字符串,格式是:p1=v1&p2=v2。如：

version=1.0&signType=4&merchantAcctId=1001215986501&terminalId=0010001&trxId=20190114114257912&idType=1&name=张三&idNumber=321281000000000000

2.进行RSA签名后获得sign，再经过Base64编码，具体加签代码请详见Demo

注意：

没有值的参数无需传递,也无需包含到待签名数据中。
签名时将字符转化成字节流时指定的字符集UTF8。
根据HTTP协议要求，传递参数的值中如果存在特殊字符（如：&、@等），那么该值需要做URL Encoding，这样请求接收方才能接收到正确的参数。此时，待签名数据应该是原始值而不是encoding之后的值。例如:调用某接口需要对请求参数 email 进行数字签名,那么待签名数据应该是：email=test@abc.com,而不是 email=test%40abc.com。

返回结果

返回示例：

respCode:000000
result:S

调用Chinapnr开放平台接口后，Chinapnr会向开发者提交的pageUrl地址同步返回查询结果。为保证信息安全，会经Chinapnr私钥进行RSA加密，开发者收到消息后可通过ChinapnrRSA公钥进行解密。

1.将所有返回参数（signMsg除外）按照signMsg验签串按顺序拼接:

idNumber={idNumber}&idType={idType}&merchantAcctId={merchantAcctId}&name={name}&respCode={respCode}&respMsg={respMsg}&result={result}&terminalId={terminalId}&trxId={trxId}&version={version}

组成待验签字符串，如：

idNumber=321281000000000000&idType=1&merchantAcctId=1001215986501&name=张三&respCode=000000&result=S&terminalId=0010001&trxId=20190114143214310&version=1.0

2.将签名参数（signMsg）使用base64解码为字节码串

3.使用RSA的验签方法，通过签名字符串、签名参数（经过base64解码）及Chinapnr公钥验证签名。具体验签方法请详见Demo

查询完成后，Chinapnr会同步返回查询结果

接口返回参数说明请参见《身份鉴权接口说明》

查询结果通知

查询结果返回示例：

respCode:000000
result:S

查询结果通知的验签

1.将所有返回参数（signMsg除外）按照signMsg验签串按顺序拼接:

idNumber={idNumber}&idType={idType}&merchantAcctId={merchantAcctId}&name={name}&respCode={respCode}&respMsg={respMsg}&result={result}&terminalId={terminalId}&trxId={trxId}&version={version}

组成待验签字符串，如：

idNumber=3212810000000000000&idType=1&merchantAcctId=1001215986501&name=张三&respCode=000000&result=S&terminalId=0010001&trxId=20190114143214310&version=1.0

2.将签名参数signMsg和拼接的验签字符串进行URLDecoder。

如C#代码，signMsg为通知中的signMsg字段，signMsgVal为拼接的验签串：
String signMsgDecode = HttpUtility.UrlDecode(signMsg);
String signMsgValDecode = HttpUtility.UrlDecode(signMsgVal);

3.将URLDecoder后的签名参数（signMsg）使用base64解码为字节码串。

4.使用RSA的验签方法，通过签名字符串、签名参数（经过base64解码）及Chinapnr公钥验证签名。具体验签方法请详见Demo

商户业务处理注意事项

1.商户必须根据Chinapnr不同类型的业务通知，正确的进行不同的业务处理，并且过滤重复的通知结果数据。

2.Chinapnr异步通知以通知地址返回HTTPSTATUS为200认为成功，否则会一直通知，通知策略是一共通知16次，前面每隔10s通知一次一共通知6次每次，后10次通知时间间隔增加（N*60s+30s，N为第几次通知，如第7次通知间隔第一次7min30s）。商户在接受到Chinapnr异步通知后，应返回成功接受内容，如"SUCESS"。

3.在Chinapnr的业务通知中，只有交易通知payResult状态为10时，Chinapnr才会认定为买家付款成功。如果商户未正确处理业务通知，存在潜在的风险，商户自行承担因此而产生的所有损失。

响应码	描述
000000	处理成功
100001	必输项[xxx]未提交
100002	请求的数据项[xxx]长度最大允许[y],实际[z]
100003	请求的数据项[xxx]格式错误,合法格式请参照接入文档
100004	请求的数据项[xxx]不合法
110001	商户不存在
110002	信息的签名内容不正确
110003	产品功能未开通
999999	系统错误

商户请求API

商户需上传唯一的商户订单号(orderId)，同时建议商户订单号中包含年月日等时间信息。
Chinapnr默认在网关页面半小时不选择银行支付，则超时失败。如已选择银行支付，默认支付超时时间12小时，即晚于该订单的最晚付款时间后，将关闭交易。

交易查询

商户可在商户后台进行交易查询，也可通过查询接口查询。

进入商户后台“交易管理”=>“交易查询”菜单，输入订单号，Chinapnr交易流水号发起查询。

图6.1 商户后台交易查询
网关交易在未收到支付结果通知时通过查询接口查询支付结果，查询接口未返回支付成功，则继续轮询。

详情请参见交易查询接口。

退款

商户因业务原因需要退款时，可通过成功交易的商户订单号或Chinapnr交易号进行退款。Chinapnr退款支持单笔交易分多次退款，多次退款需要提交Chinapnr交易号并设置不同的退款单号；总退款金额不能超过用户实际支付金额。

对接退款接口。

详情请参见退款接口。

对账

商户可通过接口下载指定日期（当天除外）的业务明细账单文件，并结合自身业务系统实现自动对账。

商户可在商户后台发起日终查询,进入“交易管理”=>“日终交易查询”菜单，选择要查询的交易所对应的终端号，选择日期，点击查询。

对查询出的日终列表，选择点击下载按钮下载日终对账文件。

图6.4 商户后台日终文件查询
对接日终文件查询接口

详情请参见日终交易查询。

DEMO下载

注意：Demo下载后可直接运行，也可将项目里商户号，终端号，私钥证书（**.pfx）更换成已开通测试商户的。

支付模式	说明	平台	操作
身份鉴权API	身份鉴权API对应的DEMO	JAVA	下载

文档下载

接口名称	说明	操作
身份鉴权API	身份鉴权API对应的文档	下载

1.订单信息的签名不正确

确保私钥证书正确。

确保加签字段和加签顺序正确，可对照Demo对比

2.订单返回信息验签失败

确保公钥证书正确，与所提交环境匹配，可在对应环境商户后台下载。

确保验签字段和验签顺序正确，可对照Demo对比

3.接口发起请求,报商户号不存在或未开通

接口发起请求时,提交的并非是商户号,而是会员号,会员号=商户号+“01”。

4.TLS1.0 SSL3.0等协议无法正常进行网关交易

根据PCI-DSS检查要求，正式环境禁止使用低版本的SSL3.0 TLS1.0 TLS1.1等协议,请使用高于TLSv1.2及以上发送请求，推荐使用TLSv1.2

OpenSSL工具安装

1.Linux用户（以Ubuntu为例）

sudo apt-get install openssl

2.Windows用户开发者可以在OpenSSL官方网站下载Windows的OpenSSL安装包进行安装。或直接下载

RSA私钥及公钥生成

1.Linux用户（以Ubuntu为例）

				$ openssl   进入OpenSSL程序
    OpenSSL> genrsa -out private-rsa.key 1024   生成私钥
    OpenSSL> req -new -x509 -key private-rsa.key -days 750 -out public-rsa.cer     生成公钥
    OpenSSL> pkcs12 -export -name test-alias -in public-rsa.cer -inkey private-rsa.key -out private-rsa.pfx    生成证书，密码和别名需记住
    OpenSSL> exit   # 退出OpenSSL程序

2.Windows用户在cmd窗口中进行以下操作：

				C:\Users\Hammer>cd C:\OpenSSL\bin     进入OpenSSL安装目录
    C:\OpenSSL\bin>openssl.exe            进入OpenSSL程序
    OpenSSL> genrsa -out private-rsa.key 1024   生成私钥
    OpenSSL> req -new -x509 -key private-rsa.key -days 750 -out public-rsa.cer     生成公钥
    OpenSSL> pkcs12 -export -name test-alias -in public-rsa.cer -inkey private-rsa.key -out private-rsa.pfx    生成证书，密码和别名需记住
    OpenSSL> exit   # 退出OpenSSL程序

注意：

1.对于使用Php的开发者，需要将“private-rsa.pfx”证书转换为“private-rsa.pem”，输入转换命令pkcs12 -in dc-rsa.pfx -passin pass:“此处输入商户第3步设置的密码” -nodes -out private-rsa.pem。

跨境公钥转pem（cer转pem）:x509 -in C:\OpenSSL\bin\ChinaPnR.rsa.cer -out C:\OpenSSL\bin\ChinaPnR.rsa.pem

2.如第二步报错，则根据工具所在路径指定下配置文件，如命令改为：req -new -x509 -key private-rsa.key -config "C:\OpenSSL\bin\openssl.cnf" -days 750 -out public-rsa.cer

私钥及公钥文件示例

经过以上步骤，开发者可以在当前文件夹中（Windows用户在C:\OpenSSL\bin）看到private-rsa.pfx和public-rsa.cer两个文件，前者为私钥，后者为公钥。开发者将私钥保留，将公钥提交给Chinapnr网关，用于信息加密及解密。公钥需修改前缀为商户号，并上传至跨境系统商户后台。以下为使用OpenSSL生成的私钥文件和公钥文件示例：

1.私钥文件示例（Java使用）

3.公钥文件示例