CAcardda
Bank payroll

List bank payrolls

Changed on

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 → enrolled → preauthorized → approved / declined).
  • 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:

FieldDescription
idUUID.
nameFree-form label (e.g. "April vendor batch").
statusLifecycle status (see enum below).
transitionCurrently-running async transition, when applicable (enroll, preauthorize, authorize, delete).
payment_dateScheduled payment date (date only).
categoryOptional grouping key set by the company.
onlinePayment timing flag — true for same-day payrolls, false for deferred payrolls (a future payment_date is required).
holder_idUUID of the company (multi-tenancy).
sender_idUUID of the source bank_account.
bank_idBank where the payroll lives (e.g. cl_banco_de_chile, cl_santander).
external_idIdentifier returned by the bank once the payroll is accepted.
number_of_transactionsCount of line items in the batch.
totalSum of amount across all transactions.
transactionsEmbedded array of line items.
receiptWhether 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":["enrolled","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.

get/v1/banking/bank_payrolls/

Request

Query parameters

idstring

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

holder_idstring 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_idstring uuid

UUID of the source bank_account.

bank_idstring

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'draft' | 'enrolled' | 'enroll_failed' | 'pending_validation' | 'preauthorized' | 'approved' | 'declined' | 'deleted'
Example:approved

Lifecycle status of the payroll.

transition'enroll' | 'preauthorize' | 'authorize' | 'delete'
Example:authorize

Async state machine transition currently running on the payroll.

namestring

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

typestring

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_datestring

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_idstring

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

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.

Parameters

#/paths/~1v1~1banking~1bank_keys/get/parameters/0 (unresolved $ref)
#/paths/~1v1~1banking~1banks/get/parameters/0 (unresolved $ref)
#/paths/~1v1~1banking~1banks/get/parameters/1 (unresolved $ref)
#/paths/~1v1~1banking~1banks/get/parameters/2 (unresolved $ref)
#/paths/~1v1~1banking~1banks/get/parameters/3 (unresolved $ref)

Response

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

idstring uuid required

Unique identifier for the payroll

sender_idstring uuid required

ID of the bank account that will send the payments

status'draft' | 'enrolled' | 'enroll_failed' | 'pending_validation' | 'preauthorized' | 'approved' | 'declined' | 'deleted' required

Current status of the payroll

transition'enroll' | 'preauthorize' | 'authorize' | 'delete' nullable required

Current transition being processed for the payroll

namestring required

Name of the payroll

external_idstring nullable

External identifier assigned by the bank. Null until the bank accepts the payroll.

bank_idstring

Identifier of the bank where the payroll will be processed

holder_idstring uuid

ID of the company that owns this payroll

raw_dataobject nullable

Raw data from the bank system, can contain any data structure

payment_datestring date nullable

Date when the payment is scheduled to be processed

categorystring

Category of the payroll (e.g., suppliers, employees)

onlineboolean

Indicates whether the payroll will be paid the same day (true) or is deferred (false)

number_of_transactionsinteger nullable

Count of line items in the batch.

totalinteger nullable

Sum of amount across all line items, in the minor unit of the account's currency — the whole peso for CLP. See Amounts and currency.

receiptboolean

Whether a downloadable receipt exists. Pull it from GET /v1/banking/bank_payrolls/{id}/receipt/url.

bank_errorsItems[] (unresolved $ref)

List of errors returned by the bank for this payroll

created_atstring date-time

Timestamp when the payroll was created

updated_atstring date-time

Timestamp when the payroll was last updated

Changes