1 文档说明

1.1 文档目的

本文档的目的是为宝付订单支付网关平台定义一个接口规范，以帮助商户技术人员快速接入宝付订单支付网关和查询订单，并快速掌握订单支付网关的相关功能，便于尽快的投入使用。

1.2 阅读对象

• 商户开发人员、维护人员和管理人员
• 宝付订单支付产品相关的技术人员

1.3 技术支持联系方式

在开发或使用宝付订单支付接口时，如果您有任何技术上的疑问，请按如下方式寻求帮助，宝付技术支持人员会及时处理，给予您答复。

• 技术支持热线：021-68819999-8005
• 技术支持Email：support@baofoo.com
• 技术支持QQ：800066689

1.4 术语与定义

1.4.1 符号含义

数据类型

类型语法：[Max][Min][Size][Type]
Max:可选描述符，如果出现，则说明业务要素的长度最大为Size
Min:可选描述符，如果出现，则说明业务要素的长度最小为Size
Size：强制描述符，指定业务要素UTF-8编码前的最大字符数。
Type：强制描述符，指定业务要素的类型属性。Type主要属性如下

字符集及编码

报文采用Unicode字符集，UTF-8编码方式。

保留字

报文内容中“|”、“%”、 “#”、 “^”、 “-”等为局部保留字，在相关以此类字符作为分隔符的复合字段中不应出现。

1.5 通讯模式

采用HTTPS方式进行通讯。

2 接口须知

2.1 术语含义

 订单支付：面向企业用户，集企业交易信息及支付资金一体化转接的对公支付产品，为收付款企业提供7*24小时的订单通知和订单付款的支付服务，实现支付有因，保障交易的真实性。
 会员：在宝付注册并使用宝付提供的互联网产品的企业或者个人。
 签约：与宝付签订商业合作协议，使用宝付提供的代收，代付代扣等互联网金融服 务功能。
 商户：与宝付签订商户合约的宝付会员。
 终端：商户在与宝付签订某项具体互联网金融功能合作协议自动分配的会员属性， 终端将用于进行具体的金融交易必要参数。
 订单：是指商户在使用宝付金融功能时产生的交易记录，商户和宝付之间采用订单 作为结算的唯一依据。
 密钥：是指宝付分配给商户用于进行安全通讯验证的随机字符串或者是数字证书。
 用户：是指在商户平台注册的企业或个人。

2.2接口准备

 仔细阅读本文档相关申明和注意事项
 商户调试接口相关的文档
 商户的支付网关商户号、终端、密钥

2.3订单支付流程

支付流程：
 流程步骤说明

1. 用户登录商户网站，选择支付内容并下单，商户网站产生预订单信息，商户提供商户订单号、订单时间、订单金额等信息；
2. 用户提交订单后，商户将产生的订单信息服务发送给宝付，宝付把订单提交至付款方的发卡行；
3. 付款方用户登陆网银，选择付款订单完成支付；
4. 银行直接将支付结果反馈给付款用户；
5. 银行系统通知宝付订单支付结果（服务器通知方式）；
6. 宝付系统异步将支付结果通知给商户（服务器通知方式）；

3.订单支付网关接口

3.1 通用主体报文

通用主体报文指商是指发送报文的主体，具体参数信息则在加密数据中。
申请报文主体

返回报文主体

*说明
A）“应答码resp_code”为“0000”时，获取“加密响应体data_content”中的业务参数，只有在“应答码resp_code”和“加密响应体data_content”中的参数都为“成功”时，订单方为成功。

3.2 支付接口

宝付支付订单支付是指用户从商户应用先经过宝付下单，进行相关信息的填写，再由宝付提交至银行处理的支付方式。
注：
请勿在测试环境使用大额支付，测试金额不予返还，建议使用1分钱进行测试；
上线时，请及时更换正式商户号、终端号和密钥，并提交至正式环境。

3.2.1 支付请求报文

测试接收地:https://vgw.baofoo.com/orderPay
正式接收地址:https://gw.baofoo.com/neptune/orderPay

把加密数据加密后放入主体报文“data_content”中请求宝付接口地址。

请求报文加密数据

说明：
A）“交易方式”“ pay_type”：
a）“direct”时，交易资金不过宝付，由清算机构直接结算至收款方的账户，所以在报文中需要填写收款方的收款账户信息；商户需要自行处理资金的差错问题。该模式需要申请开通。该模式下分账业务不支持
b）“guarantee”时，交易资金过宝付，由宝付统一按照与商户的约定结算至商户预留在宝付的结算账户。此模式下报文中可选填收款方账户的账户信息。该模式暂不支持
c）“freeze”时，付款方资金会冻结在付款方的账户中，并且通过“订单解冻交易”或“订单批次支付申请”来解冻或者划拨被冻结的资金。暂不支持。

B）“冻结交易附加字段”
a）“冻结交易附加字段”“ payee_freeze_sign”当“交易方式”为“freeze”时必填，该字段用于标识冻结资金划拨时是否由宝付结算。“BAOFU”为资金过宝付，由宝付按照与商户的约定结算至商户在宝付预留的结算账户，报文中收款方信息字段可选填。“OTHER”为冻结资金不过宝付，由清算机构直接结算至收款方账户，报文中收款方信息字段为必填。

C）“附言”
“附言”remark字段在交易方式“pay_type”为“guarantee”时，在字段头会默认上送一个宝付订单号。

D）“二级商户信息 subMerInfo 数据接口”
a） 属性：json对象
b） 数据格式

二级商户单元信息列表（subMerUnits）

商品单元信息列表（prodUnits）

二级商户信息：填写要求

1.B2B采购/核心企业平台结算/缴费场景

一级商户信息（商户代码、商户名称、商户类型）：上送平台商户的信息
二级商户信息【二级商户实际数量、二级商户单位信息列表、二级商户单位信息列表（二级商户名称、类型、代码、证件类型、证件号码、商品相关信息）】：上送平台入驻商户作为二级商户信息及各二级商户旗下的商品信息，如为自营可上送与平台商户同样的信息然后上送商品信息。

2.经营收款场景

一级商户信息（商户代码、商户名称、商户类型）：上送发起收款的渠道信息，如XX银行网银收款平台、XX收款平台、XX系统
二级商户信息【二级商户实际数量、二级商户单位信息列表、二级商户单位信息列表（二级商户名称、类型、代码、证件类型、证件号码、商品相关信息）】：上送收款企业的信息作为二级商户信息，然后将收款科目如物业费、水电费等作为商品信息上送，支持上送多个收款科目信息。

详情举例（收款案例）

"subMerInfo":{
 "subMerTotalQty":"1",
 "subMerShowQty":"1",
 "subMerUnits":[
 {
    "subMerName":"XX物业公司",
    "subMcc":"6012",
    "subMerId":"物业公司在银行侧的身份标识",
    "subMerCertifType":"01",
    "subMerCertifNo":"91T1234567890123456"
    "subMerTotalAmt":"10000000",
    "subMerTotalKindsQty":"1",
    "prodUnitQty":"1",
    "prodUnits":[
    {
        "prodName":"XX月的房屋租金",
        "prodPrice":"10000000",
        "prodQty":"1",
        "prodAmt":"10000000"
    }]
 }]
}

加密数据模板:
 JSON

{
    "member_id": "XXXX",
    "page_url": "http://localhost:8080/PayGateRSA2048/PageUrl.html",
    "amount": "1",
    "user_name": "用户名称",
    "order_money": "100",
    "trans_id": "PAGATID1551150255542",
    "trade_date": "20190226110415",
    "notice_type": "1",
    "additional_info": "附加字段",
    "return_url": "http://10.1.60.129:8080/PayGateRSA2048/ReturnUrl.action",
    "pay_id": "3001",
    "terminal_id": "XXXXX"
}

3.2.2 支付返回报文

应答报文（宝付返回报文）
支付响应结果都是宝付通过非对称加密公私钥方式发送给商户。商户接收到宝付的响应报文，将接收到的data_content内容，用宝付发给商户且后缀为（*.cer）的公钥证书进行解密。
返回报文实例：

{"error_code":"0000","error_msg":"成功","data_content":"6c0b4d30aefaa925f1fcf05533ea39a28de4bbf7e17ba0beead165402f83fec9503c047936ca35d73d7e1aaadd4cf55ae050aa5b940ca22ab82a0d1d6f9b7895079989caea45df55edecf583b10d72c63f40293b6bba610d6cc8ca475037a24eb7c341654e5cbf60f208cdc45576c68f45cd91dc0bd9c7c334f64c7fcca43a67"}

请求响应结果的数据类型根据请求version决定，4.2为json。输出内容包括

data_content 响应json内容

3.3 查询接口

3.3.1 接口请求参数

接口请求参数是指商户通过HTTPS 请求，采用POST的方式请求宝付的接口地址，并按 照接口参数定义传送数据。宝付支付网关将以纯文本方式返回查询结果。

测试地址:https://vgw.baofoo.com/queryOrderPay
正式地址:https://gw.baofoo.com/neptune/queryOrderPay

请求报文加密数据

3.3.2 支付返回报文

{"error_code":"0000","error_msg":"成功","data_content":"6c0b4d30aefaa925f1fcf05533ea39a28de4bbf7e17ba0beead165402f83fec9503c047936ca35d73d7e1aaadd4cf55ae050aa5b940ca22ab82a0d1d6f9b7895079989caea45df55edecf583b10d72c63f40293b6bba610d6cc8ca475037a24eb7c341654e5cbf60f208cdc45576c68f45cd91dc0bd9c7c334f64c7fcca43a67"}

data_content 响应json内容

说明：
A）“冻结资金实时可用余额”
在冻结支付查询时，“冻结资金实时可用余额”为0，则说明无冻结资金。“订单解冻交易”申请后查询结果为0，“订单解冻交易”则申请成功。

3.4支付撤销

3.4.1接口请求参数

测试地址:https://vgw.baofoo.com/cancelOrderPay
正式地址:https://gw.baofoo.com/neptune/cancelOrderPay

请求报文加密数据

3.4.2返回报文

说明：
支付撤销如果未获得可重复撤销，但同一笔订单只能撤销一次。

3.5 订单解冻交易

3.5.1 接口请求参数

订单解冻交易仅适用于冻结支付场景中，用于将已冻结资金（部分或全部）原路退回到原付款账户。
本交易为同步应答。
本交易不参与清算。

测试地址:https://vgw.baofoo.com/unFreezeOrderPay
正式地址: https://gw.baofoo.com/neptune/unFreezeOrderPay

请求报文加密数据

3.5.2 应答报文

{" resp_code ":"0000","resp_msg":"成功","data_content":"6c0b4d30aefaa925f1fcf05533ea39a28de4bbf7e17ba0beead165402f83fec9503c047936ca35d73d7e1aaadd4cf55ae050aa5b940ca22ab82a0d1d6f9b7895079989caea45df55edecf583b10d72c63f40293b6bba610d6cc8ca475037a24eb7c341654e5cbf60f208cdc45576c68f45cd91dc0bd9c7c334f64c7fcca43a67"}

data_content 响应json内容

说明：如果未获得最终结果，可以通过查询接口获取解冻结果。

3.6 订单批次支付申请

3.6.1 接口请求参数

测试地址:https://vgw.baofoo.com/batchOrderPay
正式地址: https://gw.baofoo.com/neptune/batchOrderPay

请求报文加密数据

3.6.2应答报文

{" resp_code ":"0000","resp_msg":"成功","data_content":"6c0b4d30aefaa925f1fcf05533ea39a28de4bbf7e17ba0beead165402f83fec9503c047936ca35d73d7e1aaadd4cf55ae050aa5b940ca22ab82a0d1d6f9b7895079989caea45df55edecf583b10d72c63f40293b6bba610d6cc8ca475037a24eb7c341654e5cbf60f208cdc45576c68f45cd91dc0bd9c7c334f64c7fcca43a67"}

data_content 响应json内容

3.7 支付通知

订单支付后根据 return_url 通知商户参数如下：
注：订单支付使用“freeze:冻结交易”后，调用订单批次支付申请返回

data_content解密后参数

应答报文

模式一：标准应答
data_content解密后参数

模式二：简易应答
该模式不使用通用主体报文
异步通知以GET和POST方式发送到商户配置的接收地址，商户接收到签约结果，并且进行相应处理之后，需要商户接收通知的地址在页面上输出 OK 表示接收成功<除了 OK 无任何其他内容>，告诉宝付已经成功接收并处理完毕，宝付系统在未得到商户接收通知成功的反馈时，将通过重发机制再次通知商户（重发次数 2~10 次，请以第一次收到的签约成功的消息为准），直到商户接收成功或达到最大重发次数为止。

3.8 分账通知

分账成功后根据 share_notify_url 通知商户参数如下：
注：订单支付使用“freeze:冻结交易”后，调用订单批次支付申请返回

data_content解密后参数

应答报文
模式一：标准应答
data_content解密后参数

模式二：简易应答
该模式不使用通用主体报文
异步通知以GET和POST方式发送到商户配置的接收地址，商户接收到签约结果，并且进行相应处理之后，需要商户接收通知的地址在页面上输出 OK 表示接收成功<除了 OK 无任何其他内容>，告诉宝付已经成功接收并处理完毕，宝付系统在未得到商户接收通知成功的反馈时，将通过重发机制再次通知商户（重发次数 2~10 次，请以第一次收到的签约成功的消息为准），直到商户接收成功或达到最大重发次数为止。

3.9 安全要点

如果说功能是业务的基础，那么后期的运营管理就是业务得以进展的源泉，这里的运营 管理包括了安全方面的要点。以下列举了宝付为了提高安全性，保障商户权益提供的几项安 全保障功能。

安全连接访问

宝付提供HTTPS安全连接方式。 HTTPS是HTTP的一种扩展，这种方式可以把数据先在本地加密然后通过网络传输，宝付接受后解密处理，这个可以避免数据被非定向包劫持后泄漏交易敏感数据。

密钥管理（非常重要）

密钥的目的是为了防止在交易数据被定向劫持后被篡改，导致经济损失。 密钥虽然可以防止数据被篡改的危险，但是如果密钥因为某种原因被泄露了，比如人事变动，计算机病毒，开发人员安全意识不足，注册邮箱管理不善被盗等。所以需要妥善保管 密钥，如果保留邮箱的务必也要保证邮箱的安全。密钥被泄漏了，那么熟悉宝付支付业务的 犯罪分子就可以利用你的密钥进行违法犯罪活动，造成商户的经济损失。
密钥一定要保存在安全的文件服务系统或者数据库之上，并且必须需要加密保存，防止黑客浸入等可能的威胁。

保密通知地址（重要）

通知地址保密的好的话，那么基本上犯罪分子是很难进行破坏性行为的，因为没有破坏目标。
通知地址切记与页面通知地址一致，这也违背了保密通知地址的原则，请切记。

数据校验（重要）

数据校验包含签名校验和参数校验。 数据校验一定要进行，要保证数据的完整性和正确性，防止被篡改的可能。 数据校验的精确度一定要高，一定要严格按照文档所描述的校验规则进行校验，特别是标记成功和代表金额的参数，金额等关键参数还要进行双向匹配校验，多一层校验就多一份 保障，这在金融行业尤为重要。

商户域名绑定

宝付支持进行商户域名绑定，目的是宝付将校验商户的订单来源以及订单的返回和通知 地址，绑定了域名，可以极大的保障商户的安全性，当然，域名保管也很重要。

宝付IP 来源绑定

为了提高商户的安全级别，保障商户的交易安全，宝付将无偿给合作商户提供宝付的IP，以便商户进行通知来源校验，防止虚假通知和伪造通知。

订单重复性校验

宝付为了确保交易能够准确的通知到商户，有可能会重复发送通知消息，为此宝付提醒商户，采取正确的防重复校验。
大多数校验通知都采取先查询后更新的方式，这种方式存在一个很大的漏洞，当多个通 知请求在很短的一个时间内达到时，查询数据有可能是脏数据，导致订单重复更新，后续工 作重复执行。
对于此种情况，宝付结合自身校验情况，分享两个校验方式。
1) 如果是单线程或者订单资源在一个共享区域，那么可以采取锁定资源的方式，每次 调用加锁，每次调用完毕解锁。
2) 大部分数据都存在数据库，宝付绝大多数都是这种情况，利用数据库的特性来控制， 在我们调用数据库更新信息时，数据库会返回给我们更新条目数，我们利用这个特性，这样 操作，当我们更新订单时，把这个订单的原始状态作为条件进行更新，当我们短时间内操作 更新时，第二次更新必然不成功，因为条件不满足了，状态变了，那么数据库在第二次就会 返回更新数量为0，这样我们就发现问题了，这就是熟称的“乐观锁”。

4.附录

4.1 支付结果错误码

4.2 产品功能

4.2.1 订单支付

*支持银行请参考支持银行列表
-订单支付支持银行列表

• 更多联行号下载
  • 联行号数据