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

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

1. 商户会员号

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

商户接入结汇业务，调用API须遵循以下规则：

场景介绍

帮助商户将资金购结汇以及代发。

结汇代发流程

第一步：明细备案

图3.0 明细备案

第二步：汇款及结汇处理

图3.1 汇款及结汇处理

第三步：资金下发

图3.2 资金下发

概述

本文档展示了如何从零开始，与Chinapnr跨境系统结汇代发接口对接的流程。

第一步：获取账号信息

1. 商户需与前端销售沟通开通测试账号或生产账号，并提供接受邮箱地址。

2. 1-2个工作日内由开通组负责将开通的账号信息发送至商户邮箱。

第二步：配置密钥

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

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

1. 下载示例代码Demo
   为了帮助开发者调用开放接口，我们提供了示例代码下载，封装了签名&验签、HTTP接口请求等基础功能。请先下载对应语言版本的Demo并引入您的开发工程《Demo下载》。

2. 将Demo运行成功，并将代码集成到您的项目中，记得修改商户号，终端号，和私钥证书。如生产环境，还需更换Chinapnr生产公钥证书。

调用流程

接口调用时序图：

图4.1 结汇代发时序图

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

概述

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

RSA 私钥及公钥生成

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

商户上传公钥

注意：

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

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

图5.1 上传公钥

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

下载Chinapnr公钥

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

图5.2 下载Chinapnr公钥

注意：

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

API请求

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

注意：

1. 没有值的参数无需传递,也无需包含到待签名数据中。

2. 签名时将字符转化成字节流时指定的字符集UTF8。

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

结汇申请完成后，Chinapnr会向开发者提交的通知地址后台异步返回结汇结果。

接口返回参数说明请参见《结汇代发接口》

结汇结果通知

结汇结果通知示例：

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

competCustom={competCustom}&customCode={customCode}&customVersion={customVersion}&dealId={dealId}&decResult={decResult}&declareId={declareId}&ecpDomainName={ecpDomainName}&ecpShortName={ecpShortName}&errorCode={errorCode}&errorMsg={errorMsg}&freightAmt={freightAmt}&goodsAmt={goodsAmt}&iaqInstCode={iaqInstCode}&merCustomCode={merCustomCode}&merCustomName={merCustomName}&merchantAcctId={merchantAcctId}&offsetAmt={offsetAmt}&orderAmt={orderAmt}&orderCurrency={orderCurrency}&orderId={orderId}&payerIdNumber={payerIdNumber}&payerIdType={payerIdType}&payerName={payerName}&taxAmt={taxAmt}&terminalId={terminalId}&bizType={bizType}&version={version}

组成待验签字符串，如：

competCustom=11111&customCode=NBHG&dealId=c108270&decResult=20&declareId=15849&ecpDomainName=www.xxx.com&ecpShortName=1111&freightAmt=0&goodsAmt=600&iaqInstCode=11111&merCustomCode=1111&merCustomName=测试商户&merchantAcctId=1001215986501&offsetAmt=0&orderAmt=600&orderCurrency=CNY&orderId=20170825152657559&payerIdNumber=320125198805232313&payerIdType=1&payerName=张三&taxAmt=0&terminalId=hgtest02&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

银行码表+省市代码

针对结汇明细备案，提交明细时使用。

DEMO下载

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

文档下载

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使用）

								-----BEGIN PRIVATE KEY-----
    MIICeAIBADANBgkqhkiG9w0BAQEFAASCAmIwggJeAgEAAoGBAN0yqPkLXlnhM+2H
    /57aHsYHaHXazr9pFQun907TMvmbR04wHChVsKVgGUF1hC0FN9hfeYT5v2SXg1WJ
    Sg2tSgk7F29SpsF0I36oSLCIszxdu7ClO7c22mxEVuCjmYpJdqb6XweAZzv4Is66
    1jXP4PdrCTHRdVTU5zR9xUByiLSVAgMBAAECgYEAhznORRonHylm9oKaygEsqQGk
    YdBXbnsOS6busLi6xA+iovEUdbAVIrTCG9t854z2HAgaISoRUKyztJoOtJfI1wJa
    QU+XL+U3JIh4jmNx/k5UzJijfvfpT7Cv3ueMtqyAGBJrkLvXjiS7O5ylaCGuB0Qz
    711bWGkRrVoosPM3N6ECQQD8hVQUgnHEVHZYtvFqfcoq2g/onPbSqyjdrRu35a7P
    vgDAZx69Mr/XggGNTgT3jJn7+2XmiGkHM1fd1Ob/3uAdAkEA4D7aE3ZgXG/PQqlm
    3VbE/+4MvNl8xhjqOkByBOY2ZFfWKhlRziLEPSSAh16xEJ79WgY9iti+guLRAMra
    vGrs2QJBAOmKWYeaWKNNxiIoF7/4VDgrcpkcSf3uRB44UjFSn8kLnWBUPo6WV+x1
    FQBdjqRviZ4NFGIP+KqrJnFHzNgJhVUCQFzCAukMDV4PLfeQJSmna8PFz2UKva8f
    vTutTryyEYu+PauaX5laDjyQbc4RIEMU0Q29CRX3BA8WDYg7YPGRdTkCQQCG+pjU
    2FB17ZLuKRlKEdtXNV6zQFTmFc1TKhlsDTtCkWs/xwkoCfZKstuV3Uc5J4BNJDkQ
    OGm38pDRPcUDUh2/
    -----END PRIVATE KEY-----
							

3.公钥文件示例

								-----BEGIN CERTIFICATE-----
MIIDNzCCAqCgAwIBAgIJAJaZj8YlPQcIMA0GCSqGSIb3DQEBBQUAMHExCzAJBgNV
BAYTAkhLMQswCQYDVQQIEwJISzELMAkGA1UEBxMCSEsxDTALBgNVBAoTBE1QQVkx
DTALBgNVBAsTBE1QQVkxDTALBgNVBAMTBE1QQVkxGzAZBgkqhkiG9w0BCQEWDE1Q
QVlAMTIzLkNPTTAeFw0xNjA3MDUxMDM5NDJaFw0xODA3MjUxMDM5NDJaMHExCzAJ
BgNVBAYTAkhLMQswCQYDVQQIEwJISzELMAkGA1UEBxMCSEsxDTALBgNVBAoTBE1Q
QVkxDTALBgNVBAsTBE1QQVkxDTALBgNVBAMTBE1QQVkxGzAZBgkqhkiG9w0BCQEW
DE1QQVlAMTIzLkNPTTCBnzANBgkqhkiG9w0BAQEFAAOBjQAwgYkCgYEAyiVbdBOF
Qtb03wKw+7oR7bA32vi5/XkJ33CbzdiID+ZK6lkeeRlJVIQvf2UsfScIeTLE/Nyn
lapF12Gsw9dVoiCzrScagn3kknFcE7fM2x4kyLLNQdJgJvb7jCRl/oMOziVT+z5R
cZ8SS11vO5Dk5kx8W4n66ldoyDeUVXArlCcCAwEAAaOB1jCB0zAdBgNVHQ4EFgQU
epQ9Qvg/VE5nb69L+D08eqn6/E8wgaMGA1UdIwSBmzCBmIAUepQ9Qvg/VE5nb69L
+D08eqn6/E+hdaRzMHExCzAJBgNVBAYTAkhLMQswCQYDVQQIEwJISzELMAkGA1UE
BxMCSEsxDTALBgNVBAoTBE1QQVkxDTALBgNVBAsTBE1QQVkxDTALBgNVBAMTBE1Q
QVkxGzAZBgkqhkiG9w0BCQEWDE1QQVlAMTIzLkNPTYIJAJaZj8YlPQcIMAwGA1Ud
EwQFMAMBAf8wDQYJKoZIhvcNAQEFBQADgYEAOHgqqxMLoaUW/i43KtTHFGciwr9m
OkusX4B4kx5sKN8Ed110iyRPixMKCslV2EHP4uIVAMWhEw+AxULbJte86r8ryr/m
Jc0PR4U9vrpQxdWLsBh8lhKgC4GVJb8jkwcVkjF/XvvVUp/VqHto+LBnjdNAXqZa
GbuKXbLTnmIwGes=
-----END CERTIFICATE-----