协议支付接口

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

提交参数

1.1预下单

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

协议参数

参数 类型 是否必填 最大长度 描述 示例值
inputCharset String 是 1 字符集,固定值：1
1-UTF-8		 1
pageUrl String 是 256 接受支付结果的页面地址 https://www.merchant.com/pay/notifyReceiverPg.do
bgUrl String 是 256 服务器接受支付结果的后台地址 https://www.merchant.com/pay/notifyReceiverBg.do
version String 是 10 网关版本,固定值：3.0 3.0
language String 是 3 网关页面显示语言种类，固定值：1
1-中文显示		 1
signType String 是 256 签名类型，固定值：4
4-RSA加签		 4

业务参数

参数 类型 是否必填 最大长度 描述 示例值
merchantAcctId String 是 32 会员账号，由我司提供的商户号+01，共13位数字 1001234001101
terminalId String 是 8 终端号，由我司提供的终端号 999999
payerName String 条件必选 64 支付人姓名，中文名，网银直连或 涉及到资金跨境时必填 张三
payerContactType String 否 1 支付人联系方式类型，固定值：1或者2
1-代表电子邮件方式
2-其他联系方式 		1
payerContact String 否 64 支付人联系方式，根据payerContactType的方式填写对应字符，邮箱或者其他联系方式 13400000000
payerIdentityCard String 条件必选 32 支付人身份证号码，字符串，18位身份证号；跨境结算且为直连模式时必填 320125198800001000
mobileNumber String 否 32 支付人手机号 15800001111
cardNumber string 是 16 支付人所持卡号。 6225881257400000 只支持16位或19位数字
shortCardno string 协议支付必填 10 短卡号 为卡号的前6位及后4位拼接而成，明文传输 6225880000
cvv string 协议支付必填 4 CVV号，支付卡为信用卡时必填需要加密后以密文形式传输，加密前明文长度限制为4 1111 （密文）
expiration string 协议支付必填 4 卡有效期，支付卡为信用卡时必填，格式为MMYY需要加密后以密文形式传输，加密前明文长度限制为4 0922（密文）
customerId string 否 32 支付人在商户系统的客户编号 jd1001
customerIp string 否 32 保留字段
orderId string 是 32 商户订单号，只允许使用字母、数字、_,每商户提交的订单号，必须在自身账户交易中唯一 order20170728120001299
inquireTrxNo string 否 32 查询流水号
商户从CHINAPNR外汇询价时需填入PNR返回的工单号，用于锁定汇率，不填则根据交易时间实时询价		 交易前已在CHINAPNR询价返回工单号：2089，则填入2089
orderCurrency String 是 3 订单币种，3位币别码，详情请参照币别代码附录。当该字段不为CNY时，必须与settlementCurrency一致。 如美元：USD。
settlementCurrency String 是 3 结算币种，3位币别码，详情请参照币别代码附录。 如美元：USD。
orderAmount Number 是 12 商户订单金额，整型数字，单位为分。日韩元支持的最小单位为元。 如100元，则填写10000
orderTime String 是 14 数字串，一共14位。格式为：年[4位]月[2位]日[2位]时[2位]分[2位]秒[2位] 20071117020101
productName String 是 256 商品名称 iphone7
productNum Number 是 8 商品数量，整型数字 1
productId String 是 32 商品代码，请根据我司提供的商品代码附录进行填写。 如服饰箱包，填写：100200
productDesc String 否 256 商品描述，字符串 iphone7 128G 玫瑰金
ext1 String 否 128 扩展字段1，英文或中文字符串支付完成后，按照原样返回给商户 扩展字段1
ext2 String 否 128 扩展字段2，英文或中文字符串支付完成后，按照原样返回给商户 扩展字段2
openId String 否 128 关注微信公众号的用户分配的id 如：
op5EP1G8XtyYH1VvmAbleB3AYgc8
deviceType String 是 1 1：pc端支付2：移动端支付 1
payType String 是 4 当deviceType=2时
6：协议支付
6
bankId String 否 8 银行代码，请参考银行代码表附录 如中国农业银行，ABC
redoFlag String 否 1 同一订单禁止重复提交标志，预留字段
signMsg String 是 2048 签名字符串请参考签名方法。 参数1={参数1}&参数2={参数2}&……&参数n={参数n}然后进行商户密钥进行加签 
-	按以下固定字段顺序进行加签
-	仅对非空字段进行加签
pageUrl={pageUrl}&bgUrl={bgUrl}&merchantAcctId={merchantAcctId}&terminalId={terminalId}& customerId={customerId}&orderId={orderId}&orderAmount={orderAmount}&orderTime={orderTime}&productDesc={productDesc}&ext1={ext1}&ext2={ext2}& deviceType={deviceType}&payType={payType}&shortCardno={shortCardno}

返回结果

交易结果会同时通知提交时pageUrl和bgUrl对应的地址。

1.1.1预下单返回

预下单请求处理完成后，会返回如下数据,：

参数名称 参数含义 最大长度 参数说明
respCode 错误代码 6 000000 成功，其它为异常
respMsg 错误描述 512 失败错误描述

1.1.2返回商户支付结果

参数 类型 是否必填 最大长度 描述 示例值
merchantAcctId String 是 32 会员账号，与提交订单时的保持一致 1001234001101
terminalId String 是 8 终端号，与提交订单时的保持一致 999999
version String 是 10 网关版本，与提交订单时一致 3.0
payType String 是 4 支付方式，与提交订单时一致 00
bankId String 是 8 银行代码，与提交订单一致 BOC
orderId String 是 32 商户订单号，与提交订单时一致 order20170728120001299
orderTime String 是 14 商户订单提交时间，与提交订单时一致 20171117020101
orderCurrency String 是 3 订单币种，与提交订单时一致 USD
orderAmount Number 是 12 商户订单金额，与提交订单时一致 10000
dealId String 是 32 收单系统交易号，该交易在收单系统对应的交易号;商户号下唯一。 20000100
dealTime String 是 14 交易时间，交易失败时可能为空。收单系统对交易进行处理的时间,格式为：年[4位]月[2位]日[2位]时[2位]分[2位]秒[2位] 20170728120001
ext1 String 否 128 扩展字段1，与提交订单时一致 扩展字段1
ext2 String 否 128 扩展字段2，与提交订单时一致 扩展字段2
bankDealId String 否 128 银行交易号，后端通道系统的交易流水号。
需要按照海关179 号文报送的商户可以解析该字段存储，格式为1 位字母（标识银联/网联/其他）+流水号。其中U-银联，N-网联，D-直连，O-其他目前后端渠道在断直连背景下，基本均为U或者N		 如：U20181203215458215 表示交易渠道为银联，流水号为20181203215458215
payResult String 是 2 处理结果:
10-支付成功
其他均为失败 		10
errCode String 是 128 错误代码，详细请参考
signMsg String 是 2048 签名字符串，商户需对该字段进行验签。详情请参考验签方法。对于所有值不为空的参数及对应值，按照字母顺序组成字符串 DSA：参数1={参数1}&参数2={参数2}&……&参数n={参数n}然后进行支付平台证书加密形成密文后进行2048位的Base64转码。 
-	下述字段按首字母排列进行验签
-	仅对非空字段进行验签
bankDealId={bankDealId}&bankId={bankId}&dealId={dealId}&dealTime={dealTime}&errCode={errCode}&ext1={ext1}&ext2={ext2}&merchantAcctId={merchantAcctId}&orderAmount={orderAmount}&orderCurrency={orderCurrency}&orderId={orderId}&orderTime={orderTime}&payResult={payResult}&payType={payType}&terminalId={terminalId}&version={version}

请求示例

请参考具体Demo。 下载地址

PG返回示例

http://192.168.1.111:8081/QAMOCK-Test/notifyReceiverPg.do?dealTime=20170825155744&errCode=000000&merchantAcctId=1001215986501&orderTime=20170825155735&orderCurrency=CNY&dealId=2000003898&version=3.0&bankId=cmb&terminalId=0010003&payResult=10&ext1=ext1&ext2=ext2&orderAmount=600&signMsg=URgwbxHfL%2FE3YNiIBpP0vbL1UPtvbsqfAvGMpLFo5nIW2Bq786Mi0uLrvsIs8BHHw7B3f%2BRDEkdjE96nxfT4YcP4cYXkzk1SPAlAFwUy4JDgOQAOwYVgUG7%2FcHWx6Ef7uIMWZxyNxQ2SCC1WVBXsWPfnIRhzvGPDpgiqzK46cdA%3D&payType=10&orderId=20170825155741712

BG返回示例

BG以http Key-Value方式返回，如：
dealTime=20170825155744
errCode=000000
merchantAcctId=1001215986501
orderTime=20170825155735
orderCurrency=CNY
dealId=2000003898
version=3.0
bankId=cmb
terminalId=0010003
payResult=10
ext1=ext1
ext2=ext2
orderAmount=600
signMsg=URgwbxHfL%2FE3YNiIBpP0vbL1UPtvbsqfAvGMpLFo5nIW2Bq786Mi0uLrvsIs8BHHw7B3f%2BRDEkdjE96nxfT4YcP4cYXkzk1SPAlAFwUy4JDgOQAOwYVgUG7%2FcHWx6Ef7uIMWZxyNxQ2SCC1WVBXsWPfnIRhzvGPDpgiqzK46cdA%3D
payType=10
orderId=20170825155741712
`

2.1绑卡申请

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

协议参数

参数 类型 是否必填 最大长度 描述 示例值
inputCharset String 是 1 字符集,固定值：1
1-UTF-8		 1
version String 是 10 网关版本,固定值：3.0 3.0
language String 是 3 网关页面显示语言种类，固定值：1
1-中文显示		 1
service String 是 30 接口名称
绑卡 BINDCARD
绑卡确认 BINDCONFIRM
解绑 UNBIND 		BINDCARD
signType String 是 256 签名类型，固定值：4
4-RSA加签		 4

业务参数

参数 类型 是否必填 最大长度 描述 示例值
merchantAcctId String 是 32 会员账号，由我司提供的商户号+01，共13位数字 1001234001101
terminalId String 是 8 终端号，由我司提供的终端号 999999
customerId String 是 32 支付人在商户系统的客户编号 jd1001
reqSeqId String 是 32 请求流水号，只允许使用字母、数字、_,每商户提交的流水号，必须在自身账户交易中唯一 order20170728120001299
reqTime String 是 14 数字串，一共14位。格式为：年[4位]月[2位]日[2位]时[2位]分[2位]秒[2位] 20171117020101
transType String 条件必选 4 WH-协议支付 WH
smsType String 是 1 签约类型 Y-发短信 N-不发短信 Y 目前仅支持Y，默认Y
cardName string 是 64 持卡人姓名，中文名。需要加密后以密文形式传输，加密前明文长度限制为64 张三（密文）
cardId string 是 32 持卡人需绑卡的卡号。需要加密后以密文形式传输，加密前明文长度限制为32 6225881257400000（密文）
certType string 是 8 证件类型 01-身份证 默认01
certId string 是 32 持卡人身份证号码，字符串，18位身份证号。 需要加密后以密文形式传输，加密前明文长度限制为32 320125198800001000（密文）
mobilePhone string 是 32 银行卡绑定手机号。 需要加密后以密文形式传输，加密前明文长度限制为32 15800001111（密文）
cvv string 协议支付必填 4 CVV号，支付卡为信用卡时必填需要加密后以密文形式传输，加密前明文长度限制为4 1111 （密文）
expiration string 协议支付必填 4 卡有效期，支付卡为信用卡时必填，格式为MMYY需要加密后以密文形式传输，加密前明文长度限制为4 0922（密文）
ext1 string 否 128 扩展字段1，英文或中文字符串 扩展字段1
ext2 string 否 128 扩展字段2，英文或中文字符串 扩展字段2
signMsg String 是 2048 签名字符串请参考签名方法。 参数1={参数1}&参数2={参数2}&……&参数n={参数n}然后进行商户密钥进行加签 
-	按以下固定字段顺序进行加签
-	仅对非空字段进行加签
-	加密字段明文加签
merchantAcctId={merchantAcctId}&terminalId={terminalId}&customerId={customerId}&reqSeqId={reqSeqId}&reqTime={reqTime}&transType={transType}&smsType={smsType}&cardName={cardName}&cardId={cardId}&certType={certType}&certId={certId}&mobilePhone={mobilePhone}&cvv={cvv}&expiration={expiration}&ext1={ext1}&ext2={ext2}

2.1.2 同步返回参数

绑卡申请请求处理完成后，会同步返回如下数据：

参数名称 参数含义 最大长度 参数说明
respCode 错误代码 6 000000 成功，其它为异常
respMsg 错误描述 512 错误代码不为000000时提供
bindSeqId 交易跟踪编号 32 PnR的绑卡申请流水号

2.2 绑卡确认

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

协议参数

参数 类型 是否必填 最大长度 描述 示例值
inputCharset String 是 1 字符集,固定值：1
1-UTF-8		 1
version String 是 10 网关版本,固定值：3.0 3.0
language String 是 3 网关页面显示语言种类，固定值：1
1-中文显示		 1
service String 是 30 接口名称
绑卡 BINDCARD
绑卡确认 BINDCONFIRM
解绑 UNBIND 		BINDCONFIRM
signType String 是 256 签名类型，固定值：4
4-RSA加签		 4

业务参数

参数 类型 是否必填 最大长度 描述 示例值
merchantAcctId String 是 32 会员账号，由我司提供的商户号+01，共13位数字 1001234001101
terminalId String 是 8 终端号，由我司提供的终端号 999999
customerId String 是 32 支付人在商户系统的客户编号 jd1001
reqSeqId String 是 32 请求流水号，只允许使用字母、数字、_,每商户提交的流水号，必须在自身账户交易中唯一 order20170728120001299
reqTime String 是 14 数字串，一共14位。格式为：年[4位]月[2位]日[2位]时[2位]分[2位]秒[2位] 20171117020101
bindSeqId String 是 32 汇付返回绑卡申请流水号
smsCode String 是 8 短信验证码
ext1 string 否 128 扩展字段1，英文或中文字符串 扩展字段1
ext2 string 否 128 扩展字段2，英文或中文字符串 扩展字段2
signMsg String 是 2048 签名字符串请参考签名方法。 参数1={参数1}&参数2={参数2}&……&参数n={参数n}然后进行商户密钥进行加签 
-	按以下固定字段顺序进行加签
-	仅对非空字段进行加签
-	加密字段明文加签
merchantAcctId={merchantAcctId}&terminalId={terminalId}&customerId={customerId}&reqSeqId={reqSeqId}&reqTime={reqTime}&bindSeqId={bindSeqId}&smsCode={smsCode}&ext1={ext1}&ext2={ext2}

2.2.2 同步返回参数

绑卡申请请求处理完成后，会同步返回如下数据：

参数名称 参数含义 最大长度 参数说明
respCode 错误代码 6 000000 成功，其它为异常
respMsg 错误描述 512 错误代码不为000000时提供

2.3 解绑

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

协议参数

参数 类型 是否必填 最大长度 描述 示例值
inputCharset String 是 1 字符集,固定值：1
1-UTF-8		 1
version String 是 10 网关版本,固定值：3.0 3.0
language String 是 3 网关页面显示语言种类，固定值：1
1-中文显示		 1
service String 是 30 接口名称
绑卡 BINDCARD
绑卡确认 BINDCONFIRM
解绑 UNBIND 		UNBIND
signType String 是 256 签名类型，固定值：4
4-RSA加签		 4

业务参数

参数 类型 是否必填 最大长度 描述 示例值
merchantAcctId String 是 32 会员账号，由我司提供的商户号+01，共13位数字 1001234001101
terminalId String 是 8 终端号，由我司提供的终端号 999999
customerId String 是 32 支付人在商户系统的客户编号 jd1001
reqSeqId String 是 32 请求流水号，只允许使用字母、数字、_,每商户提交的流水号，必须在自身账户交易中唯一 order20170728120001299
reqTime String 是 14 数字串，一共14位。格式为：年[4位]月[2位]日[2位]时[2位]分[2位]秒[2位] 20171117020101
transType String 是 4 WH-协议支付 WH
cardId String 是 10 解绑卡短号 为卡号的前6位及后4位拼接而成，明文传输 6225880000
ext1 string 否 128 扩展字段1，英文或中文字符串 扩展字段1
ext2 string 否 128 扩展字段2，英文或中文字符串 扩展字段2
signMsg String 是 2048 签名字符串请参考签名方法。 参数1={参数1}&参数2={参数2}&……&参数n={参数n}然后进行商户密钥进行加签 
-	按以下固定字段顺序进行加签
-	仅对非空字段进行加签
-	加密字段明文加签
merchantAcctId={merchantAcctId}&terminalId={terminalId}&customerId={customerId}&reqSeqId={reqSeqId}&reqTime={reqTime}&transType={transType}&cardId={cardId}&ext1={ext1}&ext2={ext2}

2.3.2 同步返回参数

绑卡申请请求处理完成后，会同步返回如下数据：

参数名称 参数含义 最大长度 参数说明
respCode 错误代码 6 000000 成功，其它为异常
respMsg 错误描述 512 错误代码不为000000时提供