收款列表

Quick Reference

What列出带筛选和分页的收款

Why构建对账仪表板、财务报表和争议调查工具

Reading Time8 分钟

Difficulty中级

Prerequisites身份验证 → 至少创建一笔收款

GET/api/v1/bank/wallet/charges/Bearer Token带筛选条件列出收款

为什么需要收款列表

没有收款列表	使用收款列表
对账靠人工——导出 CSV 并交叉核对	自动对账按计划通过 API 拉取交易
财务报表需要等待结算文件	实时收入仪表板按日期范围查询收款
争议调查从"找到那笔交易"开始	按卡品牌、BIN、日期或状态在数秒内搜索
无法了解每日交易量	以编程方式监控收款量、通过率和手续费
月末结账需要数天的人工工作	自动脚本拉取所有收款、计算总额、标记差异

对账管道

身份验证

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

查询参数

字段	类型	必填	说明
`wallet_uuid`	string (UUID)	是	将结果限定到此钱包
`merchant_uuid`	string (UUID)	否	按商户标识符筛选
`date_start`	string	否	日期范围起始（ISO 8601：`2026-03-01` 或 `2026-03-01T00:00:00Z`）
`date_end`	string	否	日期范围结束（ISO 8601）
`page`	integer	否	页码（从 1 开始）。默认：`1`
`limit`	integer	否	每页条数（1-100）。默认：`20`
`filter`	string	否	附加筛选条件（状态、类型、卡品牌）
`sort`	string	否	排序条件（如 `created:desc`）

筛选组合

用例	查询字符串
本月所有收款	`date_start=2026-03-01&date_end=2026-03-31`
仅已确认的收款	`filter=status:confirmed`
仅信用卡收款	`filter=type:credit`
Visa 交易	`filter=card_brand:Visa`
大额收款	`filter=amount_gte:1000`
昨日已结算的收款	`date_start=2026-03-19&date_end=2026-03-19&filter=status:confirmed`

复数形式端点路径

此端点使用 /charges/（复数），而非 /charge/。使用单数路径会调用查询收款。

代码示例

基本分页列表

cURL
Python
JavaScript

curl -s -X GET "https://core-manager.a55.tech/api/v1/bank/wallet/charges/?wallet_uuid=f47ac10b-58cc-4372-a567-0e02b2c3d479&page=1&limit=20" \
  -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://core-manager.a55.tech")

charges = requests.get(
    f"{base}/api/v1/bank/wallet/charges/",
    params={
        "wallet_uuid": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
        "page": 1,
        "limit": 20,
    },
    headers={"Authorization": f"Bearer {token}"},
).json()

for c in charges.get("data", []):
    print(f"{c['created']} | {c['transaction_id']} | {c['currency']} {c['amount']} | {c['status']}")

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

const params = new URLSearchParams({
  wallet_uuid: "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  page: "1",
  limit: "20",
});

const charges = await fetch(`${base}/api/v1/bank/wallet/charges/?${params}`, {
  headers: { Authorization: `Bearer ${token}` },
}).then((r) => r.json());

for (const c of charges.data || []) {
  console.log(`${c.created} | ${c.transaction_id} | ${c.currency} ${c.amount} | ${c.status}`);
}

完整对账——分页遍历所有收款

Python
JavaScript

import requests
import os

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

def fetch_all_charges(wallet_uuid, date_start, date_end):
    all_charges = []
    page = 1

    while True:
        resp = requests.get(
            f"{base}/api/v1/bank/wallet/charges/",
            params={
                "wallet_uuid": wallet_uuid,
                "date_start": date_start,
                "date_end": date_end,
                "page": page,
                "limit": 100,
            },
            headers={"Authorization": f"Bearer {token}"},
        ).json()

        data = resp.get("data", [])
        all_charges.extend(data)

        if len(data) < 100:
            break
        page += 1

    return all_charges

charges = fetch_all_charges(
    wallet_uuid="f47ac10b-58cc-4372-a567-0e02b2c3d479",
    date_start="2026-03-01",
    date_end="2026-03-20",
)

total_amount = sum(c["amount"] for c in charges)
total_fees = sum(c.get("fee", 0) for c in charges)
print(f"收款数：{len(charges)} | 总额：{total_amount} | 手续费：{total_fees}")

async function fetchAllCharges(walletUuid, dateStart, dateEnd) {
  const allCharges = [];
  let page = 1;

  while (true) {
    const params = new URLSearchParams({
      wallet_uuid: walletUuid,
      date_start: dateStart,
      date_end: dateEnd,
      page: String(page),
      limit: "100",
    });

    const resp = await fetch(`${base}/api/v1/bank/wallet/charges/?${params}`, {
      headers: { Authorization: `Bearer ${token}` },
    }).then((r) => r.json());

    const data = resp.data || [];
    allCharges.push(...data);

    if (data.length < 100) break;
    page++;
  }

  return allCharges;
}

const charges = await fetchAllCharges(
  "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "2026-03-01",
  "2026-03-20"
);

const totalAmount = charges.reduce((sum, c) => sum + c.amount, 0);
const totalFees = charges.reduce((sum, c) => sum + (c.fee || 0), 0);
console.log(`收款数：${charges.length} | 总额：${totalAmount} | 手续费：${totalFees}`);

响应字段

data 数组中的每个收款对象包含：

字段	类型	说明
`created`	string	ISO 8601 创建时间戳
`transaction_id`	string	A55 交易标识符
`charge_uuid`	string	收款唯一标识符
`merchant`	string	商户名称
`amount`	number	收款总金额
`currency`	string	ISO 4217 货币代码
`net_amount`	number	扣除手续费后的金额
`fee`	number	扣除的处理手续费
`status`	string	`issued`、`pending`、`confirmed`、`paid`、`error`、`canceled`、`refunded`
`card_brand`	string	卡品牌（`Visa`、`Mastercard`、`Amex`、`Elo`）——非卡片方式为 `null`
`card_bin`	string	卡号前 6 位——非卡片方式为 `null`
`type`	string	支付类型：`credit`、`debit`、`pix`、`boleto` 等
`settlement_date`	string	预计或实际结算日期
`message`	array	状态消息或错误详情

分页元数据

字段	类型	说明
`page`	integer	当前页码
`total`	integer	匹配查询的收款总数

完整响应示例

{
  "data": [
    {
      "created": "2026-03-20T14:32:11Z",
      "transaction_id": "TX1234567890",
      "charge_uuid": "7f8d4e2c-9c3f-4a7f-83b5-4e2f7f2b9d11",
      "merchant": "Loja Online ABC",
      "amount": 150.75,
      "currency": "BRL",
      "net_amount": 145.23,
      "fee": 5.52,
      "status": "confirmed",
      "card_brand": "Visa",
      "card_bin": "411111",
      "type": "credit",
      "settlement_date": "2026-03-23",
      "message": ["Success"]
    },
    {
      "created": "2026-03-20T15:10:45Z",
      "transaction_id": "TX1234567891",
      "charge_uuid": "a2c3d4e5-f6a7-8b9c-0d1e-2f3a4b5c6d7e",
      "merchant": "Loja Online ABC",
      "amount": 49.90,
      "currency": "BRL",
      "net_amount": 48.01,
      "fee": 1.89,
      "status": "confirmed",
      "card_brand": null,
      "card_bin": null,
      "type": "pix",
      "settlement_date": "2026-03-20",
      "message": ["Success"]
    },
    {
      "created": "2026-03-19T09:22:00Z",
      "transaction_id": "TX1234567892",
      "charge_uuid": "b3d4e5f6-a7b8-9c0d-1e2f-3a4b5c6d7e8f",
      "merchant": "Loja Online ABC",
      "amount": 899.00,
      "currency": "BRL",
      "net_amount": 865.84,
      "fee": 33.16,
      "status": "refunded",
      "card_brand": "Mastercard",
      "card_bin": "515590",
      "type": "credit",
      "settlement_date": "2026-03-22",
      "message": ["Refunded by merchant"]
    }
  ],
  "page": 1,
  "total": 142
}

错误响应

状态码	代码	说明	解决方式
400	`validation_error`	缺少 `wallet_uuid` 或参数格式无效	`wallet_uuid` 是必填的。检查日期格式是否为 ISO 8601
400	`errors.wallet.not_found`	钱包 UUID 不存在	验证 `wallet_uuid` 是否正确
401	`unauthorized`	无效或过期的 Bearer 令牌	通过 Cognito 刷新您的访问令牌
429	`rate_limit_exceeded`	请求过于频繁	等待并在 `Retry-After` 头值之后重试

优化大数据集的分页

设置 limit=100（最大值）以减少 API 调用次数。对于每日对账，使用 date_start 和 date_end 缩小日期范围，以保持结果集小而快速。

不要跳页

始终从第 1 页分页到最后一页。跳到任意页面可能会遗漏收款，因为请求之间可能创建了新交易。对于实时仪表板，按 created:desc 排序并处理前几页。

净额和手续费明细

net_amount 字段等于 amount - fee。使用 net_amount 与银行存款进行对账，使用 fee 用于会计。手续费因支付方式、币种和商户协议而异。

查询收款 →从列表中检索特定收款的完整详情。退款 →对列表中的任何收款发起退款。Webhook 概述 →获取实时通知，而非轮询列表。

Quick Reference

为什么需要收款列表​

对账管道​

身份验证​

查询参数​

筛选组合​

代码示例​

基本分页列表​

完整对账——分页遍历所有收款​

响应字段​

分页元数据​

完整响应示例​

错误响应​