Overview
Only 3 API calls needed — everything after approval is automatic.Create a payroll
Select the worker type (employee/contractor) and create a payroll.
POST /v1/payrolls → Webhook: payroll.createdSave entries
Provide the pay date, pay period, and compensation for each worker.
POST /v1/payrolls/{id}/save → Webhook: payroll.status.updated (saved)Approve
Approve the payroll to trigger fund collection and scheduling.
POST /v1/payrolls/{id}/approve → Webhook: payroll.status.updated (approved)What Happens After Approval
Once you callPOST /v1/payrolls/{id}/approve, the rest is automatic:
Balance Check
Cadana checks whether the business account has sufficient funds to cover the payroll.- Sufficient funds — the payroll moves to
scheduledand is queued for the payroll date. Webhook:payroll.status.updated(scheduled) - Insufficient funds — the payroll moves to
awaiting funds. If a bank account is connected, an ACH debit initiates automatically. Once the account is funded, the payroll proceeds — no need to re-approve.
Scheduling
If the payroll date is in the future, the payroll stays inscheduled until that date. If the payroll date is today or in the past, disbursement begins immediately.
Disbursement
On the payroll date, Cadana triggers disbursements for each worker. The payroll moves toprocessing. Each worker’s payment is handled independently — if one worker’s payment fails, the others continue. Webhook: payroll.status.updated (processing)
Completion
Once all disbursements are confirmed, the payroll moves tocompleted. Webhook: payroll.status.updated (completed)
After completion, the payroll response includes an invoiceId. Fetch the invoice for a detailed breakdown of fees charged for the payroll run.
Status Reference
| Status | Meaning |
|---|---|
created | Empty payroll shell, no entries yet |
saved | Entries added, ready for approval |
approved | Approved — Cadana is checking the business balance |
awaiting funds | Insufficient balance — payroll proceeds automatically once funded |
scheduled | Funds collected, queued for the payroll date |
processing | Disbursements being sent to workers |
completed | All disbursements confirmed |
deleted | Payroll removed before processing started |
Deleting a Payroll
You can delete a payroll at any point before it starts processing. Returns204 on success. The payroll moves to deleted.
Webhook Events
Cadana emits two payroll webhook event types. Subscribe via the Dashboard or see Webhooks for setup.payroll.created
Fired when a new payroll is created.JSON
payroll.status.updated
Fired on every status transition after creation. Thestatus field tells you the new state.
JSON
| Transition | status value |
|---|---|
| Entries saved | saved |
| Payroll approved | approved |
| Funds collected, payroll queued | scheduled |
| Disbursements triggered | processing |
| All disbursements confirmed | completed |
Per-Worker Transaction Events
Each worker’s payment fires individual transaction events:transaction.initiated, transaction.succeeded, and transaction.failed. These let you track each worker’s payout independently of the overall payroll status.
The transaction’s reference field contains the payrollId, and recipientId contains the worker’s personId (for direct bank payments) or wallet identifier (for Cadana wallet payments).
JSON
Multi-Currency Payrolls
When a worker’s salary currency differs from the business’s funding currency (e.g., a US company paying a contractor in BRL), FX conversion is involved.How It Works
FX rates captured at save time
Cadana captures FX rates and calculates the debit amount in the funding currency. Each entry stores its conversion rate individually.
Rates may refresh at disbursement time
If there’s a delay between save and disbursement (future payroll date, awaiting funds, etc.), rates may be refreshed with current market rates.
Recommended Approach
- Poll after save — check the
debitamount on the payroll to understand the total cost in your funding currency. - Fund with headroom — if your payroll date is days away, consider funding slightly above the quoted debit to absorb potential rate movement.
- Monitor
awaiting funds— if a rate refresh causes the debit to exceed your balance, the payroll pauses until you top up.
Edge Cases
Individual Worker Payment Fails
If one worker’s disbursement fails (e.g., invalid bank details), the other workers’ payments continue. The payroll still moves tocompleted once all disbursements are resolved. Use transaction.failed webhooks to identify which worker’s payment needs attention.
Multiple Payrolls Awaiting Funds
When multiple payrolls are inawaiting funds and the business adds funds, Cadana schedules them in priority order:
- Earliest payroll date first
- Creation time as a tiebreaker
scheduled. The rest remain in awaiting funds until more funds are added.
Payroll Stuck in Awaiting Funds
The payroll remains inawaiting funds indefinitely until the business account is funded. Once sufficient funds are available, the payroll proceeds automatically. See Fund Your Account for funding options.