一麻袋资金托管API V1.0.doc

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功能说明结果说明开通一麻袋专属账户接口/openAccount调用该接口时传入约定参数，完成生成一麻袋专属账户的功能页面返回，返回地址为请求时传递的return_url参数；服务器返回，返回地址为请求时传递的advice_url参数，要求收到通知后进行响应。充值接口/hostingRecharge在一麻袋充值页面选择银行后跳转到相应银行进行付款操作，操作成功后，钱会进入一麻袋相应的托管账户中，同时通知商户该笔订单完成页面返回，返回地址为请求时传递的return_url参数；服务器返回，返回地址为请求时传递的advice_url参数，要求收到通知后进行响应。注意：只返回成功结果，充值取消不返回结果交易接口/hostingTrade调用该接口时传入约定参数，完成生成一麻袋托管账户交易转账的功能实时返回交易状态码提现接口/hostingWithdrawcash调用该接口时传入约定参数，完成生成一麻袋专属账户的钱到用户银行卡的操作服务器返回，返回地址为请求时传递的adviceURL参数，要求收到通知后进行响应。提现接口只返回失败操作，成功不给予返回查询接口/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 请求参数列表开户接口请求地址： /openAccount表7-1 请求参数说明参数参数名称类型 参数说明是否为空样例number_id商户数字账号String商户一麻袋数字账号不可空1111111mode请求类型String类型为：个人，企业不可空personal/companyaccount_name账户名String个人为手机号，企业为邮箱不可eal_name用户名称String会根据该名称来创建麻袋账户不可空Kit，如果为汉字的话进行url编码传输card_no证件号码String证件号码不可空0101921587871245nick_name昵称String用户平台唯一昵称不可空1111111_kityadvice_url服务器通知地址String服务器异步通知地址，一麻袋会将结果发送到该地址可空/advicereturn_url页面通知地址String页面通知地址，一麻袋会将结果发送到该地址可空/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编码此接口支持重复调用，前提是请求信息在多次调用中保持一致，且尚未开户成功。其中merchantKey是商户注册一麻袋后获取的（请妥善保管），连接起来进行MD5加密后字符串，并进行小写转换。7.1.3 页面返回和服务器返回页面返回和服务器返回，返回的参数是一致的，页面返回通过请求中的return_rul，服务器返回通过请求中的advice_url来信息，采用post方式返回数据返回参数包含如下内容：表7-2 返回参数说明参数参数名称类型参数说明是否为空样例number_id数字账号String商户一麻袋数字账号不可空1111111mode类型Number开通麻袋专属账户：bind不可空bindnick_name昵称String平台用户唯一昵称不可空1111111_kitystatus状态String状态，00为成功，其他为失败不可空00sign_info签名Stringmd5校验串：number_id=1111111&mode=bind&nick_name=1111111_kity&status=00&merchantKey=213545df44sfd54，MD5加密后，进行小写转换不可空213545df44sfd54参数中nick_name如果有汉字的话，使用含有汉字的原字符串进行加密，汉字参数传输需要urlcode解码7.2 资金托管充值接口7.2.1 数据交互请求：页面跳转交互post方式返回结果：页面跳转+后台通知7.2.2 请求参数列表充值请求地址： /hostingRecharge参数参数名称类型 参数说明是否为空样例number_id商户数字账号String商户一麻袋数字账号不可空1111111out_trade_no商户订单号String要求在商户平台上为唯一不可空12121212amount充值金额String该笔充值订单的金额不可空100fee手续费String商户收取的充值的手续费可空3nick_name昵称String用户平台唯一昵称不可空1111111_kityadvice_url服务器通知地址String服务器异步通知地址，一麻袋会将结果发送到该地址可空/advicereturn_url页面通知地址String页面通知地址，一麻袋会将结果发送到该地址可空/returnremark备注String备注信息可空Testsign_info签名String签名信息：number_id=a& out_trade_no=b&amount=c&fee=d&nick_name=e&advice_url=f&return_url=r&remark=r&merchantKey=j，MD5加密后，进行小写转换，为空的参数不要参与加密不可空646df5df5sd5参数中nick_name,remark如果有汉字的话，使用含有汉字的原字符串进行加密，汉字参数传输需要urlcode编码7.2.3 页面返回和服务器返回页面返回和服务器返回，返回的参数是一致的，页面返回通过请求中的return_rul，服务器返回通过请求中的advice_url来信息，采用post方式返回数据返回参数包含如下内容：表7-2 返回参数说明参数参数名称类型参数说明是否为空样例number_id数字账号String商户一麻袋数字账号不可空1111111mode类型String充值：recharge不可空rechargeout_trade_no商户订单号String要求在商户平台上为唯一不可mount充值金额String该笔充值订单的金额不可空100fee手续费String商户收取的充值的手续费可空3nick_name昵称String平台用户唯一昵称不可空1111111_kitystatus状态String状态，00为成功，其他为失败不可空00sign_info签名Stringmd5校验串：number_id=1111111&mode=recharge&out_trade_no =o&amount=1&fee=1&nick_name=1111111_kity&status=00&merchantKey=213545df44sfd54，MD5加密后，进行小写转换,参数为空不参与加密不可空213545df44sfd54参数中nick_name如果有汉字的话，使用含有汉字的原字符串进行加密，汉字参数传输需要urlcode解码7.3 资金托管交易接口7.3.1 数据交互请求：商户使用post方式提交主参数transData信息到一麻袋服务器参数transData是一个明文为xml格式的base64转码后的字符串。返回结果：实时返回交易结果状态码7.3.2 安全签名在发起一个请求的同时，商户必须提交一个“secureCode”的参数到一麻袋服务器，它是集合所有参数以及一麻袋系统产生的一个安全密码key进行加密后的字符串。安全密码key是只有一麻袋系统以及商户本身保存，来保证交易的完整性以及商户授权交易。详细请查看请求参数信息。7.3.3 请求参数列表 一麻袋生产请求地址：/ hostingTrade转账明细参数列表参数说明是否为空限制transData主体参数，包含xml的主体内容NAdd下表是交易针对tranData的xml参数描述转账明细参数列表参数说明是否为空限制accountNumber一麻袋系统的数字帐户，7位数字帐户NAssigned unique.tradeNo商户交易号N最大20位-字母数字-多笔交易可以共用一个tradeType交易类型NTrade为正常交易outTradeNo商户流水号NMax 20-每笔订单应为唯一outName付款人昵称NMax 50inName收款人昵称NMax 50amount金额N数字，保留2位小数remark备注N交易信息secureCode签名信息N详见3.6请求参数信息样例：7.3.4 签名描述参数secureCode的值为accountNumber+outTradeNo+outName+inName+amount+remark+privatekey字符串连接以后进行MD5签名，结果为32位小写字母类型。7.3.5 返回代码返回0000成功，其他为失败返回码信息1001Base64解析异常1002Xml字符串格式有问题1003签名错误1005缺少对应必要的参数1006该商户无操作权限1007未找到托管账户1009余额不足0000转账成功7.4 资金托管提现接口7.4.1 数据交互请求：商户使用post方式提交主参数transData信息到一麻袋服务器参数transData是一个明文为xml格式的base64转码后的字符串。返回结果：实时返回交易结果状态码7.4.2 安全签名在发起一个请求的同时，商户必须提交一个“secureCode”的参数到一麻袋服务器，它是集合所有参数以及一麻袋系统产生的一个安全密码key进行加密后的字符串。安全密码key是只有一麻袋系统以及商户本身保存，来保证交易的完整性以及商户授权交易。详细请查看请求参数信息。7.4.3 请求参数列表一麻袋生产请求地址：/ hostingWithdrawCash转账明细参数列表参数说明是否为空限制transData主体参数，包含xml的主体内容NAdd下表是交易针对transData的xml参数描述转账明细参数列表参数说明是否为空限制accountNumber一麻袋系统的数字帐户，7位数字帐户NAssigned unique.outTradeNo商户的交易流水ID，对应每笔转账信息N最大20位-字母数字-不可以重复adviceURL退回通知，转账失败，退回通知地址NMax 50 , http协议bankName转账信息，银行名称N参考银行列表 3.9provice开户省份NMax 20city开户市NMax 20branchName支行名称NMax 50nickName昵称NMax 50cardNo卡号NMax 25amount金额N数字，保留2位小数fee商户收取的手续费可空数字，保留2位小数remark备注NsecureCode签名信息N详见3.6请求参数信息样例：7.4.4 签名描述参数secureCode的值为accountNumber+outTradeNo+ bankName+ provice + city + branchName + nickName+ cardNo+ amount+fee+remark+ key字符串连接以后进行MD5签名，结果为32位小写字母类型。7.4.5 回调说明请求成功获取到resCode为“0000”就代表请求成功，只需等待一麻袋进行最后转账操作。当一麻袋提交到银行以后，银行因开户信息错误导致转账退回，一麻袋会将退回的转账信息通过adviceURL地址回调通知给用户告知此笔转账已经退回到一麻袋，请检查后重新提交转账信息到一麻袋再次转账。回调参数列表参数说明是否为空限制number_id数字账号NAssigned unique.mode类型Nwithdrawalout_trade_no商户订单号NAssigned unique.amount提现金额N数字，保留2位小数fee手续费可空商户收取的提现的手续费nick_name昵称N平台用户唯一昵称status提现状态N状态，00为成功，88为失败，66为处理中sign_info签名NMD5加密后，进行小写转换sign_info校验串：number_id=1111111&mode=withdrawal&out_trade_no =o&amount=1&fee=1&nick_name=1111111_kity&status=88&merchantKey=213545df44sfd54，参数为空 不参与加密参数中nick_name如果有汉字的话，使用含有汉字的原字符串进行加密，汉字参数传输需要urlcode解码7.4.6 返回代码返回0000成功，其他为失败返回码信息1001Base64解析异常1002Xml字符串格式有问题1003签名错误1005缺少对应必要的参数1006该商户无操作权限1007未找到托管账户1008提现金额小于11009余额不足7.4.7 银行列表下表是银行名称列表，请按照下列银行名称填写开户银行列参数：* 按照银行列表填写开户行参数，可以减少因开户行不准确而导致转账失败的情况。银行列表序号银行名称1中国银行2工商银行3农业银行4交通银行5广东发展银行6深圳发展银行7建设银行8上海浦东发展银行9浙江泰隆商业银行10招商银行12中国民生银行13兴业银行14广东发展银行15上海浦东发展银行16深圳发展银行17中信银行18华夏银行19中国光大银行20北京银行21上海银行22天津银行23大连银行24杭州银行25宁波银行26厦门银行27广州银行28平安银行29浙商银行30上海农村商业银行31重庆银行11中国邮政储蓄银行32江苏银行33北京农村商业银行34济宁银行35台州银行7.5 查询请求参数7.5.1 充值、提现和交易的查询参数参数名称类型 参数说明是否为空样例number_id商户数字账号String商户一麻袋数字账号不可空1111111mode交易类型String交易类型：充值recharge，提现withdrawal，交易trade可空recharge/tradeout_trade_no商户流水号String商户唯一流水号可空H54854878231trade_no商户批次号String商户唯一订单号可空854878231begin_time开始时间String商户交易开始时间可空2014-03-13 10:19:23end_time结束时间String商户交易结束时间可空2014-03-13 10:19:23page_index页码String(5)可空，如果为空则默认为1可空1sign_info签名String签名顺序: number_id=a &mode=m&out_trade_no=b&begin_time=1&end_time=t&page_index=p&merchantKey=c，为空的参数不参与加密不可空0101921587871245参数为空不参与加密一麻袋生产请求地址：/ hostingTradeQuery7.5.2 返回参数说明转账明细参数列表参数说明是否为空限制accountNumber一麻袋系统的数字帐户，7位数字帐户NAssigned unique.resultCode返回状态N00为成功resultCount返回数据条数NpageSize每页有多少 数据N100pageIndex页码NoutTradeNo商户订单号NMax 30mode交易类型Nrecharge/withdrawaltradeStatus交易状态N00为成功nickName昵称NMax 25amount金额N数字remark备注NsecureCode签名信息N详见3.6返回的xml如下充值和提现查询返回相同的xml格式如下图1，交易查询返回的xml格式