--- title: "List bank payrolls" method: GET path: "/v1/banking/bank_payrolls/" tags: ["Bank payroll"] --- # List bank payrolls `GET /v1/banking/bank_payrolls/` ## Request - Base URL: `https://api.cardda.com` - URL: `https://api.cardda.com/v1/banking/bank_payrolls/` - Auth: HTTP bearer - TypeScript: (a function with typed inputs; its response is checked against the schema) 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: | 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`, `delete`). | | `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 ```bash # Most recent 60 payrolls of a company (the dashboard's default) GET /v1/banking/bank_payrolls?\ holder_id=&_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= # Search by name GET /v1/banking/bank_payrolls?\ name={"$regex":"april"}&holder_id= # Batch fetch by id GET /v1/banking/bank_payrolls?id={"$in":["",""]} # Payrolls of a specific source account GET /v1/banking/bank_payrolls?sender_id= ``` All operators in [Filters](https://docs.cardda.com/docs/filters) (`$gt`, `$lt`, `$in`, `$regex`, `$or`, `$ne`, …) are supported across every column listed in **Query parameters**. ## Query parameters - `id` string - `holder_id` string, uuid - `sender_id` string, uuid - `bank_id` string - `status` 'draft' | 'enrolled' | 'enroll_failed' | 'pending_validation' | 'preauthorized' | 'approved' | 'declined' | 'deleted' - `transition` 'enroll' | 'preauthorize' | 'authorize' | 'delete' - `name` string - `type` string - `payment_date` string - `external_id` string - `created_at` string ## 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 `200` Paginated list of bank payrolls. Headers include `X-Total-Count` and `Content-Range` for offset pagination — see [Pagination](https://docs.cardda.com/docs/pagination). - BankPayroll[] - `id` string, uuid, required: Unique identifier for the payroll - `sender_id` string, uuid, required: ID of the bank account that will send the payments - `sender` BankAccount - `id` string, uuid, required - `balance` integer, nullable: The account balance, in the currency's minor unit, as Cardda read it the last time it synced the account with the bank. **This field is not included in every response that uses this schema.** Only `GET /v1/banking/bank_accounts`, `GET /v1/banking/bank_accounts/{bank_account_id}` and the payroll-level `sender` (`Bank_payroll.sender`) of each row in `GET /v1/banking/bank_payrolls/` (the account the payroll is paid from, not the `sender` of its transactions) return it, and only if the company that holds the account turned on **"Mostrar el saldo y las inversiones"** in its company settings (Configuración de la empresa). When that setting is off, the `balance` key is omitted entirely (it is not sent as `null`, which in this API means something else: "we have never read this account"). Everywhere else this schema is reused — `Bank_transaction.sender` and `Bank_key_filtered.accounts` — the key is always omitted, regardless of that setting: there the account identifies where the payment comes from, it does not report its funds. An integration that needs the balance should read it from `GET /v1/banking/bank_accounts`. - `holder_id` string, uuid, nullable: UUID of the Person (company or counterpart) that owns the account. - `bank_id` string: Bank identifier, e.g. `cl_banco_de_chile`, `mx_stp`, `us_mercury`. - `type` string: STI subclass, bank-specific (e.g. `Banking::Cl::BancoDeChile::Account`). - `number` string, required - `rut` string, required - `email` string - `name` string - `account_type` 'corriente' | 'vista' | 'ahorro' | 'clabe' | 'yape', nullable: Chilean account types are the following: > * 'corriente' > * 'vista' > * 'ahorro' Mexican account types are the following: > * 'clabe' Peruvian account types are the following: > * 'yape' For more details check the [guide](https://docs.cardda.com/docs). - `bank_errors` object[] - `id` string, uuid - `banking_entity_id` string, uuid - `banking_entity_type` string - `error_code` 'auth/wrong-credentials' | 'auth/invalid-body' | 'recipient/create/invalid-body' | 'recipient/create/unknown-bank-name' | 'recipient/create/unknown-account-type' | 'recipient/get/unknown-bank-name' | 'recipient/get/unknown-account-type' | 'recipient/authorization/not-found' | 'recipient/authorization/invalid-data' | 'transaction/enqueue/invalid-body' | 'transaction/enqueue/first-transaction-max-amount' | 'transaction/enqueue/transaction-daily-max-amount' | 'transaction/enqueue/recipient-not-registered' | 'transaction/enqueue/sender-account-not-fund' | 'transaction/enqueue/recipient-collision' | 'transaction/enqueue/sender-collision' | 'transaction/dequeue/invalid-body' | 'transaction/dequeue/not-found' | 'transaction/dequeue/dequeue-all-unsuccessful' | 'transaction/dequeue/no-queued-transactions' | 'transaction/get/unknown-status' | 'transaction/get/unknown-date-format' | 'transaction/get/invalid-body' | 'transaction/authorization/invalid-body' | 'transaction/authorization/wrong-token' | 'transaction/authorization/invalid-method' | 'transaction/authorization/no-queued-transactions' | 'transaction/authorization/insufficient-funds' | 'transaction/authorization/account-token-blocked' | 'account/get/not-found' | 'account/common/blocked-auth-devices' | 'account/common/temporary-blocked' | 'page/failed-to-load-components' | 'page/recipient-save-unsuccessful' | 'page/transaction-enqueue-unsuccessful' | 'page/transaction-authorization-unsuccessful' | 'request/expired-cookies', nullable - `created_at` string, date-time - `updated_at` string, date-time - `created_at` string, date-time - `updated_at` string, date-time - `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 - `name` string, required: Name of the payroll - `external_id` string, nullable: External identifier assigned by the bank. Null until the bank accepts the payroll. - `bank_id` string: Identifier of the bank where the payroll will be processed - `holder_id` string, uuid: ID of the company that owns this payroll - `raw_data` object, nullable: Raw data from the bank system, can contain any data structure - `payment_date` string, date, nullable: Date when the payment is scheduled to be processed - `category` string: Category of the payroll (e.g., suppliers, employees) - `online` boolean: Indicates whether the payroll will be paid the same day (true) or is deferred (false) - `transactions` BankTransaction[]: List of bank transactions associated with this payroll - `id` string, uuid, required: Unique identifier for the transaction - `external_id` string: The ID assigned to the transaction in the bank systems - `sender_id` string, uuid, required: The ID of the bank account that will send the payment - `recipient_id` string, uuid, required: The ID of the bank recipient that will receive the payment - `bank_payroll_id` string, uuid, nullable: The ID of the payroll this transaction belongs to, if any - `lbtr` boolean: This attribute indicates that a transaction does not have an amount limit. Only available at Banco de Chile and Santander - `payroll` object, nullable: The payroll this transaction belongs to, if any - `id` string, uuid - `created_at` string, date-time - `updated_at` string, date-time - `status` 'draft' | 'enrolled' | 'enroll_failed' | 'pending_validation' | 'preauthorized' | 'approved' | 'declined' | 'deleted': Current status of the payroll. Mirrors `Bank_payroll.status`. - `transition` 'enroll' | 'preauthorize' | 'authorize' | 'delete', nullable: Async state-machine transition currently running on the payroll. Mirrors `Bank_payroll.transition`. - `sender_id` string, uuid - `name` string - `external_id` string, nullable: External identifier assigned by the bank. Null until the bank accepts the payroll. - `bank_id` string - `holder_id` string, uuid - `raw_data` object, nullable: Raw data from the bank system, can contain any data structure - `payment_date` string, date, nullable: Date when the payment is scheduled to be processed - `category` string - `online` boolean: Indicates whether the payroll will be paid the same day (true) or is deferred (false) - `sender` BankAccount - `id` string, uuid, required - `balance` integer, nullable: The account balance, in the currency's minor unit, as Cardda read it the last time it synced the account with the bank. **This field is not included in every response that uses this schema.** Only `GET /v1/banking/bank_accounts`, `GET /v1/banking/bank_accounts/{bank_account_id}` and the payroll-level `sender` (`Bank_payroll.sender`) of each row in `GET /v1/banking/bank_payrolls/` (the account the payroll is paid from, not the `sender` of its transactions) return it, and only if the company that holds the account turned on **"Mostrar el saldo y las inversiones"** in its company settings (Configuración de la empresa). When that setting is off, the `balance` key is omitted entirely (it is not sent as `null`, which in this API means something else: "we have never read this account"). Everywhere else this schema is reused — `Bank_transaction.sender` and `Bank_key_filtered.accounts` — the key is always omitted, regardless of that setting: there the account identifies where the payment comes from, it does not report its funds. An integration that needs the balance should read it from `GET /v1/banking/bank_accounts`. - `holder_id` string, uuid, nullable: UUID of the Person (company or counterpart) that owns the account. - `bank_id` string: Bank identifier, e.g. `cl_banco_de_chile`, `mx_stp`, `us_mercury`. - `type` string: STI subclass, bank-specific (e.g. `Banking::Cl::BancoDeChile::Account`). - `number` string, required - `rut` string, required - `email` string - `name` string - `account_type` 'corriente' | 'vista' | 'ahorro' | 'clabe' | 'yape', nullable: Chilean account types are the following: > * 'corriente' > * 'vista' > * 'ahorro' Mexican account types are the following: > * 'clabe' Peruvian account types are the following: > * 'yape' For more details check the [guide](https://docs.cardda.com/docs). - `bank_errors` object[] - `id` string, uuid - `banking_entity_id` string, uuid - `banking_entity_type` string - `error_code` 'auth/wrong-credentials' | 'auth/invalid-body' | 'recipient/create/invalid-body' | 'recipient/create/unknown-bank-name' | 'recipient/create/unknown-account-type' | 'recipient/get/unknown-bank-name' | 'recipient/get/unknown-account-type' | 'recipient/authorization/not-found' | 'recipient/authorization/invalid-data' | 'transaction/enqueue/invalid-body' | 'transaction/enqueue/first-transaction-max-amount' | 'transaction/enqueue/transaction-daily-max-amount' | 'transaction/enqueue/recipient-not-registered' | 'transaction/enqueue/sender-account-not-fund' | 'transaction/enqueue/recipient-collision' | 'transaction/enqueue/sender-collision' | 'transaction/dequeue/invalid-body' | 'transaction/dequeue/not-found' | 'transaction/dequeue/dequeue-all-unsuccessful' | 'transaction/dequeue/no-queued-transactions' | 'transaction/get/unknown-status' | 'transaction/get/unknown-date-format' | 'transaction/get/invalid-body' | 'transaction/authorization/invalid-body' | 'transaction/authorization/wrong-token' | 'transaction/authorization/invalid-method' | 'transaction/authorization/no-queued-transactions' | 'transaction/authorization/insufficient-funds' | 'transaction/authorization/account-token-blocked' | 'account/get/not-found' | 'account/common/blocked-auth-devices' | 'account/common/temporary-blocked' | 'page/failed-to-load-components' | 'page/recipient-save-unsuccessful' | 'page/transaction-enqueue-unsuccessful' | 'page/transaction-authorization-unsuccessful' | 'request/expired-cookies', nullable - `created_at` string, date-time - `updated_at` string, date-time - `created_at` string, date-time - `updated_at` string, date-time - `recipient` BankRecipient - `id` string, uuid, required - `name` string - `alias` string - `owner_id` string, uuid, required - `rut` string: The rut must not contain dots or hyphens, and if it ends up with a k this letter should be capitalized - `email` string - `account_type` 'corriente' | 'vista' | 'ahorro' | 'clabe' | 'yape': Chilean account types are the following: > * 'corriente' > * 'vista' > * 'ahorro' Mexican account types are the following: > * 'clabe' Peruvian account types are the following: > * 'yape' For more details check the [guide](https://docs.cardda.com/docs). - `account_number` string, required - `person_id` string, uuid: the id of the company that owns this recipient - `bank_id` 'cl_banco_de_chile' | 'cl_banco_internacional' | 'cl_banco_scotiabank' | 'cl_banco_scotiabank_azul' | 'cl_banco_bci' | 'cl_banco_bice' | 'cl_hsbc_bank' | 'cl_banco_santander_chile' | 'cl_banco_itau' | 'cl_banco_security' | 'cl_banco_falabella' | 'cl_banco_ripley' | 'cl_banco_consorcio' | 'cl_banco_btg_pactual_chile' | 'cl_banco_estado' | 'cl_banco_corpbanca' | 'cl_banco_paris' | 'cl_coopeuch' | 'cl_mercado_pago' | 'cl_prepago_los_heroes' | 'cl_tapp_caja_los_andes' | 'cl_tenpo_prepago_sa' | 'cl_banco_del_desarrollo' | 'cl_transbank' | 'cl_banco_do_brasil' | 'cl_jp_morgan_chase_bank' | 'cl_mufg_bank' | 'cl_banco_sudamericano' | 'cl_rabobank' | 'cl_china_construction_bank' | 'cl_bank_of_china' | 'cl_banco_de_la_nacion_argentina' | 'cl_banco_penta' | 'cl_abn_amro_bank' | 'mx_banxico' | 'mx_bancomext' | 'mx_banobras' | 'mx_banjercito' | 'mx_nafin' | 'mx_babien' | 'mx_hipotecaria_fed' | 'mx_banamex' | 'mx_bbva_mexico' | 'mx_santander' | 'mx_hsbc' | 'mx_bajio' | 'mx_inbursa' | 'mx_mifel' | 'mx_scotiabank' | 'mx_banregio' | 'mx_invex' | 'mx_bansi' | 'mx_afirme' | 'mx_banorte' | 'mx_bank_of_america' | 'mx_mufg' | 'mx_jp_morgan' | 'mx_bmonex' | 'mx_ve_por_mas' | 'mx_azteca' | 'mx_autofin' | 'mx_barclays' | 'mx_compartamos' | 'mx_multiva_banco' | 'mx_actinver' | 'mx_intercam_banco' | 'mx_bancoppel' | 'mx_abc_capital' | 'mx_consubanco' | 'mx_volkswagen' | 'mx_cibanco' | 'mx_bbase' | 'mx_bankaool' | 'mx_pagatodo' | 'mx_inmobiliario' | 'mx_donde' | 'mx_bancrea' | 'mx_banco_covalto' | 'mx_icbc' | 'mx_sabadell' | 'mx_shinhan' | 'mx_mizuho_bank' | 'mx_bank_of_china' | 'mx_banco_s3' | 'mx_monexcb' | 'mx_gbm' | 'mx_masari' | 'mx_value' | 'mx_vector' | 'mx_finamex' | 'mx_valmex' | 'mx_profuturo' | 'mx_cb_intercam' | 'mx_ci_bolsa' | 'mx_fincomun' | 'mx_nu_mexico' | 'mx_reforma' | 'mx_stp' | 'mx_credicapital' | 'mx_kuspit' | 'mx_unagra' | 'mx_asp_integra_opc' | 'mx_alternativos' | 'mx_libertad' | 'mx_caja_pop_mexica' | 'mx_cristobal_colon' | 'mx_caja_telefonist' | 'mx_transfer' | 'mx_fondo_fira' | 'mx_invercap' | 'mx_fomped' | 'mx_tesored' | 'mx_nvio' | 'mx_indeval' | 'mx_arcus' | 'pe_banco_bcp' | 'pe_banco_yape' - `bank` Bank - `created_at` string, date-time - `id` 'cl_banco_de_chile' | 'cl_banco_internacional' | 'cl_banco_scotiabank' | 'cl_banco_scotiabank_azul' | 'cl_banco_bci' | 'cl_banco_bice' | 'cl_hsbc_bank' | 'cl_banco_santander_chile' | 'cl_banco_itau' | 'cl_banco_security' | 'cl_banco_falabella' | 'cl_banco_ripley' | 'cl_banco_consorcio' | 'cl_banco_btg_pactual_chile' | 'cl_banco_estado' | 'cl_banco_corpbanca' | 'cl_banco_paris' | 'cl_coopeuch' | 'cl_mercado_pago' | 'cl_prepago_los_heroes' | 'cl_tapp_caja_los_andes' | 'cl_tenpo_prepago_sa' | 'cl_banco_del_desarrollo' | 'cl_transbank' | 'cl_banco_do_brasil' | 'cl_jp_morgan_chase_bank' | 'cl_mufg_bank' | 'cl_banco_sudamericano' | 'cl_rabobank' | 'cl_china_construction_bank' | 'cl_bank_of_china' | 'cl_banco_de_la_nacion_argentina' | 'cl_banco_penta' | 'cl_abn_amro_bank' | 'mx_banxico' | 'mx_bancomext' | 'mx_banobras' | 'mx_banjercito' | 'mx_nafin' | 'mx_babien' | 'mx_hipotecaria_fed' | 'mx_banamex' | 'mx_bbva_mexico' | 'mx_santander' | 'mx_hsbc' | 'mx_bajio' | 'mx_inbursa' | 'mx_mifel' | 'mx_scotiabank' | 'mx_banregio' | 'mx_invex' | 'mx_bansi' | 'mx_afirme' | 'mx_banorte' | 'mx_bank_of_america' | 'mx_mufg' | 'mx_jp_morgan' | 'mx_bmonex' | 'mx_ve_por_mas' | 'mx_azteca' | 'mx_autofin' | 'mx_barclays' | 'mx_compartamos' | 'mx_multiva_banco' | 'mx_actinver' | 'mx_intercam_banco' | 'mx_bancoppel' | 'mx_abc_capital' | 'mx_consubanco' | 'mx_volkswagen' | 'mx_cibanco' | 'mx_bbase' | 'mx_bankaool' | 'mx_pagatodo' | 'mx_inmobiliario' | 'mx_donde' | 'mx_bancrea' | 'mx_banco_covalto' | 'mx_icbc' | 'mx_sabadell' | 'mx_shinhan' | 'mx_mizuho_bank' | 'mx_bank_of_china' | 'mx_banco_s3' | 'mx_monexcb' | 'mx_gbm' | 'mx_masari' | 'mx_value' | 'mx_vector' | 'mx_finamex' | 'mx_valmex' | 'mx_profuturo' | 'mx_cb_intercam' | 'mx_ci_bolsa' | 'mx_fincomun' | 'mx_nu_mexico' | 'mx_reforma' | 'mx_stp' | 'mx_credicapital' | 'mx_kuspit' | 'mx_unagra' | 'mx_asp_integra_opc' | 'mx_alternativos' | 'mx_libertad' | 'mx_caja_pop_mexica' | 'mx_cristobal_colon' | 'mx_caja_telefonist' | 'mx_transfer' | 'mx_fondo_fira' | 'mx_invercap' | 'mx_fomped' | 'mx_tesored' | 'mx_nvio' | 'mx_indeval' | 'mx_arcus' | 'pe_banco_bcp' | 'pe_banco_yape' - `image_url` string - `name` string - `updated_at` string, date-time - `external_id` string, uuid - `bank_former_name` string - `status` 'draft' | 'enrolled' | 'preauthorized' | 'deleted' | 'approved' - `transition` 'enroll' | 'authorize' | 'preauthorize' | 'delete', nullable - `bank_errors` Items[] (unresolved $ref) - `metadata` unknown - `created_at` string, date-time - `updated_at` string, date-time - `holder_id` string, uuid: The ID of the company that owns this bank transaction - `status` 'draft' | 'enqueued' | 'dequeued' | 'preauthorized' | 'declined' | 'approved' | 'payroll_authorized', required: Current status of the transaction - `transition` 'enqueue' | 'dequeue' | 'authorize' | 'preauthorize' | 'remove': Current transition being processed for the transaction - `description` string: Description of the transaction - `raw_data` string, nullable: The raw data stored from the banks - `metadata` object: Additional metadata for the transaction - `receipt` boolean: Indicates whether the transaction's receipt is available - `payables` object[]: List of invoices paid with this transaction (only available if pay product is activated) - `amount` integer, required: Amount of the transaction, as an integer in the minor unit of the account's currency. For CLP that is the whole peso — `1450` is $1.450, not $14,50. See [Amounts and currency](https://docs.cardda.com/docs/amounts-and-currency). - `decline_motive` string: Reason for declining the transaction if it was declined - `bank_errors` Items[]: List of errors returned by the bank for this transaction (unresolved $ref) - `created_at` string, date-time: Timestamp when the transaction was created - `updated_at` string, date-time: Timestamp when the transaction was last updated - `authorized_at` string, date-time: Timestamp when the transaction was authorized - `enqueued_at` string, date-time: Timestamp when the transaction was enqueued - `idempotency_id` string, nullable: Unique identifier to prevent duplicate transactions - `number_of_transactions` integer, nullable: Count of line items in the batch. - `total` integer, 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](https://docs.cardda.com/docs/amounts-and-currency). - `receipt` boolean: Whether a downloadable receipt exists. Pull it from `GET /v1/banking/bank_payrolls/{id}/receipt/url`. - `bank_errors` Items[]: List of errors returned by the bank for this payroll (unresolved $ref) - `created_at` string, date-time: Timestamp when the payroll was created - `updated_at` string, date-time: Timestamp when the payroll was last updated ## Other responses - `401`: Unauthorized — missing or invalid bearer token, `company-id` header not set, or the caller is not authorized for the requested scope. Pundit authorization failures return `401` with an empty body (no `403`). ## Changes - **2026-11-03** `785332193a09`: 1 info - endpoint added [Operation history](https://skmtc.dev/cardda/apis/banking-api/changes/v1/banking/bank_payrolls/get.md) --- [API](https://skmtc.dev/cardda/apis/banking-api.md) - [All operations](https://skmtc.dev/cardda/apis/banking-api/llms.txt) - [OpenAPI document](https://skmtc.dev/cardda/apis/banking-api/revisions/785332193a09?raw)