B2C在线支付说明文档汇潮支付有限公司资金托管接口说明文档版本：1.0目 录1文档说明31.1功能描述31.2阅读对象41.3业务术语42接口开发52.1接口介绍52.2接入准备62.3返回处理实现流程73数据交互83.1页面跳转交互83.2服务器通知交互84数据格式84.1POST85数字签名95.1签名原始串95.2签名算法95.2.1MD5签名96补单机制97接口107.1开通专属账户接口107.1.1数据交互107.1.2请求参数列表107.1.3页面返回和服务器返回117.2资金托管充值接口127.2.1数据交互127.2.2请求参数列表127.2.3页面返回和服务器返回137.3资金托管交易接口147.3.1数据交互147.3.2安全签名147.3.3请求参数列表157.3.4签名描述167.3.5返回167.4资金托管提现接口167.4.1数据交互167.4.2安全签名177.4.3请求参数列表177.4.4签名描述187.4.5回调说明187.4.6银行列表197.5查询请求参数217.5.1充值、提现和交易的查询217.5.2返回参数说明227.5.3查询用户账户余额247.5.4返回参数说明241注意事项251 文档说明1.1 功能描述本文描述了一麻袋提供给合作商户的资金托管解决方案，帮助商户轻松实现商户收益和商户资金池分离的功能。文档分别从交互模式、签名、接口、注意事项等方面详细介绍了一麻袋的接口连接方式和开发注意事项，可以帮助开发人员快速集成支付接口到网站中去。1.2 阅读对象合作商户系统的技术开发人员，要求具有WEB程序开发背景，了解http和https请求和应答的格式和过程，对XML格式有所掌握。1.3 业务术语术语解释防钓鱼 “网络钓鱼”攻击利用欺骗性的电子邮件和伪造的Web站点来进行诈骗活动，受骗者往往会泄露自己的财务数据，如信用卡号、账户用户名、口令和社保编号等内容，造成损失。防钓鱼用来防止以上情况的发生。 商户数字账号在一麻袋申请注册以后生成的一个7位数字账号，由注册时候得来请求 通过HTTP协议把需要传输的数据发送给接收方的过程。 返回 页面交互，商户订单请求支付完成后，一麻袋会将得到的处理结果参数，传递到商户提供的return_url地址上，同时从一麻袋支付成功页面跳转到商户提供的接收结果页面上。 页面交互不作为修改商户订单状态的依据通知 服务器交互，商户订单请求支付完成后，一麻袋的服务器会主动发起通知给商户的网站，传递到商户提供的advice_url地址上同时携带处理完成的结果信息反馈给商户网站。 密钥为保证通讯不被篡改，商户在一麻袋网站上获取的一组字符串，生成签名的时侯使用2 接口开发2.1 接口介绍接口名请求URL功能说明结果说明开通一麻袋专属账户接口http:/gateway.yemadai.com/openAccount调用该接口时传入约定参数，完成生成一麻袋专属账户的功能页面返回，返回地址为请求时传递的return_url参数；服务器返回，返回地址为请求时传递的advice_url参数，要求收到通知后进行响应。充值接口http:/gateway.yemadai.com/hostingRecharge在一麻袋充值页面选择银行后跳转到相应银行进行付款操作，操作成功后，钱会进入一麻袋相应的托管账户中，同时通知商户该笔订单完成页面返回，返回地址为请求时传递的return_url参数；服务器返回，返回地址为请求时传递的advice_url参数，要求收到通知后进行响应。注意：只返回成功结果，充值取消不返回结果交易接口http:/gateway.yemadai.com/hostingTrade调用该接口时传入约定参数，完成生成一麻袋托管账户交易转账的功能实时返回交易状态码提现接口http:/gateway.yemadai.com/hostingWithdrawcash调用该接口时传入约定参数，完成生成一麻袋专属账户的钱到用户银行卡的操作服务器返回，返回地址为请求时传递的adviceURL参数，要求收到通知后进行响应。提现接口只返回失败操作，成功不给予返回查询接口http:/gateway.yemadai.com/hostingTradeQuery调用该接口时传入约定参数，根据查询条件返回商户充值 提现记录状态返回标准的xml格式数据2.2 接入准备商户集成支付接口，需要先申请一个一麻袋的账户作为商户收款账户，然后将收款账户告诉相应的业务人员，一麻袋的工作人员会给该账户开通支付网关功能，设置交易手续费，结算周期等。商户注册成功以后会得到一个key，这是接口请求通知时需要参与数据签名的密钥请商户妥善管理。2.3 返回处理实现流程(1) 构造请求数据 商户根据一麻袋提供的接口规则，通过程序生成得到签名结果及要传输给一麻袋的数据集合。 (2) 发送请求数据 把构造完成的数据集合，通过页面链接跳转或表单提交的方式传递给一麻袋。 (3) 一麻袋对请求数据进行处理一麻袋得到这些集合后，会先进行安全校验等验证，一系列验证通过后便会处理这次发送过来的数据请求。 (4) 返回处理的结果数据 对于处理完成的交易，一麻袋会以下三种方式把数据反馈给商户网站。 页面通知，操作完成后会从一麻袋页面上通过自动跳转的方式跳回商户在请求时设定好的页面路径地址（参数return_url，如果商户没有设定，则不会进行该操作）； 一麻袋服务器主动发起通知，调用商户在请求时设定好的服务器通知路径（参数advice_url，如果商户没有设定，则不会进行该操作）；对于不需要进行异步返回的操作，一麻袋会在后台直接进行获取response写入的方式来进行返回相关数据，例如查询接口、和商户平台直接请求接口。(5) 获取的返回结果数据进行处理 商户在同步页面通知（参数return_url商户接收页面）或服务器异步通知（参数advice_url商户后台接收接口）获取一麻袋返回的结果数据后，可以结合自身网站的业务逻辑进行数据处理（如：订单更新、自动充值到会员账号中等）。 3 数据交互3.1 页面跳转交互页面跳转交互是指商户系统与一麻袋系统的数据交互通过用户浏览器中转进行，是一种非实时的异步交互。如用户充值，商户系统会生成一个支付链接，此链接通过用户的浏览器跳转到一麻袋系统，一麻袋通过此链接获取支付请求的参数，这个支付请求用的就是页面跳转交互模式。用户在一麻袋页面完成支付后，一麻袋通过return_url跳转到商户系统接收页面返回结果的页面，显示支付成功状态给用户。3.2 服务器通知交互服务器通知交互是指一麻袋系统主动向商户系统发送通知数据，并同步等待商户系统处理完毕后返回的响应数据。数据交互是一麻袋服务器与商户服务器直接通信，一般请求采用http的post，应答用字符串格式。如用户在一麻袋支付成功后，一麻袋会在后台通过支付请求advice_url参数向商户系统发起通知，商户处理后成功返回ok字符，如果为其他字符串表示商户接收失败，一麻袋会自动进行补单操作。4 数据格式4.1 POST采用HTTP标准的GET或POST协议，为了保证接收方接收数据正确，传递的参数如果存在特殊字符（如&、=等）需要进行URL Encode。GET或POST一般用于页面交互的请求和通知、服务器交互的请求。5 数字签名为了保证数据传输过程中的数据真实性和完整性，我们需要对数据进行数字签名，在接收签名数据之后进行签名校验。数字签名有两个步骤，先按一定规则拼接要签名的原始串，再使用MD5加密方式和密钥计算出签名结果。5.1 签名原始串无论是用get、post还是xml，签名原始串根据相关的约定来进行拼接，不进行URL Encode。5.2 签名算法目前暂只支持MD5签名5.2.1 MD5签名MD5 是一种摘要生成算法，通过在签名原始串后加上商户通信密钥的内容，进行MD5运算，形成的摘要字符串即为签名结果。为了方便比较，签名结果统一转换为大写字符。6 补单机制服务器交互，如果一麻袋收到商户的应答不是ok或超时，一麻袋会认为通知失败，一麻袋会通过一定的策略（如5分钟、10分钟、15分钟，共3次）定期重新发起通知，尽可能提高通知的成功率,但一麻袋不保证通知最终能成功。由于存在重新发送后台通知的情况，因此同样的通知可能会多次发送给商户系统。商户系统必须能够正确处理重复的通知。一麻袋推荐的做法是，当收到通知进行处理时，首先检查对应业务数据的状态，判断该通知是否已经处理过，如果没有处理过再进行处理，如果处理过直接返回ok。7 接口7.1 开通专属账户接口7.1.1 数据交互请求：页面跳转交互post方式返回结果：页面跳转+后台通知7.1.2 请求参数列表开户接口请求地址： http:/gateway.yemadai.com/openAccount表7-1 请求参数说明参数参数名称类型 参数说明是否为空样例number_id商户数字账号String商户一麻袋数字账号不可空1111111mode请求类型String类型为：个人，企业不可空personal/companyaccount_name账户名String个人为手机号，企业为邮箱不可空15012121212real_name用户名称String会根据该名称来创建麻袋账户不可空Kit，如果为汉字的话进行url编码传输card_no证件号码String证件号码不可空0101921587871245nick_name昵称String用户平台唯一昵称不可空1111111_kityadvice_url服务器通知地址String服务器异步通知地址，一麻袋会将结果发送到该地址可空www.yemadai.com/advicereturn_url页面通知地址String页面通知地址，一麻袋会将结果发送到该地址可空www.yemadai.com/returnremark备注String该备注会显示为用户托管账户名称可用一麻袋sign_info签名String签名信息：number_id=a&mode=personal&account_name=b&real_name=c&card_no=d&nick_name=e&advice_url=f&return_url=r&remark=r&merchantKey=j，MD5加密后，进行小写转换，为空的参数不要参与加密不可空646df5df5sd5注意：所有参数都必须是utf-8编码。 参数中real_name,nick_name,remark如果有汉字的话，使用含有汉字的原字符串进行加密，汉字参数传输需要urlcode编码此接口