1 文档说明

1.1 文档目的

本文档是为宝付签约支付产品定义一个接口规范，以帮助商户技术人员快速接入宝付签约支付网关，并快速掌握其相关功能，便于尽快的投入使用。

1.2 阅读对象

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

1.3 技术支持

在开发或使用宝付签约支付接口时，如果您有任何技术上的疑问，请按如下方式寻求帮助，宝付技术支持人员会及时处理，给予您答复：
技术支持热线：021-68819999-8005
技术支持Email：support@baofoo.com
技术支持QQ：800066689

1.4 术语与定义

1.4.1 符号含义

符号缩写 符号性质 符号说明
M 强制域(Mandatory) 必须填写的属性，否则会被认为格式错误
C 条件域(Conditional) 某条件成立时必须填写的属性
O 选用域(Optional) 选填属性
R 原样返回域(Returned) 必须与先前报文中对应域的值相同的域

数据类型

类型语法：[Max] [Min] [Size] [Type]

  • Max:可选描述符，如果出现，则说明业务要素的长度最大为Size
  • Min:可选描述符，如果出现，则说明业务要素的长度最小为Size
  • Size：强制描述符，指定业务要素UTF-8编码前的最大字符数。
  • Type：强制描述符，指定业务要素的类型属性。Type主要属性如下
字段类型Type 符号说明
code 编码枚举型数据，具体枚举类型见附录：枚举类型
Text 字符串
Numeric 数字
ISODateTime 日期时间，格式为 yyyy-MM-dd HH:mm:ss ,如:2025-03-20 21:54:21
array json数组

字符集及编码

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

保留字

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

1.4.2 术语含义

  • 商户号：宝付提供给商户的唯一编号，是商户在宝付的唯一标识；
  • 终端号：商户在与宝付签订某项具体产品功能的合作协议自动分配的会员属性，将用于进行具体交易的必要参数。
  • 商户流水号：商户请求宝付时提交的流水号，每次请求均不可重复；
  • 原商户订单号：原先支付时商户请求提交的支付订单号。
  • 退款商户订单号：商户退款时请求宝付提交的退款订单号，不可重复。
  • 退款商户流水号：商户请求宝付退款时提交的流水号，每次请求均不可重复；
  • 退款宝付业务流水号：宝付返回给商户的唯一退款订单号，是宝付记录一笔退款订单的唯一标识。

1.5 通讯模式

  • 采用HTTPS方式进行通讯。
  • 请求方式：POST

1.6 报文说明

1.6.1 请求头报文

域名 变量名 必填 备注
商户号 member_id M 宝付提供给商户的唯一编号
终端号 terminal_id M 终端号
交易类型 txn_type M 详见附录交易类型枚举
版本号 version M 1.0.0
格式 format M 各个接口业务参数的格式化类型，固定值json
字符集 charset M 字符集编码，固定值UTF-8
时间戳 timestamp M 时间戳与宝付支付系统时间误差不超过10分钟，格式为yyyyMMddHHmmss，如：2025年4月15日15点50分12秒表示为：20250415155012
签名类型 sign_type M RSA:11 ;国密SM2: 10
签名证书序列号 sign_sn M 发送方公钥证书序列号，用于接收方验签证书选择
加密证书序列号 ncrptn_sn M 接收方公钥证书序列号，用于接收方解密证书选择
签名字符串 signature M 使用发送方私钥签名的非对称密钥，并做16进制转码
业务数据 data_content M 业务数据报文，JSON格式

请求报文公共格式

member_id=120838,txn_type=181,version=1.0.0,format=json,charset=UTF-8,timestamp=20250618135526,sign_type=RSA,terminal_id=23462,sign_sn=1,ncrptn_sn=1,data_content=【参考业务请求参数示例】,signature=47586A224689881F52F565E56C00E11AC7DD164EB4D2316EC0C47596F21D36EAC42E7122D0AE920249CFA116167EE7F3176688671516524F2341DB74724C198B05B4BA3B48D8A0D46E8B81113EFDF684CC68C5600AF79CB0556E6CE84625AB707262AD8E3D709A42B8C4643E63E0E8E82CE873F5E5DDE32C2727EB471F9F41FB

业务请求参数示例

{
  "acc_info": "c648371cd096394bd247d440b79d39c3cec53819f641ae24fc0ce2316296b62cae7ed57d01a381ca1393072eb73ee7bc6331a58c48bd13b7b0a4e7e31a7a15f0",
  "agent_member_id": "120838",
  "agent_terminal_id": "23462",
  "bank_code": "",
  "card_type": "",
  "dgtl_envlp": "31785009E2B8F260ABBFE91050BB5320BD27AAF47842A070C76FFB90DD891A957D97F788E15D9A5EBC300CA18D32249C088904FD105028D720840DF3B3CED5B156C429F0790373D89838F7497A91286F7CD476D74A5643CDFD1FAF0BEF4E47283E5ABFFA3B8D54D83529A98405E7042965B267039B6F8494E338EAAB3385F0B1",
  "front_fail_url": "https://www.baidu.com/",
  "front_url": "https://www.baidu.com/",
  "member_id": "1235293",
  "notify_url": "https://bf-test-system.baofoo.com/receive/protocolNotice?wx=TXJ001",
  "out_order_no": "e063b577f7d64ad1817aa6ab9e71c599",
  "req_extend_params": "{\"req_param_1\":\"req_param_1\"}",
  "req_reserved1": "req_reserved1",
  "req_reserved2": "req_reserved2",
  "risk_item": "{\"goodsCategory\":\"02\",\"riskRateInfo\":{\"usrLoginMethod\":\"11111\",\"merUserRegDt\":\"20250619160434\",\"deviceID\":\"iphone\"}}",
  "send_time": "2025-06-19 16:04:34",
  "terminal_id": "50009",
  "user_id": "432333199305118713"
}

1.6.2 返回头报文

参数含义 参数名称 必填 参数备注
商户号 member_id M 宝付提供给商户的唯一编号
终端号 terminal_id M 终端号
交易类型 txn_type M 同请求时传入参数
版本号 version M 1.0.0
格式 format M 各个接口业务参数的格式化类型，固定值json
字符集 charset M 字符集编码，固定值UTF-8
时间戳 timestamp M 时间戳与宝付支付系统时间误差不超过10分钟，格式为yyyyMMddHHmmss，如：2025年4月15日15点50分12秒表示为：20250415155012
签名类型 sign_type M RSA:11 ;国密SM2: 10
签名证书序列号 sign_sn M 发送方公钥证书序列号，用于接收方验签证书选择
加密证书序列号 ncrptn_sn M 接收方公钥证书序列号，用于接收方解密证书选择
签名字符串 signature M 使用发送方私钥签名的非对称密钥，并做16进制转码
业务数据 data_content M 业务数据报文，JSON格式
响应码 response_code M 当该值为：SUCCESS,则可以取data_content，详见：【响应码】
响应信息 response_message M 响应信息

响应报文公共格式

{
    "member_id": "120838",
    "terminal_id": "23462",
    "txn_type": "181",
    "charset": "UTF-8",
    "version": "1.0.0",
    "format": "json",
    "sign_type": "RSA",
    "sign_sn": "1139986924",
    "ncrptn_sn": "1",
    "signature": "7E3FDC3C53A578772785646EA356010D78E9510049B92C8C8DC4E374C1789C3895C45B121F88C833DB5B0643186DAD0975479021D73DE04F53A552EF46F9F919C054D0480F5C3E9A91370E3B14D31A3ED3945200B259CE03920E1FAA348804606B42377967EC3B54E23607598A5EED134064475B866C8C09352B0EA052197D47",
    "data_content": "响应业务参数示例",
    "response_code": "SUCCESS",
    "response_message": "成功"
}

响应业务参数示例

{\"member_id\":\"1235293\",\"terminal_id\":\"50009\",\"agent_member_id\":\"120838\",\"agent_terminal_id\":\"23462\",\"result_code\":\"0000\",\"result_message\":\"交易成功\",\"order_no\":\"250619101010198001147502\",\"out_order_no\":\"e063b577f7d64ad1817aa6ab9e71c599\",\"txn_type\":\"181\",\"order_status\":\"PROCESSING\",\"send_time\":\"2025-06-19 16:04:48\",\"contract_url\":\"https://mcashier.95516.com/mobile/api/unifiedOrderIndex.action?tn=506614796599055474817&sign=37806bc2c75898baaa649d02d58196a57e0e0fd96e78790b2c3d02efcdb415b7\",\"req_reserved1\":\"req_reserved1\",\"req_reserved2\":\"req_reserved2\",\"extend_params\":{}}

1.6.3 通知请求头报文

参数含义 参数名称 必填 参数备注
商户号 member_id M 宝付提供给商户的唯一编号
终端号 terminal_id M 终端号
通知类型 notify_type M 通知类型
版本号 version M 1.0.0
格式 format M 各个接口业务参数的格式化类型，固定值json
字符集 charset M 字符集编码，固定值UTF-8
签名类型 sign_type M RSA:11 ;国密SM2: 10
签名证书序列号 sign_sn M 发送方公钥证书序列号，用于接收方验签证书选择
加密证书序列号 ncrptn_sn M 接收方公钥证书序列号，用于接收方解密证书选择
签名字符串 signStr M 使用发送方私钥签名的非对称密钥，并做16进制转码
业务数据 data_content M 业务数据报文，JSON格式

请求报文公共格式

{
  "response_code": "SUCCESS",
  "response_message": "OK",
  "member_id": "120838",
  "terminal_id": "23462",
  "charset": "UTF-8",
  "version": "1.0.0",
  "format": "json",
  "notify_type": "SIGN",
  "sign_type": "RSA",
  "ncrptn_sn": "1",
  "sign_sn": "1139986924",
  "signature": "",
  "data_content": {
    "member_id": 1235293,
    "order_no": "250619101010198001147502",
    "protocol_no": "5e1d8e72d0110c4388a28e46f52a11bedf7ff117f18c5ae338c5c8ad7f1d74b7",
    "bank_code": "BOC",
    "extend_params": {},
    "result_message": "成功",
    "out_order_no": "e063b577f7d64ad1817aa6ab9e71c599",
    "dgtl_envlp": "4B4819E79F6F4113F19758C6B05EBAC6089F7C37E43A95FEDBB988F7FCEF99A6EA5E98E5311ED58310BDD0543AECA8029F1ABB763F0A3A6A198217EF5A8E028E5B8C7BEEB7FD6E12C049D2CAA63D51B154DBFFE6CFB0FFDFD478422222B5ABD612597496E3067E4C3BE526D594D6C8D593712ADAEEA18A13663CBEBB968311EF",
    "agent_member_id": 120838,
    "order_status": "SUCCESS",
    "agent_terminal_id": 23462,
    "send_time": "2025-06-19 16:08:55",
    "protocol_status": "VALID",
    "sgn_acc": "625897******7178",
    "bank_name": "中国银行",
    "result_code": "SUCCESS",
    "terminal_id": 50009,
    "req_reserved1": "req_reserved1",
    "req_reserved2": "req_reserved2"
  }
}

业务请求参数示例

{
  "acc_info": "c648371cd096394bd247d440b79d39c3cec53819f641ae24fc0ce2316296b62cae7ed57d01a381ca1393072eb73ee7bc6331a58c48bd13b7b0a4e7e31a7a15f0",
  "agent_member_id": "120838",
  "agent_terminal_id": "23462",
  "bank_code": "",
  "card_type": "",
  "dgtl_envlp": "31785009E2B8F260ABBFE91050BB5320BD27AAF47842A070C76FFB90DD891A957D97F788E15D9A5EBC300CA18D32249C088904FD105028D720840DF3B3CED5B156C429F0790373D89838F7497A91286F7CD476D74A5643CDFD1FAF0BEF4E47283E5ABFFA3B8D54D83529A98405E7042965B267039B6F8494E338EAAB3385F0B1",
  "front_fail_url": "https://www.baidu.com/",
  "front_url": "https://www.baidu.com/",
  "member_id": "1235293",
  "notify_url": "https://bf-test-system.baofoo.com/receive/protocolNotice?wx=TXJ001",
  "out_order_no": "e063b577f7d64ad1817aa6ab9e71c599",
  "req_extend_params": "{\"req_param_1\":\"req_param_1\"}",
  "req_reserved1": "req_reserved1",
  "req_reserved2": "req_reserved2",
  "risk_item": "{\"goodsCategory\":\"02\",\"riskRateInfo\":{\"usrLoginMethod\":\"11111\",\"merUserRegDt\":\"20250619160434\",\"deviceID\":\"iphone\"}}",
  "send_time": "2025-06-19 16:04:34",
  "terminal_id": "50009",
  "user_id": "432333199305118713"
}

异步通知说明：

  • 异步通知以POST方式访问商户设置的通知URL
  • 商户系统接收到宝付异步通知，并正确的完成相应的业务处理后，须同步返回大写OK字符串<除了OK无任何其他内容>。
  • 由于网络抖动等异常因素以及商户侧未按照约定返回OK，宝付支付系统会多次请求商户侧通知地址，商户系统必须能够正确处理重复的通知。建议商户系统收到通知进行处理时，采用数据锁进行并发控制，检查对应业务数据状态，如未处理，则进行处理，防止多次通知造成资金损失。
  • 宝付支付系统会在未正常收到商户侧返回OK时，将通过重发机制再次通知商户（重发次数 2~10 次，请以第一次收到的支付成功的消息为准，避免进行多次支付），直到商户接收成功或达到最大重发次数为止则不再进行通知，商户应调用订单查询接口确认订单状态。

响应码

状态码 描述
SUCCESS 成功
FAIL 失败
作者：xingchuanyi  创建时间：2025-03-28 13:49
最后编辑：何淼  更新时间：2025-07-16 17:25