即时到账批量退款接口开发流程
一、开发前期准备
1.1、查找PID(partner)和密钥（key）
a、首先查询合作者身份ID和安全校验码KEY；
b、RSA加密方式：公私钥由商户技术人员生成。
（1）首先生成商户公钥、私钥
（2）其次上传生成的公钥，同时获取支付宝公钥。
1.2、网络环境的要求
a、支付宝提供的开发环境。
生产环境。用商户自己的账户做测试。
沙箱环境。提供资料沙箱环境网关地址、测试账号、密钥。
b、商户端开发环境：公网可访问的网络环境。
1.3、下载接口开发文档及配置开发环境
开发语言：支持C#、PHP、ASP、JAVA四种开发语言。
1.4、业务术语
| 术语 | 解释 |
|---|---|
| 返回 | 支付宝根据得到的数据处理完成后，支付宝将处理完成的结果信息反馈给商户网站。 |
| 敏感词 | 带有敏感政治倾向、暴力倾向、不健康色彩或不文明的词。 |
| 请求 | 通过HTTP协议把需要传输的数据发送给接收方的过程。 |
| 特殊字符 | 用做url转义字符，或在接口参数中用作分割符的特殊字符，包括：？、%、&、+、^、|。 |
| 充退 | 即充值退回，卖家通过退款将资金从卖家支付宝账号退至交易买家支付宝账号后，支付宝将退款资金继续退至买家付款的银行卡的过程。 |
| 充退转账 | 由于银行原因或者交易买家的原银行卡被注销，充退失败，支付宝允许买家上传一张新的有效银行卡或者支付宝账号，支付宝将退款资金退到买家提供的银行卡（建议买家提供新的银行卡）或支付宝账户的过程。 |
二、开发联调阶段
2.1、安全说明
| 类型 | 细则 | 原因 |
|---|---|---|
| 安全 | 使用签约账号进行调试，必须保护PID与安全校验码key的隐私性。 | 防止接口无法正常使用或防止签约的账号信息被盗用，导致资金受损、被他人恶意利用等。 |
| 测试完毕后，要把测试账号立刻更换成签约账号。 | 使用测试账号时，手续费按照3%扣除。 | |
| 该接口必须使用https请求 | 避免请求参数暴露 | |
| 支付宝的通知服务器的出口IP段是121.0.26.0/23、110.75.128.0/19、110.75.225.0/24、110.75.242.0/24。该IP段地址不是商户访问支付宝的地址。 | 如果商户网站设置了IP白名单（即IP过滤），需要把支付宝的通知IP地址加入白名单中。这里面提供的是ip段，需要商户自己算出ip。 | |
| 商户必须以DNS解析的方式访问支付宝接口，不要设置DNS cache，不要绑定支付宝IP。如果为了商户自身安全必须绑定支付宝IP时，必须向支付宝的技术支持人员备案。 | 支付宝IP地址一旦变更，会导致商户无法请求或访问支付宝，致使商户业务直接不可用。 |
2.2、参数说明
| 类型 | 细则 | 原因及样例说明 |
|---|---|---|
| 参数配置 | 必须设置请求参数service（接口名称）refund_fastpay_by_platform_nopwd 无密退款refund_fastpay_by_platform_nopwd有密退款 | 避免接口使用错误 |
| 必须设置请求参数_input_charset（编码格式），即该参数不能为空，并让该参数加入签名运算。 | 避免接口无法正常使用 | |
|
batch_no退款批次号，在商户系统内唯一； 规格：退款日期（8位当天日期）+流水号（3~24位，不能接受“000”，但可以接受英文字母） |
避免订单重复。 | |
| batch_num 退款总笔数。最大支持1000笔 | 避免数据库更新不了。 | |
|
Detail_data单笔订单退款格式。格式说明见开发文裆4.3说明 单笔数据集格式为：第一笔交易#第二笔交易#第三笔交易...#第N笔交易。其中每一笔交易按退交易、退分润、退子交易的组合来划分，有以下4种格式： a、交易退款数据集|分润退款数据集1|分润退款数据集2|...|分润退款数据集N b、交易退款数据集|分润退款数据集1|分润退款数据集2|...|分润退款数据集N$$退子交易 c、交易退款数据集 d、交易退款数据集$$退子交易 交易退款数据集格式为：原付款支付宝交易号^退款总金额^退款理由。 分润退款数据集格式为：转出人支付宝账号[原收到分润金额的账户]^转出人支付宝账号对应用户ID[2088开头16位纯数字]^转入人支付宝账号[原付出分润金额的账户]^转入人支付宝账号对应用户ID^退款金额^退款理由。 子交易退款数据集格式为：金额^退款理由。 |
避免接口无法正常使用 一笔订单最多可以退款99次 |
|
| 在请求参数列表中，不可空的参数必须配置。 | 避免接口无法正常使用 | |
| 发送给支付宝的请求，支持http协议，get和post两种请求方式 | 避免请求支付宝时报错，错误码为ILLEGAL_SIGN； |
2.3、签名说明
| 类型 | 细则 | 原因 |
|---|---|---|
| 签名 | 请求的所有参数，需要根据参数名=参数值的格式，按首字符字典顺序（ascii值大小）排序，若遇到相同首字符，则判断第二个字符，以此类推，待签名字符串需要以“参数名1=参数值1&参数名2=参数值2&….&参数名N=参数值N”的规则进行拼接。 | 避免接口无法正常使用 |
| 在对请求的参数做签名时，这些参数必须来源于请求参数列表，并且除去列表中的参数sign、sign_type。 | 避免接口无法正常使用 | |
| 在对请求的参数做签名时，对于请求参数列表中那些可空的参数，如果选择使用它们，那么这些参数的参数值必须不能为空或空值。 | 避免接口无法正常使用 | |
| 签名时将字符转化成字节流时指定的字符集与_input_charset保持一致；如果传递了_input_charset参数，这个参数也应该包含在待签名数据中。 | 避免接口无法正常使用 | |
| 待签名数据应该是参数原始值而不是url encoding之后的值，例如：调用某接口需要对请求参数email进行数字签名，那么待签名数据应该是email=test@msn.com，而不是email=test%40msn.com。 | 避免接口无法正常使用 |
2.4、通知说明
| 类型 | 细则 | 原因 |
|---|---|---|
| 返回数据处理 | 本接口直接返回的XML信息is_success（T、F、P）仅代表提交成功、失败、处理中，不代表退款成功或者失败，商户必须根据退款异步通知中的结果集来判断是否退款成功。 | 避免由于商户余额不足等问题导致接口提交退款失败使用户投诉 |
|
退款处理后通过result_details（处理结果详情）： 格式为：第一笔交易#第二笔交易#第三笔交易...#第N笔交易。 第N笔交易格式为： 交易退款数据集$收费退款数据集|分润退款数据集|分润退款数据集|...|分润退款数据集$$退子交易 交易退款数据集格式为：原付款支付宝交易号^退款总金额^退款状态。 收费退款数据集格式：被收费人支付宝账号[交易时支付宝收取服务费的账户]^被收费人支付宝账号对应用户ID[2088开头16位纯数字]^退款金额^退费理由。 分润退款数据集格式为：转出人支付宝账号[原收到分润金额的账户]^转出人支付宝账号对应用户ID[2088开头16位纯数字]^转入人支付宝账号[原付出分润金额的账户]^转入人支付宝账号对应用户ID^退款金额^退款状态。 子交易退款数据集格式为：金额^子交易共补款金额（总补款金额减去总退款金额）^退款状态。 |
避免重复退款 |
2.5、验签说明
| 类型 | 细则 | 原因 |
|---|---|---|
| 验签 | 在对通知的参数做签名时，这些参数必须来源于支付宝通知回来的参数，并且除去列表中的参数sign、sign_type，根据参数名=参数值的格式，按首字符字典顺序（ascii值大小）排序，若遇到相同首字符，则判断第二个字符，以此类推，待签名字符串需要以“参数名1=参数值1&参数名2=参数值2&….&参数名N=参数值N”的规则进行拼接，得到的签名结果与获取到的参数sign值做比较。 | 验证返回的签名 |
三、开发完毕，测试验收
3.1、测试流程
| 步骤 | 调试内容 | 备注 |
|---|---|---|
| 第一步：在本机单独对这个接口进行调试。 |
检查参数配置，发送请求 返回批量退款处理结果数据 |
仅仅把接口配置好，不要放在商户的网站项目中 |
| 第二步：在服务器上单独对这个接口进行调试 |
检查参数配置，发送请求 返回批量退款处理结果数据 |
本机调试没有问题后，再放入服务器中调试。 |
| 第三步：接口融合到网站项目中 |
检查参数配置，发送请求 返回批量退款处理结果数据 对获取的返回结果数据进行处理 |
把调试好的接口与商户网站项目的业务流程进行衔接和融合。 |
| 第四步：在本机对融合后的网站项目进行调试 |
检查参数配置，发送请求 返回批量退款处理结果数据 对获取的返回结果数据进行处理 业务后续的执行 |
在本机调试衔接到网站项目后的接口。 |
| 第五步：在服务器对融合后的网站项目进行调试 |
整个业务操作流程检查 参数配置，发送请求 返回批量退款处理结果数据 对获取的返回结果数据进行处理 业务后续的执行 |
本机调试没有问题后，再放入服务器中调试。 |