List card transactions

get

https://api.cardda.com/v1/card_transactions

Returns a paginated list of card transactions — every authorization, capture, refund, fee, and adjustment that touched any of the company's vendor cards.

The endpoint excludes the internal StripeAuthorization rows (those are partial pre-auths that get superseded by a final CardTransaction). The result is scoped per-caller across every company the caller has permission in (via policy_scope); the company-id header is not consulted, and omitting it still returns 200 with the caller's full permitted scope. To restrict results to one company, filter explicitly with the company_id query parameter.

When you'll use this endpoint

Show the "transactions feed" in your dashboard.
Build per-user / per-card / per-merchant spend reports.
Audit pending vs. approved transactions ahead of month-end close.
Reconcile each row with its legacy Invoice (when set via invoice_id). Note: invoice_id points to the internal Invoice UUID — it is not a FiscalInvoice / SII DTE id. To match a transaction against a SII DTE you have to cross the merchant + amount + date against GET /v1/fiscal_invoices.

Response structure

Each row exposes:

Field	Description
`id`	Vendor-prefixed string (base64 encoded for some vendors).
`vendor_card_id`	The `VendorCard.id` that incurred the transaction.
`user_id`	Firebase user id of the cardholder.
`company_id`	UUID of the company.
`amount_cents` / `currency`	Transaction amount in the merchant's currency.
`target_amount_cents` / `target_currency`	Settled amount in the company's accounting currency.
`amount_in_clp`	Amount converted to CLP at settlement time (Chile-specific reporting).
`amount_in_limit_currency`	Amount converted to the card's `limit_currency`.
`exchange_rate`	FX rate applied at settlement.
`status`	Lifecycle (see enum).
`kind`	Transaction kind (`purchase`, `refund`, `fee`, `adjustment`, etc.).
`merchant` (`merchant_name`, `cleaned_merchant_name`, `merchant_image_url`, `merchant_id`)	Merchant info.
`description`	Free-form description from the vendor or the cardholder.
`comments`	Internal notes (e.g. "client meeting Q1 review").
`transaction_labels`	Tags applied by the company.
`invoice_id`	Legacy `Invoice` UUID (internal billing record kept for backwards compatibility). Not a `FiscalInvoice` / SII DTE id — fiscal invoices use the composite `<rut>-<document_type>-<number>` format and are exposed via `GET /v1/fiscal_invoices`.
`superseding_transaction_id`	When a pending transaction is replaced by the final one, the new id.
`superseding_reason`	Why it was superseded.
`completed_at` / `settled_at` / `created_at`	Lifecycle timestamps.
`target_amount_formatted`, `amount_formatted`	UI-ready strings.
`card`	Embedded vendor-card summary.

Common queries

# Most recent transactions of a single card, excluding superseded rows
GET /v1/card_transactions?\
  vendor_card_id=Q2FyZDoxMDIwNjQ5Mw==&\
  status={"$ne":"superseded"}&\
  _order=desc&_field=created_at&_start=0&_end=25

# Approved transactions in the last 30 days, by status
GET /v1/card_transactions?\
  status=approved&\
  created_at={"$gte":"2026-04-01T00:00:00Z"}&\
  _order=desc&_field=created_at

# Pending transactions of a specific user (declines and pre-auths)
GET /v1/card_transactions?\
  user_id=<firebase_uid>&\
  status=pending

# Search by merchant name (regex)
GET /v1/card_transactions?\
  merchant_name={"$regex":"AWS"}

# By kind — purchases/refunds only, excluding fees
GET /v1/card_transactions?\
  kind={"$in":["purchase","refund"]}

# USD-denominated transactions that haven't been linked to a legacy `Invoice` yet
GET /v1/card_transactions?\
  currency={"$ne":"CLP"}&\
  invoice_id=null

All operators in Filters are supported on the columns listed below.

Recent Requests

Time	Status	User Agent
Retrieving recent requests…

Loading…

Query Params

_start

integer

≥ 0

If all the cards where in an array, this would represent the index of the first item returned in the response

_end

integer

≥ 0

If all the cards where in an array, this would represent the index of the last item returned in the response

_order

string

enum

The order method, which can be ascending or descending

Allowed:

_field

string

The field used to sort, the example illustrates a response that would be sorted by the creation date

vendor_card_id

string

Filter by VendorCard.id. Cardda card ids are vendor-prefixed base64-encoded
strings (e.g. Q2FyZDoxMDIwNjQ5Mw==), not UUIDs. For batch lookups use
vendor_card_id={"$in":["...","..."]}. For more detail see
How to filter results.

string

Filter by transaction id. Use id={"$in":[...]} for batch lookups.

company_id

uuid

UUID of the company. Equivalent to the company-id header for ownership
scoping (the dashboard sends both during the migration window).

user_id

string

Firebase user id of the cardholder.

status

string

enum

Lifecycle status. The most common production query is
status={"$ne":"superseded"} to hide pre-auth rows that have been
replaced by their final captures.

kind

string

enum

What sort of monetary movement the row represents.

type

string

enum

STI subclass — the issuing vendor that produced the transaction. Useful
when you want to filter by issuing partner.

currency

string

ISO-4217 currency of the transaction at the merchant.

target_currency

string

ISO-4217 currency the transaction was settled in (typically the company's accounting currency).

amount_cents

string

Transaction amount in the merchant currency, in minor units. Accepts a
plain integer (amount_cents=100000) or a JSON-encoded operator object
({"$gte":100000}). Schema is type: string so both forms validate; see
Filters.

merchant_name

string

Merchant name as reported by the vendor. Combine with $regex for text
search. For grouped/normalized merchant names use cleaned_merchant_name.

cleaned_merchant_name

string

Cardda-normalized merchant name (e.g. "AMZN MKTP US" → "Amazon").

merchant_id

uuid

UUID of the linked Merchant row (after Cardda's merchant-resolution pass).

description

string

Free-form description provided by the cardholder or vendor.

invoice_id

UUID of a legacy Invoice row (an internal billing record kept for
backwards compatibility) — not a FiscalInvoice / SII DTE id.
This column is populated for only a small subset of card transactions
and is not the path to resolve the SII fiscal invoice for a charge:
SII fiscal-invoice ids use the composite <rut>-<document_type>-<number>
string format (see GET /v1/fiscal_invoices) and are exposed separately,
not via this field. Pass invoice_id=null to find transactions with no
linked legacy invoice.

created_at

string

Creation timestamp (UTC ISO-8601). Accepts a single date-time string or a
JSON-encoded operator object ({"$gte":"...","$lt":"..."}). Schema is
type: string (no format) so both forms validate.

completed_at

string

When the transaction was captured/cleared. Useful when reconciling against
a settled period. Accepts a single date-time string or a JSON-encoded
operator object — schema is type: string (no format).

settled_at

string

When the transaction reached final settlement. Strictly later than or
equal to completed_at. Accepts a single date-time string or a
JSON-encoded operator object — schema is type: string (no format).

$or

string

Logical OR across sub-conditions. Example: search either by description
or by merchant — $or=[{"description":{"$regex":"q"}},{"merchant_name":{"$regex":"q"}}].

Headers

company-id

uuid

required

UUID of the company that owns the card.

Responses

401

Unauthorized — missing or invalid bearer token, or the caller is not
permitted to list card transactions (Pundit authorization failure).
Returned with an empty body. Note: the company-id header is not
required for this endpoint.

200Paginated list of card transactions. Headers include X-Total-Count and Content-Range for offset pagination — see Pagination.