扣款确认收款

Quick Reference

What对先前已授权的收款进行扣款确认

Why先冻结资金，稍后按实扣款——酒店、租车和电商平台的必备功能

Reading Time5 分钟

Difficulty中级

Prerequisites身份验证 → 创建收款（capture: false）

POST/api/v1/bank/wallet/charge/capture/Bearer Token对已授权收款完成扣款确认

为什么要分离授权与扣款确认

没有授权+扣款确认	使用授权+扣款确认
酒店扣费 $500，即使客人只消费了 $320	酒店在入住时授权 $500，在退房时扣款确认 $320
租车公司无法冻结押金	租车公司授权 $2,000 押金，仅对实际费用扣款确认
电商平台在卖家确认库存前就向买家扣费	电商平台冻结资金，直到卖家发货
多扣费导致退款、争议和客户流失	部分扣款确认仅扣除应付金额——无需退款
餐厅无法在授权后添加小费	餐厅授权账单金额，稍后对账单+小费扣款确认

授权与扣款确认流程

身份验证

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

请求体

字段	类型	必填	说明
`charge_uuid`	string (UUID)	是	待扣款确认的已授权收款
`wallet_uuid`	string (UUID)	是	拥有该收款的钱包
`amount`	number	否	扣款确认金额。省略表示全额扣款确认。传入较低值表示部分扣款确认

部分扣款确认

当 amount 小于原始授权金额时，A55 仅对指定金额扣款确认并释放剩余冻结。并非所有收单机构都支持部分扣款确认——请查看服务商能力了解详情。

代码示例

全额扣款确认

cURL
Python
JavaScript

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

import requests
import os

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

capture = requests.post(
    f"{base}/api/v1/bank/wallet/charge/capture/",
    json={
        "charge_uuid": "51dcca6e-7310-4b73-a94c-90835408f2ff",
        "wallet_uuid": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    },
    headers={"Authorization": f"Bearer {token}", "Content-Type": "application/json"},
).json()

print(f"已捕获：{capture['charge_uuid']}——状态：{capture['status']}")
print(f"金额：{capture['currency']} {capture['local_currency']}")

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

const capture = await fetch(`${base}/api/v1/bank/wallet/charge/capture/`, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${token}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    charge_uuid: "51dcca6e-7310-4b73-a94c-90835408f2ff",
    wallet_uuid: "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  }),
}).then((r) => r.json());

console.log(`已捕获：${capture.charge_uuid}——状态：${capture.status}`);

部分扣款确认（酒店退房示例）

cURL
Python
JavaScript

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

partial = requests.post(
    f"{base}/api/v1/bank/wallet/charge/capture/",
    json={
        "charge_uuid": "51dcca6e-7310-4b73-a94c-90835408f2ff",
        "wallet_uuid": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
        "amount": 320.00,
    },
    headers={"Authorization": f"Bearer {token}", "Content-Type": "application/json"},
).json()

print(f"部分捕获：{partial['currency']} {partial['local_currency']}（原冻结金额的部分）")

const partial = await fetch(`${base}/api/v1/bank/wallet/charge/capture/`, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${token}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    charge_uuid: "51dcca6e-7310-4b73-a94c-90835408f2ff",
    wallet_uuid: "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    amount: 320.0,
  }),
}).then((r) => r.json());

console.log(`部分捕获：${partial.currency} ${partial.local_currency}`);

响应字段

响应结构与创建收款相同，状态更新为 confirmed：

字段	类型	说明
`charge_uuid`	string	收款唯一标识符
`status`	string	扣款确认成功后为 `confirmed`
`local_currency`	number	结算币种的扣款确认金额
`currency`	string	ISO 4217 货币代码
`usd_currency`	number	美元扣款确认金额
`eur_currency`	number	欧元扣款确认金额
`type`	string	支付方式（`credit_card`、`debit_card`）
`date`	string	原始收款创建日期
`description`	string	收款描述
`due_date`	string	付款到期日
`message`	array/null	成功时为 `null`，失败时为错误详情
`installment_count`	integer	分期数
`installments`	array	更新金额后的每期分期明细

完整响应示例

{
  "status": "confirmed",
  "charge_uuid": "51dcca6e-7310-4b73-a94c-90835408f2ff",
  "local_currency": 320.00,
  "currency": "BRL",
  "usd_currency": 57.41,
  "eur_currency": 50.33,
  "type": "credit_card",
  "date": "2026-03-15",
  "description": "酒店预订——豪华套房",
  "due_date": "2026-03-20",
  "message": null,
  "installment_count": 1,
  "installments": [
    {
      "local_currency": 320.00,
      "currency": "BRL",
      "usd_currency": 57.41,
      "eur_currency": 50.33,
      "due_date": "2026-03-20",
      "status": "confirmed",
      "installment_number": 1
    }
  ]
}

错误响应

状态码	代码	说明	解决方式
400	`errors.wallet.charge_capture_not_available`	收款不在可扣款确认状态	验证收款状态为 `authorized`。已扣款确认、已过期或已失败的收款无法再次扣款确认
401	`unauthorized`	无效或过期的 Bearer 令牌	通过 Cognito 刷新您的访问令牌
404	`errors.wallet.not_found`	钱包 UUID 不存在	验证 `wallet_uuid` 是否正确
404	`CHARGE_NOT_FOUND`	在此钱包中未找到收款	验证两个 UUID 是否与原始收款匹配
422	`amount_exceeds_authorization`	扣款确认金额超过授权金额	扣款确认金额必须 ≤ 原始授权金额

在 7 天内完成扣款确认

授权冻结在大多数卡组织中 7 天后过期。请在冻结过期前完成扣款确认，否则授权将自动作废，您需要创建新的收款。

此端点使用 POST，而非 PUT

尽管这是一个更新操作，OpenAPI 规范将扣款确认定义为 POST /charge/capture/。请在您的集成中使用 POST。

设置仅授权收款

要使用扣款确认流程，您必须先在创建收款请求中设置 capture: false。如果 capture 为 true（默认值），收款将在一步中完成授权与扣款确认——无需单独调用本端点。

创建收款 →使用 capture: false 创建仅授权收款。退款 →对已扣款确认的收款进行退款——全额或部分。查询收款 →调用后核对收款状态。

Quick Reference

为什么要分离授权与扣款确认​

授权与扣款确认流程​

身份验证​

请求体​

代码示例​

全额扣款确认​

部分扣款确认（酒店退房示例）​

响应字段​

完整响应示例​

错误响应​