会员对外文档平台

# 通用退单接口

# 简介

# 业务介绍

合作方通过该接口实现合作方订单退单功能。合作方可通过订单退订接口发起退单请求，由爱奇艺客服审核后，通过回调合作方创建的回调接口通知合作方，合作方在接到回调信息之后给用户退款，爱奇艺客服审核会查看合作方的退款原因，对极个别不合理的case可以驳回。但是不会修改退单的金额，被客服退回的退单，合作方与用户沟通后可（使用原退单号）重新发起退单，重新退单的退单号需与第一次退单的退单号相同

# 接口定义

# 应用场景

合作方退单调用本接口，通知爱奇艺为用户退权益并返回结算金额

# 接口域名

环境 域名
生产 openapi.vip.iqiyi.com
测试 test-openapi.vip.iqiyi.com

# URL

/partner/refund.action

# 请求方式

参数 说明
Method POST
Content-Type application/x-www-form-urlencoded

# 请求参数

变量名 名称 是否必须 类型 说明
partnerNo 合作方编码 是 String 合作方的唯一标识，由爱奇艺提供
sign 签名串 是 String MD5签名，签名方法见MD5加密描述
orderNo 原订单号 是 String 合作方的退单原订单号
refundNo 退单号 是 String 合作方的退单号（与下单接口订单号生成逻辑保持一致且在下单退单整体维度保证唯一）
reason 退单理由 是 String 退单原因

# 返回参数

字段名 类型 说明
code String 返回码，参考附录
msg String 返回码说明
sum Integer 退单金额（即爱奇艺侧可退金额）, 单位为分
partnerSum Integer 合作方传入的退单金额，单位为分

# 返回示例

{
    "code": "A00000",
    "msg": "成功",
    "data": {
        "sum": 10000 ,
        "partnerSum": 10000
     }
}

# 返回码定义

返回码Code 描述 备注
A00000 请求成功，需要审核返回退单审核中
Q00301 参数错误（如合作方编号为空，订单号非法等）
Q00307 签名错误
Q00332 系统错误
Q00409 原订单不存在或状态不是已完成
Q00415 调用退单交易接口失败_
Q00417 退单交易失败_系统在异步重试_请稍后重新下单 建议重试1到2次
Q00422 该退单号已被使用
Q00423 原单已被其他退单号退单
Q00425 退单号已存在且订单非退单状态
Q00426 原订单上没有可退的会员权益
Q00429 不支持合作方接口退单

需要重试的Code:Q00417，如返回此状态码，可进行同步重试1到2次

# 附录

# MD5加密描述

采用MD5计算签名，MD5密钥由爱奇艺提供，具体计算方法如下：
1、 假设共有三个参数 a=3、b=2、c=1；
2、 按参数名的字母正序排列，再用“&”连接后得到串A，即为“a=3&b=2&c=1”；
3、 将MD5密钥拼接到串A后面，假设MD5密钥为“qwer”，则拼接后为“a=3&b=2&c=1qwer”；
4、 计算拼接串的MD5即为最终签名值，注意使用UTF-8编码计算,MD5后的签名最后都转成小写。
举例：
参数：a=3、b=2、c=1；
MD5密钥：qwer
最终签名串：f80118ff523f25eda67cb799bdc9c52d

# JAVA版本示例代码如下：

public class Test{
/**
 * MD5签名测试类
 *
 */
    private static final char[] DIGITS = {'0', '1', '2', '3', '4', '5', '6',
        '7', '8', '9', 'a', 'b', 'c', 'd', 'e', 'f'};
    public static void main(String[] args) {
        TreeMap<String, Object> paramMap = new TreeMap<>();
        paramMap.put("a", "3");
        paramMap.put("b", "2");
        paramMap.put("c", "1");
        String md5key = "qwer";
        String targetParam = Joiner.on("&").withKeyValueSeparator("=")
        .useForNull("").join(paramMap);
        // MD5签名工具类,可以自己实现, MD5实现参照
        String targetSign = EncodeUtils.MD5(targetParam + md5key, "UTF-8");
        System.out.println("targetSign: " + targetSign);
    }
}

# 加密工具类

# MD5加密

import com.google.common.base.Joiner;
import org.apache.commons.lang.StringUtils;
import org.junit.Test;
import java.util.HashMap;
import java.util.Map;
import java.util.TreeMap;
import java.io.UnsupportedEncodingException;
import java.security.MessageDigest;
import java.security.NoSuchAlgorithmException;
public class EncodeUtils{

    public static String MD5(String text, String charset) {

        MessageDigest msgDigest = null;
        try {
            msgDigest = MessageDigest.getInstance("MD5");
        } catch (NoSuchAlgorithmException e) {
            throw new IllegalStateException("System doesn't support MD5 algorithm.");
        }
        try {
            msgDigest.update(text.getBytes(charset));    //注意改接口是按照指定编码形式签名
        } catch (UnsupportedEncodingException e) {
            throw new IllegalStateException("System doesn't support your  EncodingException.");
        }
        byte[] bytes = msgDigest.digest();
        String md5Str = new String(encodeHex(bytes));
        return md5Str;
    }

    public static char[] encodeHex(byte[] data) {

        int l = data.length;
        char[] out = new char[l << 1];
        // two characters form the hex value.
        for (int i = 0, j = 0; i < l; i++) {
            out[j++] = DIGITS[(0xF0 & data[i]) >>> 4];
            out[j++] = DIGITS[0x0F & data[i]];
        }
        return out;
    }
}

# 常见问题

# 退款说明

1、退款按照原有会员产品单位进行退单。

2、退权益逻辑：

天卡：按单位最小值向下取整（即整天）进行退权益。
月卡：当用户当月权益被使用超过25天时不退当月权益（即按月向下取整），当月权益使用小于（包括）25天时扣除当月权益时长（即按月向上取整）存在多退权益的可能（最多25天）。
季卡、年卡、N月卡：按照月卡的递推逻辑计算。
例A：用户1月1日0点购买月卡，如果1月10日申请退单，退一个月权益；如果1月26日申请退单，不退权益。
例B：用户1月1日0点购买年卡，如果2月10日申请退单（处于1月25日-2月25日），退11个月权益；如果2月26日申请退单（处于2月25日-3月25日），退10个月权益。

3、退款逻辑

天卡：订单金额 *（用户所剩余权益天数（向下取整）/ 订单总权益天数）。
月卡：订单金额 *（用户所剩余权益毫秒值 / 订单总权益毫秒值）。
季卡、年卡、N月卡：同月卡的退款计算逻辑。

# 特殊情况

注意：当用户有续费订单时，建议退后订购的退单，以免出现多退权益的问题。如果用户坚持要退先购买的订单，出现权益不对齐的问题，可以酌情多退金额或赠送天数补齐。

例如：用户1月1日买了年卡，1月5日买了年卡，1月10日要退掉1月1日买的年卡订单，根据退单规则会给用户退12个月权益，但是只会退355天的钱（用户用了10天）；如果退1月5日的订单，也不会有该问题。出现此问题时，可酌情送用户10天激活码，或者补退10天的钱。

# 在线测试

参数 值 备注
partnerNo toB_common_test

所需密钥：

参数 值
MD5密钥 b0ee3c7f62760330
点击此处进行接口调试
在线调试

← 退单查询 →