1.文档说明

1.1文档目的

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

1.2阅读对象

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

1.3技术支持

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

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

2.接口须知

2.1术语含义

• 互联网支付：是指持卡人通过 PC 端（电脑）通过浏览器进行支付的方式。
• 会员：在宝付注册并使用宝付提供的互联网产品的企业或者个人。
• 签约：与宝付签订商业合作协议，使用宝付提供的代收，代付代扣等互联网金融服 务功能。
• 商户：与宝付签订商户合约的宝付会员。
• 终端：商户在与宝付签订某项具体互联网金融功能合作协议自动分配的会员属性， 终端将用于进行具体的金融交易必要参数。
• 订单：是指商户在使用宝付金融功能时产生的交易记录，商户和宝付之间采用订单 作为结算的唯一依据。
• 密钥：是指宝付分配给商户用于进行安全通讯验证的随机字符串或者是数字证书。
• 用户：是指在商户平台注册的企业或个人。

2.2接口准备

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

2.3互联网支付流程

支付流程步骤说明
1.持卡人登录商户网站，选择支付内容并下单，商户网站产生预订单信息，商户提供商户订单号、订单时间、订单金额等信息；
2.持卡人提交订单后，商户将产生的订单信息服务发送给宝付，跳转至宝付支付网关，完成支付请求；
3.持卡人在宝付支付网关选择付款银行；
4.宝付网关跳转至相对应的银行网银支付页面，持卡人在银行支付页面填写网银登录名、密码等信息进行在线支付；
5.银行直接将支付结果反馈给持卡人；
6.银行网银支付系统通知宝付订单支付结果（服务器通知方式）；
7.宝付系统异步将支付结果通知给商户（服务器通知方式）；

2.4编码方式

 报文采用UTF-8编码方式

3.互联网支付网关接口

3.1 支付接口

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

3.1.1 支付请求报文

支付请求报文，是指商户通过HTTPS请求，采用POST方式提交并经过证书对敏感信息加密然后签名提交订单信息至宝付接收地址，宝付将获取参数进行验签，对敏感信息解密，校验一致则把订单信息及结果通知给商户。

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

请求报文

签名数据

加密数据模板:

• 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",
    "product_name": "商品名称",
    "notice_type": "1",
    "additional_info": "附加字段",
    "return_url": "http://10.1.60.129:8080/PayGateRSA2048/ReturnUrl.action",
    "pay_id": "3001",
    "verify_type": "10",
    "ncrptn_sn": "XXXXX",
    "sign_sn": "XXXXX",
    "version": "4.11"
  }

3.1.2 支付返回报文

应答报文（宝付返回报文）
支付返回报文是指宝付在用户交易结束后，会将支付结果以页面返回和交易通知两种方 式同时分别请求商户的页面返回地址和交易通知地址。
支付响应结果都是宝付通过SM2私钥签名发送给商户。商户接收到宝付的响应报文，将接收到的signature内容，用宝付发给商户且后缀为（*.cer）的公钥证书进行验签然后使用。

注：
发送至商户页面返回地址的支付返回报文仅用于在页面上以一种友好的方式通知用户支付结果，代表支付成功或受理成功，并不代表交易成功，请切记不可使用该地址的服务进行交易结果处理。
返回请求地址：商户在订单请求时的页面通知地址和交易通知地址

返回报文实例：

{
    "data_content": {
        "member_id": "100000178",
        "pay_result": "N",
        "succ_money": "0",
        "terminal_id": "100003742",
        "trade_date": "20220727153127",
        "trans_id": "5004240571",
        "ncrptn_sn": "1387287849",
        "sign_sn": "4026178988"
    },
    "signature": "3045022100E9A3AA1D4E6D5A59814975206FC0817FC7704C5E30A8DF2091F19D564D26768502203B4220300E0902F3EC65666DFCF300945904F95D2D37178B33BAB042821CCBA9"
}

返回参数

签名数据

3.1.3 商户接收通知后通知页面内容

商户提交订单支付请求后，用户通过正常的支付流程支付成功或者支付失败后，支付接 口将支付结果通知给商户。
支付结果通知由宝付系统确保一定成功发送给商户。成功发送是指由宝付发出结果通知 到商户后，能够成功获取商户的返回确认（商户接收通知的ReturnUrl在页面上输出OK表 示接收成功<除了OK无任何其他内容>），宝付系统在未确认商户接收通知成功后将会通过 重发机制通知商户（重发次数2~10次，请以第一次收到的支付成功的消息为准，避免进行 多次充值），同时会定时将那些已支付成功但商户未收到通知的交易取出，再次将支付成功 通知发给商户，直到商户接收成功或达到最大重发次数为止。

3.2 查询接口

3.2.1 接口请求参数

接口请求参数是指商户通过HTTPS 请求，采用POST的方式请求宝付的接口地址，并按 照接口参数定义传送数据。宝付支付网关将以纯文本方式返回查询结果。
注：
通过订单查询接口对账及时发现和处理异常的交易，此接口没有查询页面，商户如果无法使用查询接口，也可登录商户前台直接查询。
如果参数传入有误将直接返回提示，该接口将不受理频繁的查询请求，最好每次查询时间间隔 1 分钟。

• 测试接收地址：https://vgw.baofoo.com/order/signQuery
• 正式接收地址：https://gw.baofoo.com/order/signQuery

签名数据

应答报文

签名数据

示例

{
    "data_content": {
        "member_id": "100000178",
        "pay_result": "N",
        "succ_money": "0",
        "terminal_id": "100003742",
        "trade_date": "20220727153127",
        "trans_id": "5004240571",
        "ncrptn_sn": "1387287849",
        "sign_sn": "4026178988"
},
    "signature": "3045022100E9A3AA1D4E6D5A59814975206FC0817FC7704C5E30A8DF2091F19D564D26768502203B4220300E0902F3EC65666DFCF300945904F95D2D37178B33BAB042821CCBA9"
}

3.3 安全要点

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

3.3.1 安全连接访问

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

3.3.2 密钥管理（非常重要）

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

3.3.3 保密通知地址（重要）

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

3.3.4 数据校验（重要）

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

3.3.5 商户域名绑定

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

3.3.6 宝付IP 来源绑定

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

3.3.7 订单重复性校验

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

4.附录

4.1 支付结果

交易成功标志（Result）说明

4.2 支付结果描述

4.3 产品功能

4.3.1 网银支付