Create a bank payroll

Creates an empty bank payroll in draft state. The request body takes a
name and the sender_id (UUID of the source bank_account), plus the
optional online flag (true — the default — for same-day payrolls,
false for deferred), payment_date (required when online is false)
and category.

Line items are not part of this request — attach them by creating each
transaction via POST /v1/banking/bank_transactions with the new payroll's
id passed as bank_payroll_id.

Once the line items are in place, walk the lifecycle:

  1. POST /v1/banking/bank_payrolls/{id}/enroll — mandatory first step;
    requires status: draft, no transition in flight, and at least one
    attached transaction. The call answers 200 while the payroll is still
    transition: enroll; the bank settles it asynchronously into either
    enrolled or pending_validation (the branch step 2 covers), or
    enroll_failed. Poll the show endpoint for the landing state.
  2. POST /v1/banking/bank_payrolls/{id}/validateconditional branch,
    only when enrollment left the payroll in pending_validation (recipients
    the bank still needs validated). Requires token and
    verification_code.
  3. POST /v1/banking/bank_payrolls/{id}/preauthorize — requires
    status: enrolled.
  4. POST /v1/banking/bank_payrolls/{id}/authorize — final step; the payroll
    ends approved or declined.

See Tutorial: Emit a payroll and reconcile it.

Recent Requests
Log in to see full request history
TimeStatusUser Agent
Retrieving recent requests…
LoadingLoading…
Body Params

Request body.

string
required

Free-form label for the batch (e.g. "April vendor batch").

Banco BICE: the name must be unique per sender_id and may only
contain letters, digits and spaces. Reusing the name of an existing
payroll of the same account is rejected with 422.

uuid
required

The id of the bank account involved

boolean
Defaults to true

If true the payroll enrolls as "En línea" (same-day); if false, as
"Diferida" (deferred).

Optional — the column defaults to true, so omitting it means same-day.

BCI only supports deferred payrolls: online must be false there, and
any other value is rejected with 422.

date

Date on which the payroll will be paid (YYYY-MM-DD — date only, no time
component). Required only when online is false (deferred payrolls),
and it must be today or later; a deferred payroll without it — or with a
past date — is rejected with 422. The example is illustrative: send a date
that is still in the future at the moment of the call.

The dependency on online cannot be expressed in the schema itself —
OpenAPI 3.0 has no if/then or dependentRequired — so this field stays
optional at the contract level and the rule is enforced server-side.

string
enum
Defaults to suppliers

Optional grouping key for the batch. When omitted, Cardda applies the
sender bank's default (suppliers for every bank currently supported).

Allowed:
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 — missing or invalid bearer token, company-id header not
set, or sender_id names an account your user does not manage.

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