1 文档说明

1.1 文档目的

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

1.2 阅读对象

  • 商户开发人员、维护人员和管理人员
  • 宝付线下打款相关的技术人员

1.3 技术支持联系方式

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

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

1.4 术语与定义

1.4.1 符号含义

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

2 业务方案说明

2.1 应用场景

线下打款API产品（新模式）是宝付为满足商户，通过固定码/宝付分配给商户固定账户打款的模式，与宝付发生线下打款交易，以非页面手动点击，而是以纯后台的模式发起。

3 接口须知

3.1 请求交易接口

线下打款请求交易接口是指客户将打款金额、收款方账户号，指定入账商户号，流水号等信息发送至宝付，宝付进行下单，校验，充值等操作。

3.1.1 交易URL

测试环境地址：https://vgw.baofoo.com/cutpayment/api/backTransRequest
正式环境地址：https://public.baofoo.com/cutpayment/api/backTransRequest

3.1.2 请求报文

序号 域名 变量名 必填 备注
01 版本号 version M 4.0.0.0
02 商户号 member_id M 宝付提供给商户的唯一编号
03 终端号 terminal_id M
04 交易类型 txn_type M 取值0431
05 交易子类 txn_sub_type M 42
06 加密数据类型 data_type M data_type=xml或json
07 加密数据 data_content M 具体参数如下加密数据。注意：加密之前,先将组装的数据（请参照数据模版组装）进行Base64编码转化，然后再进行证书加密。

加密数据

序号 域名 变量名 必填 备注
01 终端号 terminal_id M
02 商户号 member_id M 宝付提供给商户的唯一编号
03 交易子类 txn_sub_type M 42
04 商户订单号 trans_id M 商户发起的支付订单号
05 商户流水号 trans_serial_no M 8-20 位字母和数字，每次请求都不可重复
06 附加字段 additional_info O 长度不超过 128 位
07 请求方保留域 req_reserved O
08 接入类型 biz_type C 其他：不填写和默认0000,表示为储蓄卡支付。
09 充值金额 order_money M 单位：分
10 收款方账户号 payee_acct_code M 收款方账户号
11 付款方账户号 payer_acct_code M 付款方账户号
12 付款方开户名 payer_user_name M 付款方开户名
13 银行流水号 bank_serial_no C
14 指定入账商户号 pay_member_id C 如果传入，则入账到此账号，如果未传，则该值为member_id的值
15 回调地址 call_back_url C 如果传入，则异步通知使用该url；如果未传入，则不做异步通知

3.1.3 应答报文

序号 参数含义 参数名称 必填 参数备注
01 应答码 resp_code M 应答码为0000时，表示订单预提交成功
02 应答信息 resp_msg M
03 版本号 version R 4.0.0.0
04 终端 ID terminal_id R
05 商户号 member_id R 平台或商户号
06 数据类型 data_type R xml/json
07 交易类型 txn_type R 取值0431
08 交易子类 txn_sub_type R 42
09 附加字段 additional_info O
10 预留字段 req_reserved O
11 接入类型 biz_type R 其他：不填写和默认0000,表示为储蓄卡支付
12 商户流水号 trans_serial_no R 8-20 位字母和数字，每次请求都不可重复
13 商户订单号 trans_id R 商户订单号

3.1.4 范例

3.1.4.1 请求范例

https://tgw.baofoo.com/cutpayment/api/backTransRequest?version=4.0.0.1&member_id=123456&terminal_id=123456&txn_type=331&biz_type=0000&txn_sub_type=09&data_type=xml&data_content=2ac723cbe2ba7dab519525dec8208ab70c240d8bf8981ef5fdba238857612efe271dc212d4088a991ff5ce4cdf145a80c0cd24b43bd59ffd4c0f2a84b478196330f4fc76a0175feb932eb91c0ceef344099d1716a389fc5f503fece1bd69a6750715518402f116f72aff78da831816e29c2c4112af7a3aeeaec8821126a43ede694432aeb48b999e4369a0ea6f95e3f26eac6737976659c7d749b9adaea76483c4bb90efe11e30fd61fddd5fd3528aa01779bdbb953197652700cd82b6c51cd817e0374f1feee3befecb8773e90018ca79a4219e267c9e30e9efc96b61a45cfb980804eb5adbd4240cfee1cba25c7fd59162bb97359890fce2e21b3a060ad3174511e6db8adfd47cdaa6ad9a1a8928386a95d8d27d0f525a2124b66eba18b69735e8cb432a6be2af45304c8602b486adc6d2cd97bcd81d7939f130a41760ff92ae1f4b70960bcf9d5d4f5b57c65c72b81b7d420c7dc17181d3d62b298e4d2b74241cbe49a1067dc965f2fa333e723f71a0707e1bf9853073be0323dc5134eb2d688f3f949ea1e44344fa5b50a2e57e4a502f478ad67511e6db3503b9247269a91991b478b2b38fe72ad48bdef4144497b1a5072ecb5c2665763a6c36dbb0e6e2ac426bd1483911ec590da4464ce1ce0c7a9b846a589d38b65517cc6f09436b062d5cbd08d56507244956c1cf7236644fe890d1665a18742df9c93366fb8f98d06dd2ead44080fe94dabaebd1f46b99dac5da928ce89161c1304d7f4ecf5d3e8ead49cbd1373593a038c6f48df699a44b12aed6ac78f0b6b7a1287b730ae7a03053dae72061849fa8b472cb171c2740878b35bf5b4f9a1ecf910c5c41637fb5d98554e6b19aff8df4ed5be8c1519e59599298c70ddd1c9da5351f541a6f86cd4077a6788600f576f9bac39bee73f44274f2e07710809a0df0d71472d405d56db3d8488b66716de1c8cfdcb85577640bd53ce8895e1b29959931c8038e6159c496374ad9108187fe43bafd1c19796b978659427c7d7ad9124c14abffe7bd225b95a02c6cd0d2fd3536f9979a29e1421430085a81e3212edd67dd7975451dbd261f13524d382d12987b1a3f257c2615a6fc23c9ae850ebc09d106ff0ed2f3836ee19bd2cbe376b5f50a84f78a89d8b1182a18c8ddf10d266723fb82310293ecb656a2a9a2559453d702eed7949c190baae17d028260c1024a6c0ba2e335317e88b

请求密文组装

  • xml格式
    <?xml version="1.0" encoding="UTF-8" ?>
<data_content>
<terminal_id>123456</terminal_id>
<member_id>123564</member_id>
<txn_sub_type>42</txn_sub_type>
<trans_id>123456</trans_id>
<trans_serial_no>1234567890</trans_serial_no>
<additional_info>附加字段</additional_info>
<req_reserved>请求方保留域</req_reserved>
<order_money>70000</order_money>
<payee_acct_code>6222021001113527219 </payee_acct_code>
<payer_acct_code>43050186393600000000</payer_acct_code>
<bank_serial_no>430501863936788667870</bank_serial_no>
<pay_member_id>1841654</pay_member_id>
<call_back_url>https://public.xxx.com/</call_back_url>
<share_info>100000363,10;100000364,90 </share_info>
</data_content>
  • json格式
    {
"terminal_id":123456,
"member_id":123564,
"txn_sub_type:42,
"trans_id":"123456",
"trans_serial_no":"1234567890",
"additional_info":"附加字段",
"req_reserved":"请求方保留域",
"order_money":"1000000",
"payee_acct_code":"收款方账户号",
"payer_acct_code ":"付款方账户号",
"payer_user_name ":"付款方开户名",
"bank_serial_no":"收款方账户号",
"pay_member_id":"付款方账户号",
"call_back_url ":"付款方开户名",
"share_info":"100000363,10;100000364,90 "
}
    备注：如果明文参数中data_type的值为xml，这里组装密文则使用xml格式，反之为json。将以上组装的字符串先进行base64进行加密，然后使用商户私钥进行证书加密，生成的密文则对应为data_content的值。

3.1.4.1 应答范例

6b269fdc40c6356713cf899cb0162ed03296299409d4745012078bd11b2f746045d77bd6b0ba637b73fa811c4300a05a87ce9881985a82995348ead4242ede9ba7952ed4a235e7288665ee9332c1c31f25c092059ed7155bc7bcbfd5069c8487832d376dceadd4201588b6fe1e3f91abe80c916e26ade7ee1cdfbc6e44748feb2c3987c3127f7200c4487464630e4e6ca51586010d05fbb8a200a0d5d988922238446ccce21f14b5c1fb56e4fac43f020fa3b3d9f991a2f4435a62ba61a9496acc15a3594fb6a0d63d96423aa3ddcc8ab75526c07ee4eaab08fe6a0f3ca10fd3494e700bda13dc5dfca099666f3eb8832537648e560580a3d6e8969d7dd9700b8118a994ce24e0d410f42f8c0aa02e6331ae5caf2afd4ac56fd2ca2491768d1409cdf7b81f50fa0f39bde32291dd02782195b17c3588298d6842a67924f62cdb96be4856c961fb067e509b94bd712f4a8a313b5578b1c0c441911d360b529c34fff9f7e0ff50d1e7e976ef2f7779765cadbe5cd2ba2396cecfa8ce85ef0ced8402b4d2d43e39237cccb1e83c58d8632b975214ea99dc8289e56365615e7e9c80fd665a5dd6ead4195e247a7fcd3e4282fa04a37eec2cd3f3d7382a7aaf40043117e78f8486042925899cfb5c5771f2b89a7b4d2a9baf1a3bb4179f7aa139c96e36df19746a167bbbe0663a92c3a91b856b02699464f23e2330c080915307f23d243f9db15683cd08156cc54e36fc4e5784a9384a888b240f097a0340e3d2046b21b21384ed446a4b6ca26df89c8bb746b21084d70841511aeedf0dfaad560f7f633196c7e1d5255e61866147d890e70156b6cf9796f80f64b47c239223cbf3e9c4262ec8dc5c41106218ac80ff110ab88b70c57281a384b4d2595e005ebcb70343e459dce32641c8fdeb00ee667fad61707f5263030fadabfd425f0ca8a652eec703ca5eeb0e37a9dbd8e1eff415fe72c20af520ab1c3bfc836e80de8713e66c2cec9ef89cb8b13e4acd4d5a7e7e358d10ba744694ab670ba483ee86ea10489cc905e9be8055ef287915e5f123

应答密文解析

  • Xml格式
    <?xmlversion="1.0"encoding="UTF-8" ?>
<result>
<resp_code>0000</resp_code>
<resp_msg>交易成功 </resp_msg>
<version>4.0.0.1</version>
<terminal_id>456789</terminal_id>
<member_id>123456</member_id>
<data_type>xml</data_type>
<txn_sub_type>37</txn_sub_type>
<txn_type>0431</txn_type>
<req_reserved>预留字段</req_reserved>
<additional_info>附加字段</additional_info>
<biz_type>0000</biz_type>
<trans_serial_no>3451592355</trans_serial_no>
<trans_id>1984854162</trans_id>
</result>
  • Json格式
    {
" version ":" version ",
"member_id":"123456",
"terminal_id":"456789",
"resp_code":"0000",
"resp_msg":"交易成功",
"data_type":"json",
"biz_type ":"biz_type ",
" resp_msg ":"交易成功",
"req_reserved":"预留字段",
"txn_sub_type":"37",
"txn_type":"0431",
"trans_serial_no":"3451592355",
"trans_id":"1984854162"
}

3.2 交易查询接口

线下打款交易查询接口支持客户查询线下打款订单状态。

3.2.1 交易URL

测试环境地址：https://vgw.baofoo.com/cutpayment/api/backTransRequest
正式环境地址：https://public.baofoo.com/cutpayment/api/backTransRequest

3.2.2 请求报文

序号 域名 变量名 必填 备注
01 版本号 version M 4.0.0.0
02 商户号 member_id M 宝付提供给商户的唯一编号
03 终端号 terminal_id M
04 交易类型 txn_type M 取值0431
05 交易子类 txn_sub_type M 40
06 加密数据类型 data_type M data_type=xml或json
07 加密数据 data_content M 具体参数如下加密数据。

加密数据

序号 域名 变量名 必填 备注
01 交易子类 txn_sub_type M 40
02 商户号 member_id M 宝付提供给商户的唯一编号
03 终端号 terminal_id M
04 商户订单号 trans_id M 商户发起的支付订单号
05 商户流水号 trans_serial_no M 8-20 位字母和数字，每次请求都不可重复
06 接入类型 biz_type C 其他：不填写和默认0000,表示为储蓄卡支付。
07 请求方保留域 req_reserved O
08 附加字段 additional_info O

3.2.3 应答报文

序号 参数含义 参数名称 必填 参数备注
01 应答码 resp_code M 0000表示交易成功，仅代表查询订单状态成功，不代表订单充值成功，具体订单什么状态需要看state的值，具体参考下面state各状态代表的含义
02 应答信息 resp_msg M
03 商户订单号 trans_id R 商户订单号
04 终端号 terminal_id R
05 交易类型 txn_type R 取值0431
06 交易子类 txn_sub_type R 40
07 数据类型 data_type R xml/json
08 版本号 version O 4.0.0.0
09 附加字段 additional_info O
10 预留字段 req_reserved O
11 商户号 member_id M 平台或商户号
12 商户流水号 trans_serial_no R 8-20 位字母和数字，每次请求都不可重复
13 接入类型 biz_type R 默认0000
14 订单状态 state M 订单的状态：0：待确认（预下单时的状态），1：通过（订单已充值成功），2：拒绝（订单审核被拒绝），3：待处理（订单已确认，待处理）
15 成功时间 succ_time O 仅state=1时即订单已经加值成功的时候才有成功时间,其余状态为空值

3.2.4 范例

3.2.4.1 请求范例

https://tgw.baofoo.com/cutpayment/api/backTransRequest?version=4.0.0.1&member_id=123456&terminal_id=123456&txn_type=331&txn_sub_type=10&data_type=xml&data_content=1f3f2b265e7fee210b6a04c78430d491956eae7858077f0c4ec90b34e5b94c7fb7bafcc8a58d55edb8880b97450843b544e33a3e6c31cf6461407925b05b81c49f2411574472531978600cdaabc73274f67065c0c6a5cc74d484f5552b5fd4039163fbbd65a904fc73b5891c6605d519b9e829bd2a36e21a911d86a9ba9e383b0a733c7ea357b8b36de7b50a1e9af45e8364a5dd4dde05416bf7ef768b609fa28eba198b0999bc06523799ad45f7693e4f22ae8392f1b6f55ae060531c80234787779fb5bbd3e26dbe7a2000776953c5c8affc4ec971d82c2679cf3bf11472346b74d271e5afec79f092af0599dfd5b7c6027276b211496e45871fba23af0d026e2c9aef9df41e210fbe90dea67f4ad606b7c4d8112d8c2a69a854c9d819c87b5c96d4d7ff92da4bbd540bbb994454374d4d963c8d900f8a462478bab8ff02daf3d6fef40f7602276a66e7c681e99264420fbafd57ad0bcdaecbc9473f3e6493f996d898cc288eed5e839e4e3a8ad77822ea57c7640a12337c51b3d42aecd8a5605b90623d94f8b5007f851504b42d32677c1d76a0b63a76c5689422f906363faafceeb1c216a2f95ee4e9fc5d638596df6e8378ec67b6598f3f663a5473f700fa6633ab5b852d1ffa323e648360713240b97b0ba68ff243167c995760f93e6677d68609c713e662be1b75e6c23bbb97209618116ce51bded2a113331a12b252011b35019c168e2e06f26409cc73a46ae467fa6b676ab8a11a1d1d29a68af8d55200cf6db46d259aa92e872728e410e50577c0f8aa028cd582c8adf564265e06299ff1a940e943fdf053e548840488f5dbc7804ea65330646e161e312c6e0dc9b5d0d78e9ba44e18966786568ea87bd7ef941647dd5d2efd60c616b98373b056

请求密文组装

  • xml格式
    <?xml version="1.0" encoding="UTF-8" ?>
<data_content>
<version>4.0.0<version>
<txn_type>0431<txn_type>
<txn_sub_type>40</txn_sub_type>
<data_type>xml</data_type>
  <biz_type>0000</biz_type>
<terminal_id>123456</terminal_id>
<member_id>5867528</member_id>
<trans_serial_no>1234567890</trans_serial_no>
<trans_id>123456789048448</ trans_id>
<additional_info>附加字段</additional_info>
<req_reserved>请求方保留域</req_reserved>
</data_content>
  • json格式
      {
"version":"4.0.0",
"txn_type ":"0431",
"txn_sub_type":"40",
"data_type":"json",
"biz_type ":"0000",
"terminal_id":"123456",
"member_id":"5867528",
"trans_serial_no ":"1234567890",
"trans_id ":"123456789048448",
"additional_info ":"附加字段",
"req_reserved":"请求方保留域"
}
    备注：如果明文参数中data_type的值为xml，这里组装密文则使用xml格式，反之为json。将以上组装的字符串先进行base64加密，然后使用商户私钥进行证书加密，生成的密文则对应为data_content的值。

3.2.4.2 应答范例

6b269fdc40c6356713cf899cb0162ed03296299409d4745012078bd11b2f746045d77bd6b0ba637b73fa811c4300a05a87ce9881985a82995348ead4242ede9ba7952ed4a235e7288665ee9332c1c31f25c092059ed7155bc7bcbfd5069c8487832d376dceadd4201588b6fe1e3f91abe80c916e26ade7ee1cdfbc6e44748feb2c3987c3127f7200c4487464630e4e6ca51586010d05fbb8a200a0d5d988922238446ccce21f14b5c1fb56e4fac43f020fa3b3d9f991a2f4435a62ba61a9496acc15a3594fb6a0d63d96423aa3ddcc8ab75526c07ee4eaab08fe6a0f3ca10fd3494e700bda13dc5dfca099666f3eb8832537648e560580a3d6e8969d7dd9700b8118a994ce24e0d410f42f8c0aa02e6331ae5caf2afd4ac56fd2ca2491768d1409cdf7b81f50fa0f39bde32291dd02782195b17c3588298d6842a67924f62cdb96be4856c961fb067e509b94bd712f4a8a313b5578b1c0c441911d360b529c34fff9f7e0ff50d1e7e976ef2f7779765cadbe5cd2ba2396cecfa8ce85ef0ced8402b4d2d43e39237cccb1e83c58d8632b975214ea99dc8289e56365615e7e9c80fd665a5dd6ead4195e247a7fcd3e4282fa04a37eec2cd3f3d7382a7aaf40043117e78f8486042925899cfb5c5771f2b89a7b4d2a9baf1a3bb4179f7aa139c96e36df19746a167bbbe0663a92c3a91b856b02699464f23e2330c080915307f23d243f9db15683cd08156cc54e36fc4e5784a9384a888b240f097a0340e3d2046b21b21384ed446a4b6ca26df89c8bb746b21084d70841511aeedf0dfaad560f7f633196c7e1d5255e61866147d890e70156b6cf9796f80f64b47c239223cbf3e9c4262ec8dc5c41106218ac80ff110ab88b70c57281a384b4d2595e005ebcb70343e459dce32641c8fdeb00ee667fad61707f5263030fadabfd425f0ca8a652eec703ca5eeb0e37a9dbd8e1eff415fe72c20af520ab1c3bfc836e80de8713e66c2cec9ef89cb8b13e4acd4d5a7e7e358d10ba744694ab670ba483ee86ea10489cc905e9be8055ef287915e5f123

应答密文组装

  • Xml 格式
    <?xml version="1.0" encoding="UTF-8" ?>
<result>
<version>4.0.0.1</version>
<resp_code>BF00128</resp_code>
<resp_msg>该笔订单不存在</resp_msg>
  <trans_id>16546465658</trans_id>
<member_id>123456</member_id>
<terminal_id>456789</terminal_id>
<txn_sub_type>40</txn_sub_type>
<txn_type>0431</txn_type>
<data_type>xml</data_type>
<req_reserved>预留字段</req_reserved>
<additional_info>附加字段</additional_info>
<state>1 </state>
<succ_time>20160119123456</succ_time>
</result>
  • Json 格式
    {
"version":"4.0.0.1",
"resp_code":"BF00128",
"resp_msg":"该笔订单不存在",
"trans_id":"154913633346",
"terminal_id":"456789",
"txn_type":"0431",
"txn_sub_type":"40",
"data_type":"json",
"member_id":"123456",
"additional_info":"附加字段",
"req_reserved":"预留字段",
"state":"订单状态",
"succ_time":"成功时间"
}

3.3 异步通知

3.3.1 功能说明

自动建单、BM录单模式，线下审批配置异步通知地址后，可接收异步通知。接口录单模式，交易请求中可选上送异步通知地址。若上送，可接收异步通知。

3.3.2 通知报文

data_content=09f27e40024994307c854b5bff54fdbb79e7ed9900e6013e58a816e31ef39088f42417a5d87d05e01508b93bea5be2af8fa0562b8259b07eff3fb61fee70d69a5550561731b6bf1319a98091180490d6fd783af72d20e7bf53e3b924f6455f93d7234fff06fef004f05e6795903e21535a1b19fa75473fc99a8b8ff2aadc146f85bf2bb168ccfa724a77e24f4aea12ed0634b4810feed3c1c799bdbd03b98c8378ca5fa68efd1bccd54d8f9a7ad80912f8e5c29ff74f0b8bef247c4e4319f8778366f06f3b547f9586bf229e3b15bd38523999bb58f9c11fd68df33da5ad5d99f6a528c69b178248804da25b082ab08f9c504a4db70139f1a540614fa21cebb3

3.3.3 解密后报文

  • Xml
    <result>
<resp_code>0000</resp_code>
<resp_msg>成功</resp_msg>
<memberTransId>test0000000000a01</memberTransId>
<state>1</state>
<orderMoney>1.01</orderMoney>
<succTime>20170808143943</succTime>
<bankTranNo>0000000000a01</bankTranNo>
</result>
  • Json
    {
"resp_code":"0000"
"resp_msg":"成功"
"memberTransId":"test0000000000a01",
"orderMoney":"1.01",
"bankTranNo":"0000000000a01",
"state":"1",
"succTime":"20170808143943"
}

3.3.4 加密数据

序号 参数含义 参数名称 必填 参数备注
01 应答码 resp_code M
02 应答信息 resp_msg M
03 商户订单号 memberTransId M
04 订单金额 orderMoney M
05 状态 state M 1:通过
06 成功时间 succTime M yyyyMMddHHmmss
07 银行流水号 bankTranNo M
08 充值商户号 memberId M
09 记账日期 succTime M
10 付款银行 bankName M
11 付款户名 payerUserName M
12 付款账号 payerAcctCode M
13 交易备注 summary M

4. 附录

4.1 应答码

  • 成功类
错误码 含义
0000 成功
  • 交易处理中或未知，需要后续查询
错误码 含义
BF00100 系统异常，请联系宝付
BF00112 系统繁忙，请稍后再试
BF00113 交易结果未知，请稍后查询
BF00115 交易处理中，请稍后查询
  • 交易失败
错误码 含义
BF00116 该终端号不存在
BF00118 报文中密文解析失败
BF00405 付款户未在白名单中
BF00404 付款账户白名单未启用
BF00403 收款方账户号不存在
BF00401 线下打款订单已确认,请勿重复提交
BF00400 线下打款订单已成功,请勿重复提交
BF00399 订单已存在,请勿重复提交
BF00398 线下打款审核未通过
BF00135 交易金额不正确
BF00128 订单不存在
BF00406 调用接口参数缺失
BF00411 匹配码未配置或未开启

4.2 交易子类

取值 交易子类
40 线下打款订单查询
42 线下打款固定匹配码操作接口/账户操作接口
作者：闫婷  创建时间：2023-06-12 18:07
最后编辑：xiaofeng  更新时间：2024-09-19 18:06