退款说明

需要退钱到 BALANCE 钱包时，请使用 POST /esim/refund。
仅需作废 eSIM、不涉及钱包退款时，可使用 POST /esim/profile/cancel（或 /revoke）。

接口明细见 订单退款、取消 Profile。

---

两种能力对比

	订单退款 /esim/refund	Profile 取消 /esim/profile/cancel
作用	计算可退金额并退回 BALANCE	取消 / 撤销 Profile
钱包	自动退款	不自动退钱
定位方式	orderNo / transactionId + 可选 items[]	profileId 或 iccid
典型场景	用户退款、对账	仅作废卡、已与用户线下结算

---

订单退款

路径： POST /open-api/v1/esim/refund

定位订单

orderNo 与 transactionId 至少填一项（来自下单或查单）。

退款规则

场景	怎么传
整单退	不传 items，退订单内全部可退子项
订单部分退	传 items，只包含要退的 itemNo（可多个子项）
子项整退	items[].itemNo + 不传 profiles
Profile 部分退	items[].itemNo + profiles[]，每项填 profileId 或 iccid（二选一）

itemNo 来自查单 / Webhook 的 items[].itemNo。
profileId / iccid 来自 items[].profiles[]。

退款请求不支持 esimTranNo，也不要在订单根级传 profiles[]。

请求示例

整单退：

{
  "orderNo": "MO2075463266738958338",
  "remark": "用户申请退款"
}

按子项退（该子项下全部可退 Profile）：

{
  "orderNo": "MO2075463266738958338",
  "items": [
    { "itemNo": "2075463266738958340" }
  ]
}

按 Profile 部分退（iccid）：

{
  "orderNo": "MO2075463266738958338",
  "items": [
    {
      "itemNo": "2075463266738958340",
      "profiles": [
        { "iccid": "8943108170003452385" }
      ]
    }
  ]
}

按 Profile 部分退（profileId）：

{
  "orderNo": "MO2075463266738958338",
  "items": [
    {
      "itemNo": "2075463266738958340",
      "profiles": [
        { "profileId": 2075464693179805698 }
      ]
    }
  ]
}

响应说明

字段	说明
status	REFUNDED = 已入账；REFUNDING = 处理中
refundAmount	本次或累计退款金额
items[].itemNo	子项编号
items[].refundStatus	PENDING / COMPLETED
items[].profileIds	本次退款的 Profile ID
items[].iccids	本次退款的 ICCID

status 为 REFUNDING 时，请查单或等待 REFUND_COMPLETED Webhook（见 Webhook 回调）。

响应示例

{
  "code": "000000",
  "message": "success",
  "data": {
    "orderNo": "MO2075463266738958338",
    "transactionId": "TX2025061800011",
    "status": "REFUNDED",
    "refundAmount": "2.62",
    "currency": "USD",
    "items": [
      {
        "itemNo": "2075463266738958340",
        "refundStatus": "COMPLETED",
        "profileIds": [2075464693179805698],
        "iccids": ["8943108170003452385"]
      }
    ]
  }
}

---

Profile 取消 / 撤销

路径： POST /open-api/v1/esim/profile/cancel 或 /revoke（语义相同）

用于作废 Profile，不会自动把金额退回 BALANCE。需要退钱请走上方 订单退款。

请求示例

profileId 与 iccid 二选一：

{ "profileId": 2075464693179805698 }

{ "iccid": "8943108170003452385" }

响应 asyncStatus

值	含义
COMPLETED	同步处理完成
PENDING	异步处理中，请稍后查单或等待 Webhook

---

怎么选

• 要退钱 → /esim/refund
• 只作废 eSIM、不退钱 → /esim/profile/cancel