取消收款

POST/api/v1/bank/wallet/charge/{charge_uuid}/cancel/{wallet_uuid}/Bearer Token

---

请求头

请求头	值	必填
Authorization	Bearer {A55_ACCESS_TOKEN}	是
Content-Type	application/json	是
Idempotency-Key（幂等键）	UUID v4	建议

路径参数

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

请求体

字段	类型	必填	说明
reason	string	否	取消原因，用于对账

---

响应字段

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

---

HTTP 状态码

状态码	说明
200	收款取消成功
400	收款不在可取消状态
401	Bearer Token（持有者令牌）无效或已过期
403	该钱包权限不足
404	收款或钱包未找到
409	收款已取消或已结算
422	验证错误
429	超出速率限制
500	服务器内部错误 - 请使用指数退避重试

---

代码示例

cURL

curl -s -X POST "https://core-manager.a55.tech/api/v1/bank/wallet/charge/a1b2c3d4-e5f6-7890-abcd-ef1234567890/cancel/f47ac10b-58cc-4372-a567-0e02b2c3d479/" \
  -H "Authorization: Bearer $A55_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000" \
  -d '{"reason": "客户在发货前要求取消"}'

Python

import requests
import os

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

charge_uuid = "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
wallet_uuid = "f47ac10b-58cc-4372-a567-0e02b2c3d479"

try:
    response = requests.post(
        f"{base}/api/v1/bank/wallet/charge/{charge_uuid}/cancel/{wallet_uuid}/",
        json={"reason": "客户在发货前要求取消"},
        headers={
            "Authorization": f"Bearer {token}",
            "Content-Type": "application/json",
            "Idempotency-Key": "550e8400-e29b-41d4-a716-446655440000",
        },
    )
    response.raise_for_status()
    result = response.json()
    print(f"已取消：{result['charge_uuid']}——状态：{result['status']}")
except requests.exceptions.HTTPError as e:
    print(f"HTTP {e.response.status_code}: {e.response.json()}")
except requests.exceptions.RequestException as e:
    print(f"请求失败：{e}")

Node.js

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

const chargeUuid = "a1b2c3d4-e5f6-7890-abcd-ef1234567890";
const walletUuid = "f47ac10b-58cc-4372-a567-0e02b2c3d479";

try {
  const response = await fetch(
    `${base}/api/v1/bank/wallet/charge/${chargeUuid}/cancel/${walletUuid}/`,
    {
      method: "POST",
      headers: {
        Authorization: `Bearer ${token}`,
        "Content-Type": "application/json",
        "Idempotency-Key": "550e8400-e29b-41d4-a716-446655440000",
      },
      body: JSON.stringify({
        reason: "客户在发货前要求取消",
      }),
    }
  );

  if (!response.ok) throw new Error(`请求失败（HTTP ${response.status}）：${await response.text()}`);
  const result = await response.json();
  console.log(`已取消：${result.charge_uuid}——状态：${result.status}`);
} catch (error) {
  console.error("取消失败：", error.message);
}

---

错误响应示例

{
  "charge_uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "error",
  "message": [
    {
      "code": "CANCEL_NOT_ALLOWED",
      "source": "charge",
      "description": "Charge has already been settled and cannot be cancelled. Use refund instead."
    }
  ]
}

（API 原始错误信息，原文为英文）

---

退款 →对已捕获的收款进行退款。查询收款 →通过轮询收款来验证取消状态。Webhook 概述 →在取消处理完成后接收 Webhook（网络钩子）通知。