服务接口文档-基金代付

1. 引言

1.1. 服务账户

1.1.1. 账户参数说明

1.1.2. 测试服务账户

1.2. 电子账户

商户提出申请，基金科技为商户开通电子账户功能，支付款项结算至电子账户中，商户根据接口进行款项代付。在首次开通电子商户时，电子账户号和商户号相同。

2. 接口规则

2.1. 协议规则

调用API必须遵循以下规则

2.2. 参数规定

交易金额

交易金额默认为人民币交易，接口中参数支付金额单位为【分】，参数值不能带小数。对账单中的交易金 额单位为【元】

产品类型

• trade.agent.general 普通代付
  
  trade.agent.matendow 垫资代付
  
  trade.agent.daytime 日间代付
  
  trade.agent.idling 空转代付
  

货币类型

货币类型的取值列表：CNY：人民币

时间标准

时间标准北京时间，时区为东八区；如果商户的系统时间为非标准北京时间。参数值必须根据商户系统所在时 区先换算成标准北京时间， 例如商户所在地为0时区的伦敦，当地时间为 2014 年 11 月 11 日 0 时 0分0秒，换算成北京时间为 2014 年 11 月 11 日 8 时 0 分 0 秒。

时间戳

标准北京时间，时区为东八区，自 1970 年 1 月 1 日 0 点 0 分 0 秒以来的秒数。注意：部分系统取到的值为毫 秒级，需要转换成秒(10 位数字)。

商户订单号

商户支付的订单号由商户自定义生成，要求商户订单号保持唯一性（建议根据当前系统时间加随机序列来生成订单 号）。重新发起一笔支付要使用原订单号，避免重复支付；已支付过及已调用关单、撤销（请见后文的 API 列表）的订单号不能重新发起支付。

2.3. 安全规范

1、签名算法

对于报文的签名和验签处理机制如下：
Ⅰ、 设所有发送或接收到的数据为集合M，将集合M内非空参数值的参数按照参数名ASCII码从小到大排序
（字典序），使用URL键值对的格式（即key1=value1&key2=value2…）拼接成字符串stringA。
特别注意以下重要规则：
◆ 参数名ASCII码从小到大排序（字典序）；
◆ 如果参数的值为空不参与签名；
◆ 参数名区分大小写；
◆ 验证调用返回或主动通知签名时，传送的sign参数不参与签名，将生成的签名与该sign值作校验；
◆ 接口可能增加字段，验证签名时必须支持增加的扩展字段。
Ⅱ、 对待签名字符串stringA使用SHA1WithRSA算法进行签名，并进行Base64编码。

假设传送的参数如下：

    mch_id：  26101132
    out_trade_no： 2018072500000014 
    nonce_str :ibuaiVcKdpRxkhJA

对参数按照 key=value 的格式，并按照参数名 ASCII 字典序排序如下：

stringA="mch_id=26101132&nonce_str=ibuaiVcKdpRxkhJA&out_trade_no=2018072500000014";

SHA1WithRSA签名后：

signstr="n5ppfj9cIoKDars+El46xlpy2t/jnAsg4HMsGWfeQxj7OjKjhcCDp8yhtjuLAegGKCpDcOTkiM5DFDta9Ifvf3m+66mx4hHkd0V4ZLaSJQDtgchzCEuQ9T/ZuZHBhGyn1GPmY4Bc5uD6u3moOVytj7pwZGYvKFgm11R36XkurUAVDKbP7TtyyuvkUeyrgb3HonRVmOcokS2SZSJpB1iQF9JCUqpto4dtCHsERJNFfXMLINYoou9uJwmmaVA6Goc6hCavXHMQGiuw+iynin8hQSmqpPsbELjxz4mjReh6kBpfWwiHbx3hqmDq0M+CQHaJ6uhVLn3O5oA3aNiXSF9EWA=="

2、生成随机数算法

支付 API 接口协议中包含字段 nonce_str，主要保证签名不可预测。我们推荐生成随机数算法如下：调用 随机数函数生成，将得到的值转换为字符串。

3、以xml格式传参

<xml>
    <mch_id>26101132</mch_id>
    <out_trade_no>2018072500000014<out_trade_no>
    <nonce_str>ibuaiVcKdpRxkhJA</nonce_str>
    <sign>
        n5ppfj9cIoKDars+El46xlpy2t/jnAsg4HMsGWfeQxj7OjKjhcCDp8yhtjuLAegGKCpDcOTkiM5DFDta9Ifvf3m+66mx4hHkd0V4ZLaSJQDtgchzCEuQ9T/ZuZHBhGyn1GPmY4Bc5uD6u3moOVytj7pwZGYvKFgm11R36XkurUAVDKbP7TtyyuvkUeyrgb3HonRVmOcokS2SZSJpB1iQF9JCUqpto4dtCHsERJNFfXMLINYoou9uJwmmaVA6Goc6hCavXHMQGiuw+iynin8hQSmqpPsbELjxz4mjReh6kBpfWwiHbx3hqmDq0M+CQHaJ6uhVLn3O5oA3aNiXSF9EWA==
    </sign>
<xml>

采用标准XML协议，所有参数只存在一级节点中，不采用多级节点嵌套。

协议级错误返回：

<xml>
    <return_code>
        <![CDATA[FAIL]]>
    </return_code>
    <return_msg>
        <![CDATA[404 NotFound]]>
    </return_msg>
</xml>

正确返回数据：

<xml>
    <mch_id><![CDATA[26101132]]></mch_id>
    <result_code><![CDATA[SUCCESS]]></result_code>
    <return_code><![CDATA[SUCCESS]]></return_code>
    <sign><![CDATA[hl3D+es9rfBvTdRoc+Tyn8fWn9nScAIx8CDhL46RN/tcktmHhz8RZrq8dusWsiFYxKuzN8t13GuIVJTP9LzNLyGmNGDagnXtQhp6gWacQN1f8di16kZrn/JU89FCAsmGW3d62rEKTsxBMW+08iQ8iUpYZffpo/mqRdAkIHUmp44eBO8EQio1uADtIdQPW+guoxvZx8x1cl4AjDGEqc9qYw1+k83Kmi/HgmrNnvy7ASVAMuapu4/oZbRFpVAsOI6lbVTF2LEK7WWhUxMMd0hc3AfgyXjC/7sOD/dMlRc6X3IoO1N0rdwcn8o+CfSRwbpOijppYvhTUWiWKRm18PNG7Q==]]></sign>
    <trade_state><![CDATA[PROCESSING]]></trade_state>
    <trade_state_desc><![CDATA[处理中,请耐心等待划账]]></trade_state_desc>
    <transaction_id><![CDATA[2610113220180731150000368]]></transaction_id>
</xml>

业务级错误返回：

<xml>
    <err_code><![CDATA[OUT_TRADE_NO_USED]]></err_code>
    <err_code_des><![CDATA[商户订单号重复]]></err_code_des>
    <result_code><![CDATA[FAIL]]></result_code>
    <return_code><![CDATA[SUCCESS]]></return_code>
</xml>

3. API 列表

3.1. 单笔代付接口

3.1.2. 接口地址

测试： http://api.agent_test.szulodev.com/pay/agentpay/single
生产： 找商务获取

3.1.3. 输入参数

3.1.4. 返回结果

3.1.5. 错误码

注意：如果当前交易返回的支付状态是明确的错误原因造成的支付失败（支付确认失败），请重新下单支 付；如果当前交易返回的支付状态是不明错误（支付结果未知），请调用查询订单接口确认状态。

3.2. 代付查询接口

3.2.2. 接口地址

测试： http://api.agent_test.szulodev.com/pay/agentpay/query
生产： 找商务获取

3.2.3. 输入参数

3.2.4. 返回结果

3.2.5. 错误码

3.3. 还款信息查询接口

3.3.2. 接口地址

测试： http://api.agent_test.szulodev.com/pay/agentpay/repaymentquery
生产： 找商务获取

3.3.3. 输入参数

3.3.4. 返回结果

3.3.5. 错误码

3.4. 商户账单下载接口

3.4.2. 接口地址

测试： http://api.agent_test.szulodev.com/pay/downloadbill
生产： 找商务获取

3.4.3. 输入参数

3.4.4 返回结果

成功时，数据以文本表格的方式返回，第一行为表头，后面各行为对应的字段内容，字段内容跟查询订单或退款结果一致，具体字段说明可查阅相应接口。

第一行为表头：
付款时间,清算日期,商户号,订单号,商户单号,渠道单号,业务类型,代付状态,账户类型,收款户名,收款卡号,代付金额,付款说明,商户数据包

从第二行起，为数据记录，各参数以逗号分隔，参数前增加`符号，为标准键盘 1 左边键的字符，字段顺序表头不一致。

倒数第二行为订单统计标题，最后一行为统计数据总代付笔数,总代付金额
示例如下：

付款时间,清算日期,商户号,订单号,商户单号,渠道单号,业务类型,代付状态,账户类型,收款户名,收款卡号,代付金额,付款说明,商户数据包

付款时间,清算日期,商户号,订单号,商户单号,渠道单号,业务类型,代付状态,账户类型,收款户名,收款卡号,代付金额,付款说明,商户数据包
`2018-11-01 10:41:19,`2018-11-01,`26101053,`2610105320181101100017662,`2018110100002,`100005430072,`trade.agent.general,`SUCCESS,`对公,`银联代付收单暂记户01,`424900000000200031,`1.0,`测试,`,`
总代付笔数,总代付金额
`1,`1.0

3.4.5. 错误码

3.5. 支付结果通知

3.5.1. 应用场景

支付完成后，基金代付平台会把相关支付结果和用户信息发送给商户，商户需要接收处理，并返回应答。对后台通知交互时，如果基金代付平台收到商户的应答不是成功或超时，基金代付平台认为通知失败，基金代付平台会通过一定的策略定期重新发起通知，尽可能提高通知的成功率， 但 不保证通知最终能成功。（通知频率为0、1、2、4、5分钟）
注意：同样的通知可能会多次发送给商户系统。商户系统必须能够正确处理重复的通知。
推荐的做法是，当收到通知进行处理时，首先检查对应业务数据的状态，判断该通知是否已经处理过，如 果没有处理过再进行处理，如果处理过直接返回结果成功。在对业务数据进行状态检查和处理之前，要采用数 据锁进行幵发控制，以避免函数重入造成的数据混乱。
特别提醒：商户系统对于支付结果通知的内容一定要做签名验证，防止数据泄漏导致出现“假通知”，造成资 金损失。

3.5.2. 通知参数

3.5.3. 返回参数

商户处理后同步返回给服务平台，商户做业务处理后，需要以字符串的形式反馈处理结果，内容如下：

示例如下：

success

3.6. 查询余额接口

3.6.1. 应用场景

商户可以通过该接口主动查当前系统余额，判断是否有可转金额，完成下一步的业务逻辑。

3.6.2. 接口地址

测试： http://api.agent_test.szulodev.com/pay/agentpay/account
生产： 找商务获取

3.6.3. 输入参数

3.6.4. 返回结果

3.3.5. 错误码