Card transaction

List 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.

get/v1/card_transactions

Request

Base URL
https://api.cardda.com
URL
https://api.cardda.com/v1/card_transactions
Auth
HTTP bearer

Query parameters

vendor_card_idstring

Example:Q2FyZDoxMDIwNjQ5Mw==

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.

idstring

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

company_idstring uuid

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

user_idstring

Firebase user id of the cardholder.

Example:approved

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

Example:purchase

What sort of monetary movement the row represents.

Example:PomeloTransaction

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

currencystring

ISO-4217 currency of the transaction at the merchant.

target_currencystring

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

amount_centsstring

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_namestring

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

cleaned_merchant_namestring

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

merchant_idstring uuid

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

descriptionstring

Free-form description provided by the cardholder or vendor.

string uuid

'null'

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_atstring

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_atstring

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_atstring

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).

$orstring

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

Parameters

#/paths/~1v1~1merchants/get/parameters/0 (unresolved $ref)

#/paths/~1v1~1merchants/get/parameters/2 (unresolved $ref)

#/paths/~1v1~1merchants/get/parameters/3 (unresolved $ref)

#/paths/~1v1~1merchants/get/parameters/4 (unresolved $ref)

#/paths/~1v1~1merchants/get/parameters/5 (unresolved $ref)

Response

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

idstring

Vendor-prefixed transaction id (often base64-encoded; not a UUID).

user_idstring

Firebase user id of the cardholder.

vendor_card_idstring

Id of the VendorCard that incurred the transaction (vendor-prefixed string, not a UUID).

descriptionstring

merchant_namestring

cleaned_merchant_namestring nullable

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

merchant_image_urlstring nullable

merchant_idstring uuid nullable

Lifecycle status of the transaction.

What sort of monetary movement the row represents.

typestring

STI subclass — the issuing vendor that produced the transaction.

amount_centsinteger

Transaction amount in the merchant currency, in minor units (e.g. cents). Spends are negative (purchase, fee, fx_fee, allocation); refunds/reversals/allocation_release are positive.

amount_in_clpinteger

Amount of the transaction in CLP at settlement time. Follows the same sign convention as amount_cents (spends negative, refunds positive).

amount_in_limit_currencyinteger nullable

Amount converted to the card's limit_currency.

currencystring

Merchant currency in upper-case ISO-4217 (e.g. USD, CLP).

exchange_ratestring

migratedboolean nullable

invoice_idstring uuid nullable

UUID of a legacy Invoice row (internal billing record kept for backwards compatibility). Not a FiscalInvoice / SII DTE id — fiscal invoice ids use the composite <rut>-<document_type>-<number> string format and are exposed via GET /v1/fiscal_invoices, not via this field.

status_reasonstring nullable

Reason of the current transaction status

commission_idstring uuid nullable

UUID of the linked commission row, when the transaction accrued a Cardda commission (computed field).

target_amount_centsinteger

Settled amount in the company's accounting currency, in minor units. Follows the same sign convention as amount_cents (spends negative, refunds positive).

target_currencystring

Currency the company sees the transaction in (the user's preferred accounting currency), in upper-case ISO-4217.

amount_formattedstring nullable

UI-ready formatted amount including currency.

target_amount_formattedstring nullable

UI-ready formatted settled amount including currency.

commentsstring nullable

Free-form internal notes attached by the company.

superseding_transaction_idstring nullable

When a pending transaction is replaced by the final one, the new id.

superseding_reasonstring nullable

Why the transaction was superseded.

completed_atstring date-time nullable

When the transaction was captured/cleared.

settled_atstring date-time nullable

When the transaction reached final settlement.

company_idstring uuid

created_atstring date-time

updated_atstring date-time

Example response

[
  {
    "id": "VHJhbnNhY3Rpb246MTIzNDU2",
    "user_id": "U2MGkNZT6zNPKtB85OpJi9SjFvG2",
    "vendor_card_id": "Q2FyZDoxMDIwNjQ5Mw==",
    "description": "Cargo de GOOGLE ADS",
    "merchant_name": "GOOGLE ADS",
    "cleaned_merchant_name": "Google",
    "type": "PomeloTransaction",
    "amount_cents": -45000,
    "amount_in_clp": -366287,
    "currency": "USD",
    "exchange_rate": "813.9702",
    "migrated": true,
    "status_reason": "card_limit",
    "target_amount_cents": -366287,
    "target_currency": "CLP",
    "amount_formatted": "USD 99.00",
    "target_amount_formatted": "CLP 9.270.000",
    "card": {
      "id": "Q2FyZDoxMDIwNjQ5Mw==",
      "user_id": "U2MGkNZT6zNPKtB85OpJi9SjFvG2",
      "type": "PomeloCard",
      "name": "AWS",
      "spending_control_strategy": "allocation_based",
      "last4": "4163",
      "status_preference": "inactive",
      "migrated": true,
      "limit_amount": {
        "amount": "3000.0",
        "formatted": "$3.000 CLP",
        "cents": "3000.0",
        "currency_iso": "CLP"
      },
      "limit_interval": "daily",
      "limit_amount_preference": {
        "amount": "3000.0",
        "formatted": "$3.000 CLP",
        "cents": "3000.0",
        "currency_iso": "CLP"
      },
      "allocated_amount": {
        "amount": "3000.0",
        "formatted": "$3.000 CLP",
        "cents": "3000.0",
        "currency_iso": "CLP"
      },
      "allocated_amount_preference": {
        "amount": "3000.0",
        "formatted": "$3.000 CLP",
        "cents": "3000.0",
        "currency_iso": "CLP"
      },
      "recurring_allocation_amount_cents": 50000,
      "remaining_balance": "2000.0",
      "spent": 472025,
      "company_expendable_balance_in_limit_currency": "3200000.0",
      "spent_in_interval_with_limit_currency": 472025,
      "vendor_max_allocation": {
        "amount": "3000.0",
        "formatted": "$3.000 CLP",
        "cents": "3000.0",
        "currency_iso": "CLP"
      },
      "preference_restricted_spendable": "2000.0",
      "spent_in_interval": 472025,
      "spent_in_vendor_interval": 472025
    },
    "merchant": {
      "id": "87128e7e-d774-4e2d-b4b5-5d20c7ebe682",
      "name": "Amazon",
      "image_url": "https://logos.cardda.com/amazon.png"
    }
  }
]

Changes

No recorded changes to this operation across all 1 revision of this API.