List bank payrolls

get

https://api.cardda.com/v1/banking/bank_payrolls/

Returns a paginated list of bank payrolls — the batches of wire-transfer transactions Cardda submits to a single bank account. A payroll groups multiple transactions so they can be authorized at the bank with a single TOTP / coordinate / signature challenge.

Use this endpoint to:

Show "month-end vendor batches" in your dashboard, sorted newest-first.
Audit the lifecycle of a batch (draft → pending_authorization → processing → confirmed / failed).
Reconcile each line item: the response includes transactions for every payroll, so you don't need a second round-trip per row.
Pull the receipt (receipt is true once the bank returns the proof of payment).

Response structure

Each payroll exposes:

Field	Description
`id`	UUID.
`name`	Free-form label (e.g. "April vendor batch").
`status`	Lifecycle status (see enum below).
`transition`	Currently-running async transition, when applicable (`enroll`, `preauthorize`, `authorize`, `remove`, `validate`, `sync`).
`payment_date`	Scheduled payment date (date only).
`category`	Optional grouping key set by the company.
`online`	Payment timing flag — `true` for same-day payrolls, `false` for deferred payrolls (a future `payment_date` is required).
`holder_id`	UUID of the company (multi-tenancy).
`sender_id`	UUID of the source `bank_account`.
`bank_id`	Bank where the payroll lives (e.g. `cl_banco_de_chile`, `cl_santander`).
`external_id`	Identifier returned by the bank once the payroll is accepted.
`number_of_transactions`	Count of line items in the batch.
`total`	Sum of `amount` across all `transactions`.
`transactions`	Embedded array of line items.
`receipt`	Whether a downloadable receipt exists. Pull it from `GET /v1/banking/bank_payrolls/{id}/receipt/url`.

Common queries

# Most recent 60 payrolls of a company (the dashboard's default)
GET /v1/banking/bank_payrolls?\
  holder_id=<company_uuid>&_order=desc&_field=created_at&_start=0&_end=60

# Only payrolls awaiting authorization (the "to-do" inbox)
GET /v1/banking/bank_payrolls?\
  status={"$in":["pending_authorization","preauthorized"]}&\
  holder_id=<company_uuid>

# Search by name
GET /v1/banking/bank_payrolls?\
  name={"$regex":"april"}&holder_id=<company_uuid>

# Batch fetch by id
GET /v1/banking/bank_payrolls?id={"$in":["<uuid1>","<uuid2>"]}

# Payrolls of a specific source account
GET /v1/banking/bank_payrolls?sender_id=<bank_account_uuid>

All operators in Filters ($gt, $lt, $in, $regex, $or, $ne, …) are supported across every column listed in Query parameters.

Recent Requests

Time	Status	User Agent
Retrieving recent requests…

Loading…

Query Params

_start

integer

≥ 0

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

_end

integer

≥ 0

If all the transactions 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

string

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

holder_id

uuid

UUID of the company that owns the payroll. The most common filter — the dashboard always pins the active company here. Equivalent to the company-id header for ownership scoping.

sender_id

uuid

UUID of the source bank_account.

bank_id

string

Bank identifier. Use GET /v1/banking/banks for the catalog. Examples: cl_banco_de_chile, cl_santander, cl_bci, cl_security, cl_itau, cl_banco_estado, mx_stp, pe_bcp.

status

string

enum

Lifecycle status of the payroll.

transition

string

enum

Async state machine transition currently running on the payroll.

Allowed:

name

string

Free-form label. Combines well with $regex for text search.

type

string

STI subclass — controls which bank-specific behaviors apply. The values are bank-prefixed (e.g. Banking::BancoDeChile::BankPayroll). Only set this if you specifically want one bank's payrolls.

payment_date

string

Scheduled payment date (YYYY-MM-DD). Accepts a single date string or a JSON-encoded operator object ({"$gte":"...","$lt":"..."}). Schema is type: string (no format) so both forms validate.

external_id

string

Bank-assigned identifier returned once the batch is accepted. Useful for reconciliation against the bank's own statement.

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.

Headers

company-id

uuid

required

UUID of the company on whose behalf the request is made. Required for every banking endpoint. 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 — missing or invalid bearer token, or company-id header not set.

403

Forbidden — user is not a member of the company referenced by company-id.

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