聚合支付接口

正式环境发送异步通知只支持443或80端口 其他端口暂时不支持

本文档定义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 否 32 支付人所持卡号。 6225881257400000
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 直连微信APP支付必填；
服务商公众号支付必填;
支付宝支付方式建议填写;
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
多个商品：商品1|数量;商品2|数量;商品3|数量;
productNum Number 是 8 商品数量，整型数字 例：
单个商品数量：1
多个商品数量：商品总数量
productId String 是 32 商品代码，请根据我司提供的商品代码附录进行填写。 如服饰箱包，填写：100200(如多个商品填写最主要的商品代码)
productDesc String 否 256 商品描述，字符串 iphone7 128G 玫瑰金
ext1 String 否 128 扩展字段1，英文或中文字符串支付完成后，按照原样返回给商户 当deviceType=1且payType=6-2或6或6-1245或2；
deviceType=2且payType=5或5-2（支付宝支付）时，
和当deviceType=2且payType=D（服务商公众号支付）时，该字段为JSON格式，内容参考如下：
{ "userProv":"1","userCity":"xxxxxxx", "userGpsAddr":{"latitude":"xxx.xxxxxx","longitude":"xxxx.xxxxx"} }
userProv-用户所属省份；
userCity-用户所属城市；
上述两个字段请参考我司提供的省份城市码表；
userGpsAddr-用户GPS地址，格式如上文参考，纬度和经度，各自最长不超过20位。
ext2 String 否 128 扩展字段2，英文或中文字符串支付完成后，按照原样返回给商户 扩展字段2
openId String 否 128 关注微信公众号的用户分配的id 如：
op5EP1G8XtyYH1VvmAbleB3AYgc8
deviceType String 是 1 1：pc端支付2：移动端支付 1
payType String 是 4 当deviceType=1时
2：支付宝扫码
4：网银直连
6：聚合网关，包含多种支付方式（返回跳转地址)
     2：支付宝扫码
     4：网银支付
     5：快捷支付
7：微信直连扫码
8：支付宝直连扫码

当deviceType=2时
4: 快捷支付（汇数网关）
5：移动端聚合，包含多种支付方式（返回跳转地址）
      2：支付宝H5支付
      4：快捷支付
7:微信公众号支付（返回payInfo）
8:微信小程序支付（返回payInfo）
6:协议支付 （详细信息请参考协议支付接口文档）
B:微信直连APP（返回payInfo）
C:支付宝直连APP（返回payInfo）
D:服务商公众号支付（返回跳转链接）
E:银联云闪付APP支付（返回payInfo） 		当deviceType=1时：
聚合网关可指定一个或多个支付方式,形如:
6-1245或者6展示全部开通支付方式
6-4只显示网银支付
6-5只显示快捷支付

当deviceType=2时：
移动端聚合网关可指定一个或多个支付方式，形如：
5-123或者5展示所有支付方式
5-2只有支付宝H5支付
5-4只有快捷支付
bankId String 否 8 银行代码，请参考银行代码表附录。网银直连时必填；即deviceType=1且payType为4时 如中国农业银行，ABC
redoFlag String 否 1 1表示同一订单禁止重复提交标志，预留字段
2表示 同一订单，可重复提交（订单状态为未支付成功）
divFlag String 否 1 指定交易需要分账时上送 1表示分账，不上送或上送0表示不分账；分账需要联系我司运营进行开通配置
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预下单返回

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

参数名称 参数含义 最大长度 参数说明
url 返回地址 1024 需转义
type=1：商户需将url转换成二维码展示
type=2：商户需将用户的浏览器跳转至该url
type=3：此字段为空
queryUrl 扫码结果轮训地址 1024 需转义,当返回的type=1时，此字段提供轮询地址，商户系统可以通过后台请求该地址查询扫码支付的状态，返回json格式的字符串。status=1表示支付成功格式：{"state":"0"}
type 返回类型 1 1：url是二维码
2：url跳转地址
3：其他（payInfo）
respCode 错误代码 6 000000 成功，其它为异常
respMsg 错误描述 512 失败错误描述
payInfo 支付信息 64 当type为3、4时返回回。
type=3时：
如果是支付宝APP直连支付、微信APP直连支付、微信APP支付、微信公众号支付、微信小程序支付，则为微信生成的预支付回话标识，用于后续接口调用中使用

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
extInfo Json 可选 不定长 需单独申请配置，配置后返回该字段，目前包括：authTransId（微信支付宝端支付单号），authMerOrderId（微信支付宝端商家订单号），actualPayType（实际支付方式），deviceType（实际支付的设备类型）；前两个字段当微信/支付宝支付时返回，后两个字段值可联合得到消费者最后选择的支付方式。（参考请求中payType和deviceType的定义）由于银联特殊规则，当支付方式为支付宝时，银联会在支付宝的原始支付单号前加两位数字，若接入方需要该字段进行逻辑处理，请依据银联规则裁剪长度。（若银联规则有变更，我司会在得到通知后告知新规则） 2020-11-16 V4.5新增]样例为：{"deviceType":"1","authMerOrderId":"07012011163829365007287","actualPayType":"2","authTransId":"932020111622001466645715328950"}该字段以key:value形式返回，每个key之间,分隔；接入时需要支持该字段的扩展，以备后续该字段增加/减少key值。

注意：商户接收到的字段值为urlEncode之后的值（如：extInfo=%7B%22deviceType%22%3A%222%22%2C%22authMerOrderId%22%3A%2207212011253343123302602%22%2C%22actualPayType%22%3A%227%22%2C%22authTransId%22%3A%224200000744202011259445484075%22%7D），需要对=号后面的内容进行urlDecode，上文解码之后的内容为：{"deviceType":"2","authMerOrderId":"07212011253343123302602","actualPayType":"7","authTransId":"4200000744202011259445484075"}
bankDealId String 否 128 银行交易号，后端通道系统的交易流水号。
需要按照海关179 号文报送的商户可以解析该字段存储，格式为1 位字母（标识银联/网联/其他）+流水号。其中U-银联，N-网联，D-直连，O-其他目前后端渠道在断直连背景下 A-支付宝直连，b-微信直连，基本均为U或者N		 如：U20181203215458215 表示交易渠道为银联，流水号为20181203215458215
partyOrderId String 可选 64 支付宝直连扫码、支付宝直连APP、微信直连扫码、微信直连APP四种场景下返回
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

交易规则

1. 支付宝扫码支付

收单：交易金额transAmt（0,100) 交易成功，transAmt[100，200） 交易失败

退款：退款金额transAmt（0，50）退款成功； transAmt[50，100）退款失败

微信直连退款：transAmt（2，50)，退款成功； transAmt[50，100)退款失败

支付宝扫码无需进行扫码，只需要获取我司支付结果即可

2. 网银支付

网银测试时选择兴业银行（其余会跳转其他银行真实环境）

3. 快捷支付

工商银行：卡号：6223150000123456789 姓名：张三
农业银行：卡号：6228220000123456789 姓名：张三
建设银行：卡号：5453242000123456789 姓名：张三
招商银行：卡号：6282900000123456789 姓名：张三
中国银行：卡号：5123160000123456789 姓名：张三
身份证号，手机号随意填写，格式正确即可
绑卡申请获取验证码：111111 支付申请获取验证码：111111