API Doc

# 1.1 退款接口

# 简要描述
  • 退款接口
  • 支持合并包裹支付场景下的单运单退款（传 subOrderId）与批量运单退款（传 subOrderRefundList）
# 请求URL
  • /api/v2/payment/refund
# 请求方式
  • POST
# 请求参数
参数名 必选 类型 长度 说明
appId 是 string - 应用APPID
mchRefundOrderId 是 string 1-32 商户-退款编号, 商户系统唯一标识，格式：字母+数字，1-32位,如：CCP20220428011068111
originalTransactionId 是 string 1-32 原交易流水号
subOrderId 条件必填 string 1-32 运单号。单运单退款时传入，与 subOrderRefundList 二选一，不可同时传
subOrderRefundList 条件必填 string - 子运单退款明细，JSON字符串（格式见 subOrderRefundList 参数）。批量运单退款时传入，与 subOrderId 二选一，不可同时传
refundAmount 是 int - 本次退款总金额(以分为单位，最小100分，例如PHP:500.10, 需要设置为50010)。多运单退款时，必须等于 subOrderRefundList 内所有子运单退款金额之和
refundReason 否 string 1-200 退款原因，本次请求内所有子运单共用，不支持子运单级退款原因
refundCallbackUrl 是 string - 退款回调Url
sign 是 string - 签名
# subOrderRefundList 参数
  • subOrderRefundList 为 JSON 字符串，如："[{\"subOrderId\":\"JT123456789\",\"refundAmount\":10000},{\"subOrderId\":\"JT987654321\",\"refundAmount\":20000}]"
参数名 必选 类型 长度 说明
subOrderId 是 string 1-32 运单号，格式：字母+数字，1-32位
refundAmount 是 int - 当前子运单本次退款金额(以分为单位，最小100分)。子运单仅支持全额退款：必须等于该子运单原交易金额
# 请求示例 - 单运单退款
{
    "appId": "xxx",
    "mchRefundOrderId": "RF202606220001",
    "originalTransactionId": "P202606220001",
    "subOrderId": "JT123456789",
    "refundAmount": 10000,
    "refundReason": "客户拒收",
    "refundCallbackUrl": "https://merchant.example.com/refund/callback",
    "sign": "xxx"
}
# 请求示例 - 批量运单退款
{
    "appId": "xxx",
    "mchRefundOrderId": "RF202606220002",
    "originalTransactionId": "P202606220001",
    "refundAmount": 30000,
    "refundReason": "批量退款",
    "subOrderRefundList": "[{\"subOrderId\":\"JT123456789\",\"refundAmount\":10000},{\"subOrderId\":\"JT987654321\",\"refundAmount\":20000}]",
    "refundCallbackUrl": "https://merchant.example.com/refund/callback",
    "sign": "xxx"
}
# 返回示例
{
    "code": 1000,
    "message": "success",
    "data": {
        "mchRefundOrderId": "RF202606220002",
        "refundTransactionId": "R202606220001",
        "refundAmount": 30000,
        "refundStatus": "PENDING",
        "refundCreateTime": "2026-06-22 15:30:00",
        "refundReturnTime": "",
        "subOrderRefundList": [
            {
                "subOrderId": "JT123456789",
                "refundAmount": 10000
            },
            {
                "subOrderId": "JT987654321",
                "refundAmount": 20000
            }
        ]
    }
}
  • refundReturnTime：退款结果返回时间，退款处理中时为空
  • subOrderRefundList：单运单和批量模式均返回，仅包含 subOrderId 和 refundAmount，不返回子运单级 refundStatus 和 refundReason
# 返回失败案例 响应code列表 (opens new window)
{
    "code":1002,
    "message":"merchant white ip forbidden",
}

← 1.2 退款查询接口 →