退款

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 (float)	否	剩余可退款金额	部分退款金额。省略时退还剩余可退款的全部金额。必须 ≤ `amount_remaining`

路径参数，非请求体

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

代码示例

全额退款

cURL
Python
JavaScript

curl -s -X POST "https://sandbox.api.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"

import requests
import os

token = os.environ["A55_API_TOKEN"]
base = os.environ.get("A55_API_BASE_URL", "https://sandbox.api.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']}")

const token = process.env.A55_API_TOKEN;
const base = process.env.A55_API_BASE_URL || "https://sandbox.api.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
Python
JavaScript

curl -s -X POST "https://sandbox.api.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
  }'

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

print(
    f"部分退款：{partial_refund['status']} "
    f"（已退款 {partial_refund['amount_refunded']}，"
    f"剩余 {partial_refund['amount_remaining']}）"
)

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 }),
  }
).then((r) => r.json());

console.log(
  `部分退款：${partialRefund.status} ` +
    `（已退款 ${partialRefund.amount_refunded}，` +
    `剩余 ${partialRefund.amount_remaining}）`
);

响应字段

字段	类型	说明
`charge_uuid`	string	已退款的收款标识符
`wallet_uuid`	string	拥有该收款的钱包
`status`	string	全额退款时为 `refunded`，仍有剩余余额时为 `partially_refunded`
`amount_refunded`	number (float)	此收款上所有退款操作累计已退款的总金额
`amount_remaining`	number (float)	剩余可退款金额。当其变为 `0` 时，收款已全额退款
`message`	object	退款尝试期间收集的服务商/收单机构消息
`refunds`	array	此收款上的退款操作历史

`refunds[]` 字段项

字段	类型	说明
`refund_uuid`	string	退款操作的 UUID
`amount`	number (float)	此次具体退款的金额
`status`	string	退款状态：`refunded` 或 `refund_error`
`reason`	string	退款原因
`created`	datetime	退款创建时间（ISO 8601）

完整响应示例

全额退款

{
  "charge_uuid": "51dcca6e-7310-4b73-a94c-90835408f2ff",
  "wallet_uuid": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "status": "refunded",
  "amount_refunded": 100.00,
  "amount_remaining": 0.00,
  "message": {},
  "refunds": [
    {
      "refund_uuid": "9b1f0c88-3a3c-4f2f-9d6e-1f0a2d4e88c1",
      "amount": 100.00,
      "status": "refunded",
      "reason": "customer_request",
      "created": "2026-04-27T18:00:00Z"
    }
  ]
}

部分退款

{
  "charge_uuid": "51dcca6e-7310-4b73-a94c-90835408f2ff",
  "wallet_uuid": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "status": "partially_refunded",
  "amount_refunded": 50.25,
  "amount_remaining": 49.75,
  "message": {},
  "refunds": [
    {
      "refund_uuid": "5c2a13f0-5e74-4b21-9c6a-2bd9d9b0aa10",
      "amount": 50.25,
      "status": "refunded",
      "reason": "customer_request",
      "created": "2026-04-27T18:00:00Z"
    }
  ]
}

错误响应

状态码	代码	说明	解决方式
400	`errors.wallet.not_found`	钱包 UUID 不存在	验证 URL 路径中的 `wallet_uuid`
400	`errors.wallet.charge_refund_not_available`	收款不在可退款状态	只有 `confirmed` 或 `paid` 的收款可以退款。通过查询收款检查收款状态
401	`unauthorized`	无效或过期的 Bearer 令牌	通过 Cognito 刷新您的访问令牌
422	`errors.wallet.charge_refund_amount_exceeded`	请求的 `amount` 大于 `amount_remaining`	响应体包含当前的 `amount_remaining`——使用 ≤ 该值的金额重试

分期退款为全额退还

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

退款与拒付——成本比较

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

退款时效

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

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

Quick Reference

为什么退款很重要​

退款流程​

身份验证​

路径参数​

可选请求体字段​

代码示例​

全额退款​

部分退款​

响应字段​

refunds[] 字段项​

完整响应示例​

全额退款​

部分退款​

错误响应​

为什么退款很重要

退款流程

身份验证

路径参数

可选请求体字段

代码示例

全额退款

部分退款

响应字段

`refunds[]` 字段项

完整响应示例

全额退款

部分退款

错误响应