API Reference

List bank transactions

get
https://api.cardda.com/v1/banking/bank_transactions

Returns a paginated list of bank transactions for authorized accounts. This endpoint provides comprehensive filtering, sorting, and pagination capabilities to help you query transaction history effectively.

Key Features

  • Pagination: Control result size with _start and _end parameters (default: 25 items)
  • Sorting: Sort by any field in ascending or descending order
  • Filtering: Apply complex filters on multiple fields including amounts, dates, and statuses
  • Relationships: Automatically includes related entities (recipients, senders, payables, errors)

Authorization

  • Regular users can only view transactions from accounts they have access to through a bank key.
  • The company-id header also drives wallet-transaction visibility: wallet transactions inscribed by other users are hidden unless you hold wallet_transactions_view_all in the company set on the header. The scope applies this rule in SQL (with_wallet_visibility), so the same request under a different company-id can return a different set of wallet transactions.

Response Structure

The response includes the transaction details along with nested relationships:

  • recipient: Full recipient information including bank details
  • sender: Bank account information of the sender
  • bank_errors: Any errors encountered during processing
  • payables: Related invoices (if Pay product is activated)
  • payroll: Associated payroll information (if applicable)

Common Use Cases

  1. Get recent transactions: Use default pagination without filters
  2. Find high-value transactions: Filter by amount range
  3. Check transaction status: Filter by specific status values
  4. Audit trail: Sort by created_at or updated_at with date filters
  5. Reconciliation: Filter by external_id or date ranges
Recent Requests
Log in to see full request history
TimeStatusUser Agent
Retrieving recent requests…
LoadingLoading…
Query Params
integer
≥ 0

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

integer
≥ 0

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

string
enum

The order method, which can be ascending or descending

Allowed:
string

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

string

Only as an example of filtering results that have an amount less than $11000.
For more detailed explanation, go to the How to filter results section.

uuid

Filter transactions by sender bank account ID. Required for non-admin users to access transactions.

string

Filter by transaction status. Supports JSON operators:

  • Single status: "approved"
  • Multiple statuses: {"$in": ["approved", "declined"]}
  • Exclude status: {"$ne": "draft"}

Available statuses:

  • draft: Initial state when transaction is created
  • enqueued: Transaction queued for processing
  • dequeued: Transaction removed from queue
  • preauthorized: Transaction preauthorized by bank
  • declined: Transaction declined by bank
  • approved: Transaction approved and processed
  • payroll_authorized: The payroll this transaction belongs to was authorized; the bank has not yet reported the per-line outcome
uuid

Filter transactions by recipient ID

uuid

Filter transactions belonging to a specific payroll

string

Filter by creation date using JSON operators:

  • After date: {"$gte": "2025-01-01T00:00:00Z"}
  • Before date: {"$lt": "2025-02-01T00:00:00Z"}
  • Date range: {"$gte": "2025-01-01T00:00:00Z", "$lt": "2025-02-01T00:00:00Z"}
string

Filter by last update date. Same operators as created_at.

string

Filter by the bank's external transaction ID

string

Filter by transaction description. Supports:

  • Exact match: "Pago gastos"
  • Partial match: {"$like": "%gastos%"}
  • Case insensitive: {"$ilike": "%GASTOS%"}
string

Find transaction by idempotency key (useful for checking duplicate prevention)

uuid

Filter transactions by the company that owns them

string

Filter by current transition state:

  • enqueue: Being queued for processing
  • dequeue: Being removed from queue
  • authorize: Being authorized
  • preauthorize: Being preauthorized
  • remove: Being removed
  • null: No active transition
Headers
uuid
required

UUID of the company on whose behalf the request is made. Send it on banking
requests to identify the acting company. Note that user-scoped list endpoints
(e.g. the recipients/transactions indexes) resolve results across all companies
the authenticated user is a member of, rather than strictly from this header.
See The company-id header for details on how to obtain
a value for this header and the error responses to expect when it is missing or invalid.

Responses

401

Unauthorized — typically missing/invalid Authorization or missing company-id header.
The response body is empty for this guard. Branch your client logic on the status code,
not the body. See Errors for details.

Updated 5 days ago

Did this page help you?
Language
Credentials
Bearer
LoadingLoading…
Response
Click Try It! to start a request and see the response here! Or choose an example:
application/json

Updated 5 days ago

Did this page help you?