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

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

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

  1. 商户会员号

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

商户接入身份鉴权接口时，调用API须遵循以下规则：

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

场景介绍

帮助商户对用户信息进行三/四要素身份鉴权。

概述

本文档展示了如何从零开始，与Chinapnr跨境系统身份鉴权接口对接的流程。

第一步：获取账号信息

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

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

第二步：配置密钥

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

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

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

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

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

概述

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公钥证书需在不对环境的商户后台下载。

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

接口参数说明请参见《海关申报接口》

API请求

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

请求示例：

ecpDomainName=www.xxx.com
signType=4
merCustomCode=1111
version=1.0
payerIdType=1
terminalId=hgtest02
bgUrl=http://127.0.0.1:8081/QAMOCK-Test/receiveCustomBg.do
taxAmt=0
merCustomName=测试商户
customCode=NBHG
orderId=20170825152657559
orderAmt=600
ecpShortName=1111
submiturl=http://192.168.1.139:8089/custom/applyImptDec.do
offsetAmt=0
customVersion=
merchantAcctId=1001215986501
goodsAmt=600
competCustom=11111
orderCurrency=CNY
dealId=
iaqInstCode=11111
freightAmt=0
ext1=
ext2=
signMsg=PLEdRqKZC8hxlWd2+U1tH/5blPrWVZZWIBqQiB9kiXfrT1UCqBInOhirfm391Ql3HjGKRSCVNnuogG2PoyvhPyehupaCSL3P8IwwzFuCfZJsGKTYdAT9sJ3ovckbAzcnomV/JZVVRqi6hhQqV/eU69ygb0G9WuDvVWUJrqu97Ac=
bizType=
payerIdNumber=320125198805232313
payerName=张三

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

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

version={version}&bgUrl={bgUrl}&signType={signType}&merchantAcctId={merchantAcctId}&terminalId={terminalId}&dealId={dealId}&customCode={customCode}&customVersion={customVersion}&merCustomCode={merCustomCode}&merCustomName={merCustomName}&payerIdType={payerIdType}&payerName={payerName}&payerIdNumber={payerIdNumber}&orderId={orderId}&orderCurrency={orderCurrency}&orderAmt={orderAmt}&freightAmt={freightAmt}&goodsAmt={goodsAmt}&taxAmt={taxAmt}&offsetAmt={offsetAmt}

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

version=1.0&bgUrl=http://127.0.0.1:8081/QAMOCK-Test/receiveCustomBg.do&signType=4&merchantAcctId=1001215986501&terminalId=hgtest02&customCode=NBHG&merCustomCode=1111&merCustomName=测试商户&payerIdType=1&payerName=张三&payerIdNumber=320125198805232313&orderId=20170825152657559&orderCurrency=CNY&orderAmt=600&freightAmt=0&goodsAmt=600&taxAmt=0&offsetAmt=0

2.进行RSA签名后获得sign，再经过Base64编码，具体加签代码请详见Demo其最终的请求报文样式参考如下： 

REQUEST URL: https://global.chinapnr.com/custom/applyImptDec.do 
REQUEST METHOD: POST
CONTENT:
ecpDomainName=www.xxx.com
signType=4
merCustomCode=1111
version=1.0
payerIdType=1
terminalId=hgtest02
bgUrl=http://127.0.0.1:8081/QAMOCK-Test/receiveCustomBg.do
taxAmt=0
merCustomName=测试商户
customCode=NBHG
orderId=20170825152657559
orderAmt=600
ecpShortName=1111
submiturl=http://192.168.1.139:8089/custom/applyImptDec.do
offsetAmt=0
customVersion=
merchantAcctId=1001215986501
goodsAmt=600
competCustom=11111
orderCurrency=CNY
dealId=
iaqInstCode=11111
freightAmt=0
ext1=
ext2=
signMsg=PLEdRqKZC8hxlWd2+U1tH/5blPrWVZZWIBqQiB9kiXfrT1UCqBInOhirfm391Ql3HjGKRSCVNnuogG2PoyvhPyehupaCSL3P8IwwzFuCfZJsGKTYdAT9sJ3ovckbAzcnomV/JZVVRqi6hhQqV/eU69ygb0G9WuDvVWUJrqu97Ac=
bizType=
payerIdNumber=320125198805232313
payerName=张三

注意：

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

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

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

返回结果

返回示例：

ecpDomainName=www.xxx.com
signType=4
merCustomCode=1111
payerIdType=1
version=1.0
terminalId=hgtest02
taxAmt=0
bgUrl=http://127.0.0.1:8081/QAMOCK-Test/receiveCustomBg.do
merCustomName=测试商户
customCode=NBHG
orderAmt=600
orderId=20170825152657559
ecpShortName=1111
submiturl=http://192.168.1.139:8089/custom/applyImptDec.do
offsetAmt=0
customVersion=
merchantAcctId=1001215986501
goodsAmt=600
competCustom=11111
orderCurrency=CNY
dealId=
iaqInstCode=11111
freightAmt=0
ext1=
ext2=
signMsg=QqGXKGlkh7SVD5Jef7A52FTAz85XR2Zf8zBnRJ6WLeTGFX0d5Q2nJChr0k8EMPBFLRT70xyrgE8OSfUj0liwoGFFid%2FxOZeJQ33HltHpyqPMJW%2FdF3C%2BOzldwfvvdbIqtDD55bjuuDG%2B1lqr%2BH3FBIx1bKJMqsa1AdPwUzez0vY%3D
bizType=
payerIdNumber=320125198805232313
payerName=张三
declareId=15849
decResult=10
errorCode=000000
errorMsg=SUCCESS

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

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&decResult=10&declareId=15849&ecpDomainName=www.xxx.com&ecpShortName=1111&errorCode=000000&errorMsg=SUCCESS&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）使用base64解码为字节码串

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

海关申报完成后，Chinapnr会向开发者提交的bgUrl地址后台异步返回海关申报结果。

接口返回参数说明请参见《海关申报接口》

申报结果通知

申报结果通知示例：

ecpDomainName=www.xxx.com
signType=4
merCustomCode=1111
version=1.0
payerIdType=1
terminalId=hgtest02
decResult=20
bgUrl=http://127.0.0.1:8081/QAMOCK-Test/receiveCustomBg.do
taxAmt=0
merCustomName=测试商户
customCode=NBHG
orderId=20170825152657559
orderAmt=600
ecpShortName=1111
customVersion=
offsetAmt=0
declareId=15849
merchantAcctId=1001215986501
competCustom=11111
goodsAmt=600
orderCurrency=CNY
dealId=c108270
iaqInstCode=11111
freightAmt=0
ext1=
ext2=
signMsg=D2iVN%2FA3x95CDJPMm5rp4vH7z6rKViiEUSLbrl6ffOhL2fWMA4oNrLxtYJjm2G4Bqja%2Fc%2FgJz7tpfb%2Bpn4CeIgmbukDFoZmSoXN6Hxe36lYa8Th96HnrXsMM70OWt6DwHEmmCWKhCFpjY2hD6ERnONUK7XFrfR1TnYtg%2BtZlNWM%3D
bizType=
payerIdNumber=320125198805232313
payerName=张三

申报结果通知的验签

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

商户业务处理注意事项

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

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

3.在Chinapnr的业务通知中，只有申报通知decResult=20时，Chinapnr才会认定为申报成功。如果商户未正确处理业务通知，存在潜在的风险，商户自行承担因此而产生的所有损失。

货币符号 币别
CNY 人民币
USD 美元
HKD 港元
GBP 英镑
JPY 日元
EUR 欧元
AUD 澳元
CAD 加元
code(海关错误代码) msg（海关错误描述）
999999 系统异常
100001 必输项[xxx]未提交
100002 请求的数据项[xxx]长度最大允许[y],实际[z]
100003 请求的数据项[xxx]格式错误,合法格式请参照接入文档
100004 请求的数据项[xxx]不合法
100092 支付人身份信息有误
110001 商户不存在
110002 海关不存在
110003 商户报关功能未开通
110004 申报交易重复
110005 金额数值错误
110006 交易流水不存在
110007 申报金额大于支付金额
110008 本交易原交易流水号未全部提交
110009 申报的流水号提交有误，多于应提交数目
110010 身份信息校验失败
110011 商户报关手续费未配置
200001 订单信息的签名内容不正确
100001 必输项[xxx]未提交
100002 请求的数据项[xxx]长度最大允许[y],实际[z]
100003 请求的数据项[xxx]格式错误,合法格式请参照接入文档
100004 请求的数据项[xxx]不合法
100092 支付人身份信息有误
110001 商户不存在
110002 海关不存在
110003 商户报关功能未开通
110004 申报交易重复
110005 金额数值错误
110006 交易流水不存在
110007 申报金额大于支付金额
110008 本交易原交易流水号未全部提交
110009 必输项[xxx]未提交
100001 申报的流水号提交有误，多于应提交数目

海关关区列表

《海关关区代码》下载

针对海关申报接口中“主管海关代码”字段的填写，仅用于广州和南沙海关申报时需要。

海关接口参数列表

《海关接口参数填写说明》下载

针对各海关接口参数填写规范。

中文类名 海关编码
深圳海关 SZHG
杭州海关 HZHG
宁波海关 NBHG
广州单一窗口3.0 GZHG
上海海关 SHHG
青岛海关 QDHG
苏州海关 SZSW
南沙海关 NANSHAZJ
天津海关 TJHG
郑州海关 ZHENGZHOU
成都海关 CHENGDU
福建海关 FUJIAN
合肥海关 HEFEI
河南海关 HENAN

DEMO下载

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

支付模式 说明 平台 操作
二要素身份鉴权 二要素身份鉴权对应的DEMO JAVA 下载
三四要素身份鉴权 三四要素身份鉴权对应的DEMO JAVA 下载
PHP 下载

文档下载

支付模式 说明 操作
身份鉴权（三要素-四要素） 身份鉴权（三要素-四要素）接口 下载
身份鉴权（二要素） 身份鉴权（二要素）接口 下载

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

确保私钥证书正确。

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

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

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

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

3.网关发起交易,报商户号不存在或未开通

网关发起交易时,提交的并非是商户号,而是会员号,会员号=商户号+“01”。

4.测试环境，鉴权结果返回通道异常

测试环境，鉴权结果为模拟信息，可以使用以下信息调试

姓名：王文斌 ；身份证号：411081199004235955；卡号：4682037906128888；手机号：15015160170

5.三、四要素验证失败常见原因

1.不常见地方银行
2.需开通银联在线支付
3.需开通无卡支付
4.卡状态异常等

OpenSSL工具安装

1.Linux用户（以Ubuntu为例）

sudo apt-get install openssl

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

3.若不习惯查看文档中心，此为证书生成word文档，可自行下载证书生成文档下载

RSA私钥及公钥生成

生成证书days在730-780之间

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

身份鉴权接口(二要素)

本文档定义CHINAPNR支付网关商户接入接口规范，提供接口报文参数说明、示例报文、信息安全解决方案，并给出相关问题说明等，以帮助商户技术人员接入，便于尽快投入使用。
根据PCI-DSS检查要求，正式环境禁止使用低版本的SSL3.0 TLS1.0 TLS1.1等协议,请使用高于TLSv1.2及以上发送请求，推荐使用TLSv1.2

测试环境测试数据：

姓名：王文斌 ；身份证号：411081199004235955

提交参数

请求地址

环境 HTTPS请求地址
测试环境 https://hfgj.testpnr.com/pay/idAuth.htm
正式环境 https://global.chinapnr.com/pay/idAuth.htm

协议参数

参数名称 参数含义 最大长度 是否为空 参数说明
version 网关版本 String(10) 不可空 固定值：1.0
signType 签名类型 String(2) 不可空 固定值：4
4-RSA加签

信息参数

参数名称 参数含义 最大长度 是否为空 参数说明
merchantAcctId 商户号 String(32) 不可空 由我司提供的商户号+01，共13位数字
terminalId 终端号 String(8) 不可空 终端号，由我司提供的终端号，不同的接口/功能可能会分配不同的终端号，故请考虑多终端情况下的兼容。

业务参数

参数名称 参数含义 最大长度 是否为空 参数说明
trxId 业务处理流水号 String(32) 不可空 商户端鉴权请求流水号
idType 证件类型 String(2) 不可空 如果商户提交以商户为准，证件类型默认为身份证：1
name 姓名 String(96) 不可空
idNumber 身份证号 String(32) 不可空 如果身份证号包含X，请保持字母为大写
ext1 扩展字段1 String(512) 可空 英文或中文字符串
ext2 扩展字段2 String(512) 可空 英文或中文字符串
signMsg 签名信息 String(2048) 不可空 参数1={参数1}&参数2={参数2}&……&参数n={参数n}然后进行商户密钥进行加签，
加签证书，请参照私钥公钥生成
注：若通过sdk接入，则无需自己处理，代码已封装		 
version={version}&signType={signType}&merchantAcctId={merchantAcctId}&terminalId={terminalId}&trxId={trxId}&idType={idType}&name={name}&idNumber={idNumber}
只对非空值的字段进行加签。

返回结果

查询结果会接口同步返回。

返回参数

参数名称 长度 参数说明
version String(10) 版本号;固定值：1.0
signType String(2) 签名方式;固定值：4-RSA
merchantAcctId String(32) 商户号
terminalId String(32) 终端号
trxId String(32) 商户端鉴权请求流水号
idType String(2) 证件类型
name String(64) 姓名
idNumber String(32) 身份证号
ext1 String(512) 扩展字段1
ext2 String(512) 扩展字段2
respCode String(8) 响应码;返回的响应代码，不为空。
respMsg String(256) 响应描述;返回的响应信息，可以为空。
result String(1) 响应码为000000时有返回值，否则为空
鉴权成功：S
鉴权失败：F
signMsg String(2048) 签名信息;
对于所有值不为空的参数及对应值，按照字母顺序组成字符串
DSA：参数1={参数1}&参数2={参数2}&……&参数n={参数n}然后进行支付平台证书加密形成密文后进行2048位的Base64转码。
加签证书，请参照私钥公钥生成
注：若通过sdk接入，则无需自己处理，代码已封装		 
idNumber={idNumber}&idType={idType}&merchantAcctId={merchantAcctId}&name={name}&respCode={respCode}&respMsg={respMsg}&result={result}&terminalId={terminalId}&trxId={trxId}&version={version}
根据字母排序（如a**字段放在b**字段前面）验签。

请求示例

请参考具体Demo：二要素鉴权demo

身份鉴权接口(三要素-四要素)

本文档定义CHINAPNR支付网关商户接入接口规范，提供接口报文参数说明、示例报文、信息安全解决方案，并给出相关问题说明等，以帮助商户技术人员接入，便于尽快投入使用。
根据PCI-DSS检查要求，正式环境禁止使用低版本的SSL3.0 TLS1.0 TLS1.1等协议,请使用高于TLSv1.2及以上发送请求，推荐使用TLSv1.2

交易规则（测试环境测试用信息）

三要素成功数据-姓名：王文斌 ；身份证号：411081199004235955；卡号：4682037906128888；

三要素失败数据-姓名：张三 ；身份证号：320722199010231665；卡号：4682037906128889；

四要素成功数据-姓名：王文斌 ；身份证号：411081199004235955；卡号：4682037906128888；手机号：15015160170

四要素失败数据-姓名：张三 ；身份证号：320722199010231665；卡号：4682037906128889；手机号：15015160179

提交参数

请求地址

环境 HTTPS请求地址
测试环境 https://hfgj.testpnr.com/idauth/identityAuth.htm
正式环境 https://global.chinapnr.com/idauth/identityAuth.htm

协议参数

参数 类型 是否必填 最大长度 描述 示例
inputCharset String 是 1 字符集,固定值：1
1-UTF-8		 1
version String 是 10 版本，固定值：1.0 1.0
signType String 是 2 签名类型，固定值：4
4-RSA加签		 4

业务参数

参数 类型 是否必填 最大长度 描述 示例
merchantAcctId String 是 32 由我司提供的商户号+01，共13位数字 1001234001101
terminalId String 是 8 终端号，由我司提供的终端号，不同的接口/功能可能会分配不同的终端号，故请考虑多终端情况下的兼容。 666666
reqNo String 是 32 商户请求流水号，只允许使用字母、数字、_和-,每商户提交的订单号，必须在各自系统中唯一 id_005201906120001
authType String 是 2 鉴权类型：03-三要素鉴权，04-四要素鉴权 03
idType String 是 2 证件类型：身份证-1 1
ciphertext String 是 2048 三要素/四要素密文。加密前明文按照以下固定格式拼串
三要素：姓名=张三&证件号码=210000199009091234&银行卡号=6214888888888888
四要素：
姓名=张三&证件号码=210000199009091234&银行卡号=6214888888888888&手机号码=13888888888

注：如果身份证号包含X，请保持字母为大写		 三要素：
name=xxx&idNumber=xxx&cardNumber=xxx使用平台密钥加密
四要素：
name=xxx&idNumber=xxx&cardNumber=xxx&mobileNumber=xxx使用平台密钥加密。
从商户后台下载我司公钥证书，RSA公钥加密，得到密文后对密文使用gzip压缩，最后使用Base64编码，得到最终密文字符串 方法可参考Demo：三要素鉴权demo。
（平台密钥下载：商户后台-证书管理-下载chinaPnR证书）
ext1 String 否 128 扩展字段1，英文或中文字符串，鉴权完成后，按照原样返回给商户 扩展字段1
ext2 String 否 128 扩展字段2，英文或中文字符串，鉴权完成后，按照原样返回给商户 扩展字段2
signMsg String 是 2048 按以下固定字段顺序进行加签，仅对非空字段进行加签： inputCharset={inputCharset}&version={version}&signType={signType}&merchantAcctId={merchantAcctId}&terminalId={terminalId}&reqNo={reqNo}&authType={authType}&idType={idType}
加签证书，请参照私钥公钥生成
注：若通过sdk接入，则无需自己处理，代码已封装		 参数1={参数1}&参数2={参数2}&……&参数n={参数n}然后进行商户密钥进行加签，所有参与签名的参数 KEY及其值的大小写敏感。

返回结果

返回参数

参数 类型 是否必填 最大长度 描述 示例
version String 是 10 版本，固定值：1.0 1.0
signType String 是 2 签名类型，固定值：4
4-RSA加签		 4
merchantAcctId String 是 32 商户号，与提交请求时的保持一致 1001234001101
terminalId String 是 8 终端号，与提交请求时的保持一致 666666
reqNo String 是 32 商户请求流水号，与提交请求时的保持一致 id_005201906120001
respCode String 是 6 响应码：000000-处理成功，200002-鉴权失败，其它-处理失败 000000
respMsg String 否 256 响应描述 身份信息一致
result String 否 1 鉴权结果，鉴权通道申请成功才会有。
身份信息匹配：S
身份信息不匹配：F		 S
ext1 String 否 128 扩展字段1，英文或中文字符串，鉴权完成后，按照原样返回给商户 扩展字段1
ext2 String 否 128 扩展字段2，英文或中文字符串，鉴权完成后，按照原样返回给商户 扩展字段2
signMsg String 是 2048 签名字符串，商户需对该字段进行验签。详情请参考验签方法。 签名信息;对于所有值不为空的参数及对应值，按照字母顺序组成字符串RSA：参数1={参数1}&参数2={参数2}&……&参数n={参数n}然后进行平台证书加密形成密文后进行2048位的Base64转码。
注：若通过sdk接入，则无需自己处理，代码已封装

请求实例

请参考具体Demo：三要素鉴权demo

错误码

错误码 错误描述
100000 参数转换错误
100001 必输项未提交
100002 参数项长度不符
100003 请求的数据项格式错误
100004 请求的数据项不合法
100005 密文解密失败
100006 必输项未提交
100007 密文姓名格式错误
100008 密文证件号码格式错误
100009 密文银行卡号格式错误
100010 密文手机号格式错误
100011 请求流水号reqNo重复
100012 商户不存在
100013 商户号状态异常
100014 终端不存在
100015 终端状态异常
100016 签名验证失败
100017 签名内容不正确
100018 签名类型错误
100019 商户证书不存在
100020 产品功能未开通
100021 商户参数配置错误
100022 账户余额不足
100023 统计错误
100024 入账失败

汇率查询

本文档定义CHINAPNR支付网关商户接入接口规范，提供接口报文参数说明、示例报文、信息安全解决方案，并给出相关问题说明等，以帮助商户技术人员接入，便于尽快投入使用。
根据PCI-DSS检查要求，正式环境禁止使用低版本的SSL3.0 TLS1.0 TLS1.1等协议,请使用高于TLSv1.2及以上发送请求，推荐使用TLSv1.2

1.0 汇率查询

请求地址

环境 HTTPS请求地址
测试环境 https://hfgj.testpnr.com/pay/inquiry.htm
正式环境 https://global.chinapnr.com/pay/inquiry.htm

协议参数

参数 类型 是否必填 最大长度 描述 示例值
inputCharset String 是 1 字符集,固定值：1
1-UTF-8		 1
version String 是 10 网关版本,固定值：1.0 1.0
language String 是 3 网关页面显示语言种类，固定值：1
1-中文显示		 1
signType String 是 2 签名类型，固定值：4
4-RSA加签		 4

业务参数

参数 类型 是否必填 最大长度 描述 示例值
merchantAcctId String 是 32 会员账号，由我司提供的商户号+01，共13位数字 1001234001101
terminalId String 是 8 终端号，由我司提供的终端号 999999
orderId String 是 32 商户订单号，只允许使用字母、数字、_。同一商户提交的订单号，必须在自身账户交易中唯一 order20181111120001299
orderCurrency String 是 3 订单币种，3位币别码 如美元：USD
orderAmount Number 是 12 商户订单金额，整型数字，单位为分。日韩元支持的最小单位为元 如100元，则填写10000
orderTime String 是 14 数字串，一共14位。格式为：年[4位]月[2位]日[2位]时[2位]分[2位]秒[2位] 20181117020101
ext1 String 否 128 扩展字段1，英文或中文字符串,原样返回给商户 扩展字段1
ext2 String 否 128 扩展字段2，英文或中文字符串,原样返回给商户 扩展字段2
signMsg String 是 2048 签名字符串请参考签名方法。
加签证书，请参照私钥公钥生成
注：若通过sdk接入，则无需自己处理，代码已封装		 参数1={参数1}&参数2={参数2}&……&参数n={参数n}然后进行商户密钥进行加签 
-	按以下固定字段顺序进行加签
-	仅对非空字段进行加签
inputCharset={inputCharset}&version={version}&language={language}&signType={signType}&merchantAcctId={merchantAcctId}&terminalId={terminalId}&orderId={orderId}&orderCurrency={orderCurrency}&orderAmount={orderAmount}&orderTime={orderTime}

返回结果

结果会接口同步返回。

返回参数

参数 类型 是否必填 最大长度 描述 示例值
merchantAcctId String 是 32 会员账号，与提交订单时的保持一致 1001234001101
terminalId String 是 8 终端号，与提交订单时的保持一致 999999
orderId String 是 32 商户订单号，与提交订单时一致 order20181111120001299
orderCurrency String 是 3 订单币种，与提交订单时一致 如美元：USD
orderAmount Number 是 12 商户订单金额，与提交订单时一致 600
sourceAmount Number 否 12 汇率换算后的订单金额，交易失败时可能为空。 4070
inquireTrxNo String 否 32 询盘流水号，交易失败时可能为空。 34595
exchangeRate Number 否 15 汇率，交易失败时可能为空。当订单币别为日元、韩元时，为汇率扩大1000000倍的值，其余币别为扩大10000倍的值。 67827
quoteTime String 否 14 当前汇率报价时间，交易失败时可能为空。收单系统对交易进行处理的时间,格式为：年[4位]月[2位]日[2位]时[2位]分[2位]秒[2位] 20181115143042
expireTime String 否 14 当前汇率过期时间，交易失败时可能为空。收单系统对交易进行处理的时间,格式为：年[4位]月[2位]日[2位]时[2位]分[2位]秒[2位] 20181115144042
errCode String 是 8 详细可查看附录 000000
errorMsg String 否 512 错误描述 错误描述
ext1 String 否 128 扩展字段1，原样返回 扩展字段1
ext2 String 否 128 扩展字段2，原样返回 扩展字段2
signMsg String 是 2048 签名字符串请参考签名方法。
加签证书，请参照私钥公钥生成
注：若通过sdk接入，则无需自己处理，代码已封装		 参数1={参数1}&参数2={参数2}&……&参数n={参数n}然后进行商户密钥进行加签 
-	按以下字段字母顺序进行加签
-	仅对非空字段进行加签
errCode={errCode}&exchangeRate={exchangeRate}&expireTime={expireTime}&inquireTrxNo={inquireTrxNo}&merchantAcctId={merchantAcctId}&orderAmount={orderAmount}&orderCurrency={orderCurrency}&orderId={orderId}& quoteTime={quoteTime}&sourceAmount={sourceAmount}&terminalId={terminalId}