退款

Quick Reference

What对已捕获的收款进行退款

Why将资金退还给付款人——防止拒付、处理退货并维护客户信任

Reading Time5 分钟

Difficulty中级

Prerequisites身份验证 → 已扣款的收款（状态：confirmed 或 paid）

POST/api/v1/bank/wallet/charge/{charge_uuid}/refund/{wallet_uuid}/Bearer Token退款收款

为什么退款很重要

没有退款	使用退款
不满意的客户发起拒付（每笔争议费 $25+）	在争议发起前主动退还资金
拒付率超过 1%——卡组织标记您的账户	退款率不计入拒付阈值
不良体验后客户信任降低	快速退款将负面体验转变为"他们解决了问题"
账务显示虚高的收入	退款金额自动调整收入报表
"我的钱在哪里？"的工单堆积	退款状态可通过查询收款和 Webhook（网络钩子）追踪

---

退款流程

---

身份验证

需要 Bearer 令牌。参见身份验证。

路径参数

两个 UUID 都在 URL 路径中，而不是请求体或查询字符串中：

字段	类型	必填	说明
charge_uuid	string (UUID)	是	要退款的收款
wallet_uuid	string (UUID)	是	拥有该收款的钱包

可选请求体字段

字段	类型	必填	说明
amount	number	否	部分退款金额。省略表示全额退款
reason	string	否	用于对账和报表的退款原因

路径参数，非请求体

与大多数 A55 端点不同，退款端点将 charge_uuid 和 wallet_uuid 放在 URL 路径中： POST /api/v1/bank/wallet/charge/{charge_uuid}/refund/{wallet_uuid}/

---

代码示例

全额退款

cURL

curl -s -X POST "https://core-manager.a55.tech/api/v1/bank/wallet/charge/51dcca6e-7310-4b73-a94c-90835408f2ff/refund/f47ac10b-58cc-4372-a567-0e02b2c3d479/" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json"

Python

import requests
import os

token = os.environ["A55_API_TOKEN"]
base = os.environ.get("A55_API_BASE_URL", "https://core-manager.a55.tech")

charge_uuid = "51dcca6e-7310-4b73-a94c-90835408f2ff"
wallet_uuid = "f47ac10b-58cc-4372-a567-0e02b2c3d479"

refund = requests.post(
    f"{base}/api/v1/bank/wallet/charge/{charge_uuid}/refund/{wallet_uuid}/",
    headers={"Authorization": f"Bearer {token}", "Content-Type": "application/json"},
).json()

print(f"退款：{refund['charge_uuid']}——状态：{refund['status']}")

JavaScript

const token = process.env.A55_API_TOKEN;
const base = process.env.A55_API_BASE_URL || "https://core-manager.a55.tech";

const chargeUuid = "51dcca6e-7310-4b73-a94c-90835408f2ff";
const walletUuid = "f47ac10b-58cc-4372-a567-0e02b2c3d479";

const refund = await fetch(
  `${base}/api/v1/bank/wallet/charge/${chargeUuid}/refund/${walletUuid}/`,
  {
    method: "POST",
    headers: {
      Authorization: `Bearer ${token}`,
      "Content-Type": "application/json",
    },
  }
).then((r) => r.json());

console.log(`退款：${refund.charge_uuid}——状态：${refund.status}`);

部分退款

cURL

curl -s -X POST "https://core-manager.a55.tech/api/v1/bank/wallet/charge/51dcca6e-7310-4b73-a94c-90835408f2ff/refund/f47ac10b-58cc-4372-a567-0e02b2c3d479/" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 50.25,
    "reason": "客户退回了 3 件商品中的 1 件"
  }'

Python

partial_refund = requests.post(
    f"{base}/api/v1/bank/wallet/charge/{charge_uuid}/refund/{wallet_uuid}/",
    json={
        "amount": 50.25,
        "reason": "客户退回了 3 件商品中的 1 件",
    },
    headers={"Authorization": f"Bearer {token}", "Content-Type": "application/json"},
).json()

print(f"部分退款：{partial_refund['status']}")

JavaScript

const partialRefund = await fetch(
  `${base}/api/v1/bank/wallet/charge/${chargeUuid}/refund/${walletUuid}/`,
  {
    method: "POST",
    headers: {
      Authorization: `Bearer ${token}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      amount: 50.25,
      reason: "客户退回了 3 件商品中的 1 件",
    }),
  }
).then((r) => r.json());

console.log(`部分退款：${partialRefund.status}`);

---

响应字段

字段	类型	说明
charge_uuid	string	已退款的收款标识符
wallet_uuid	string	拥有该收款的钱包
status	string	成功时为 refunded
message	object	附加详情，成功时为空对象

---

完整响应示例

全额退款

{
  "charge_uuid": "51dcca6e-7310-4b73-a94c-90835408f2ff",
  "wallet_uuid": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "status": "refunded",
  "message": {}
}

部分退款

{
  "charge_uuid": "51dcca6e-7310-4b73-a94c-90835408f2ff",
  "wallet_uuid": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "status": "refunded",
  "message": {}
}

---

错误响应

状态码	代码	说明	解决方式
400	errors.wallet.not_found	钱包 UUID 不存在	验证 URL 路径中的 wallet_uuid
400	REFUND_NOT_ALLOWED	收款不在可退款状态	只有 confirmed 或 paid 的收款可以退款。通过查询收款检查收款状态
401	unauthorized	无效或过期的 Bearer 令牌	通过 Cognito 刷新您的访问令牌
404	CHARGE_NOT_FOUND	未找到收款	验证 URL 路径中的 charge_uuid
422	amount_exceeds_captured	部分退款金额超过已捕获金额	退款金额必须 ≤ 已捕获金额

分期退款为全额退还

如果支付以分期方式进行，全额退款将退还所有分期的全部金额。您无法退还单笔分期。对于分期支付的部分退货，请使用指定 amount 的部分退款。

退款与拒付——成本比较

处理退款除了退还的支付金额外不产生额外费用。拒付则需要支付金额加上争议费用（根据卡组织 $25-$100 不等）。当收到合理投诉时，始终主动退款。

退款时效

退款需要 5-10 个工作日才会显示在付款人的账单上，具体取决于发卡行。请告知您的客户此时间线，以减少"我的退款在哪里？"的工单。

查询收款 →通过轮询收款验证退款状态。收款列表 →在交易列表中查找需要退款的收款。Webhook 概述 →在退款处理完成时接收 Webhook。