List charges

Quick Reference

WhatList charges with filters and pagination

WhyBuild reconciliation dashboards, financial reports, and dispute investigation tools

Reading Time8 min

DifficultyIntermediate

PrerequisitesAuthentication → At least one created charge

GET/api/v1/bank/wallet/charges/Bearer TokenList charges with filters

Why list charges

Without List Charges	With List Charges
Reconciliation is manual — export CSVs and cross-reference	Automated reconciliation pulls transactions via API on schedule
Financial reports require waiting for settlement files	Real-time revenue dashboards query charges by date range
Dispute investigation starts with "find the transaction"	Search by card brand, BIN, date, or status in seconds
No visibility into daily transaction volume	Monitor charge volume, approval rates, and fees programmatically
Month-end close takes days of manual work	Automated scripts pull all charges, compute totals, flag discrepancies

Reconciliation pipeline

Authentication

Requires Bearer token. See Authentication.

Query parameters

Field	Type	Required	Description
`wallet_uuid`	string (UUID)	Yes	Scope results to this wallet
`merchant_uuid`	string (UUID)	No	Filter by merchant identifier
`date_start`	string	No	Start of date range (ISO 8601: `2026-03-01` or `2026-03-01T00:00:00Z`)
`date_end`	string	No	End of date range (ISO 8601)
`page`	integer	No	Page number (1-indexed). Default: `1`
`limit`	integer	No	Items per page (1–100). Default: `20`
`filter`	string	No	Additional filters (status, type, card_brand)
`sort`	string	No	Sort criteria (e.g., `created:desc`)

Filter combinations

Use case	Query string
All charges this month	`date_start=2026-03-01&date_end=2026-03-31`
Only confirmed charges	`filter=status:confirmed`
Credit card charges only	`filter=type:credit`
Visa transactions	`filter=card_brand:Visa`
High-value charges	`filter=amount_gte:1000`
Yesterday's settled charges	`date_start=2026-03-19&date_end=2026-03-19&filter=status:confirmed`

Plural endpoint path

This endpoint uses /charges/ (plural), not /charge/. Using the singular path calls Get Charge instead.

Code examples

Basic list with pagination

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}`);
}

Full reconciliation — paginate through all charges

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"Charges: {len(charges)} | Total: {total_amount} | Fees: {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: ${charges.length} | Total: ${totalAmount} | Fees: ${totalFees}`);

Response fields

Each charge object in the data array contains:

Field	Type	Description
`created`	string	ISO 8601 creation timestamp
`transaction_id`	string	A55 transaction identifier
`charge_uuid`	string	Unique charge identifier
`merchant`	string	Merchant name
`amount`	number	Total charge amount
`currency`	string	ISO 4217 currency code
`net_amount`	number	Amount after fees
`fee`	number	Processing fee deducted
`status`	string	`issued`, `pending`, `confirmed`, `paid`, `error`, `canceled`, `refunded`
`card_brand`	string	Card brand (`Visa`, `Mastercard`, `Amex`, `Elo`) — `null` for non-card methods
`card_bin`	string	First 6 digits of the card — `null` for non-card methods
`type`	string	Payment type: `credit`, `debit`, `pix`, `boleto`, etc.
`settlement_date`	string	Expected or actual settlement date
`message`	array	Status messages or error details

Pagination metadata

Field	Type	Description
`page`	integer	Current page number
`total`	integer	Total number of charges matching the query

Complete response example

{
  "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
}

Error responses

Status	Code	Description	Resolution
400	`validation_error`	Missing `wallet_uuid` or invalid parameter format	`wallet_uuid` is required. Check date format is ISO 8601
400	`errors.wallet.not_found`	Wallet UUID does not exist	Verify `wallet_uuid` is correct
401	`unauthorized`	Invalid or expired Bearer token	Refresh your access token via Cognito
429	`rate_limit_exceeded`	Too many requests	Wait and retry after `Retry-After` header value

Optimize pagination for large datasets

Set limit=100 (maximum) to reduce the number of API calls. For daily reconciliation, narrow the date range with date_start and date_end to keep result sets small and fast.

Don't skip pages

Always paginate from page 1 to the last page. Jumping to arbitrary pages may miss charges if new transactions are created between requests. For real-time dashboards, sort by created:desc and process the first few pages.

Net amount and fee breakdown

The net_amount field is amount - fee. Use net_amount for reconciliation against bank deposits, and fee for accounting. Fees vary by payment method, currency, and merchant agreement.

Get charge →Retrieve full details for a specific charge from the list.Refund charge →Issue a refund for any charge in the list.Webhooks →Get real-time notifications instead of polling the list.

Quick Reference

Why list charges​

Reconciliation pipeline​

Authentication​

Query parameters​

Filter combinations​

Code examples​

Basic list with pagination​

Full reconciliation — paginate through all charges​

Response fields​

Pagination metadata​

Complete response example​

Error responses​