Pay Workers via Payroll

This guide details the steps needed for a business to pay its workers via a scheduled payroll. Cadana handles fund collection, scheduling, and disbursement automatically.

Prerequisites

API key from Dashboard

Get your API key from the Cadana Dashboard. See Authentication for details.

Compliance-approved business

Your business must have completed KYB verification. See KYB Requirements.

Account funded

Your business account must have sufficient funds to cover the payroll. See Fund Your Account.

Onboarded workers

Workers must be onboarded as Persons with payment methods configured — you’ll use their personId to set up pay entries. See Onboard Workers.

Step 1: Create a Payroll

Start by creating an empty payroll shell. Specify the worker type and whether this is a one-off or regular payroll. Response:

{
  "payrollId": "a1b2c3d4-e5f6-7890-abcd-ef0123456789"
}

Save the payrollId — you’ll use it in the next steps.

Payroll Types

Field	Values	Description
`workerType`	`EMPLOYEE`, `CONTRACTOR`	Type of workers being paid
`type`	`ONE_OFF`, `REGULAR`	One-off payment or recurring payroll

Step 2: Save Entries

Add the pay date, pay period, and compensation entries for each worker. Each entry requires a personId and salary amount. If you set compensation info (compInfo) when onboarding the worker, you can retrieve it from the Person profile with GET /v1/persons/{personId} and use those values for the salary entry. Returns 204 on success. The payroll status moves to saved. Fetch the payroll with GET /v1/payrolls/{id} to see the calculated debit — the total amount that will be debited from the business account.

Amounts are in the lowest denomination of the currency. For USD, 100000 = $1,000.00. For GHS, 500000 = GHS 5,000.00.

You can re-save a payroll to update entries before approving. Each save replaces the previous entries.

For workers with variable pay (e.g., hourly contractors), set compInfo.salary to 0 during onboarding and provide the actual amount when saving payroll entries.

Custom Metadata

You can pass a tags object on both the create and save requests to store custom metadata against the payroll (e.g., internal reference IDs, department codes). This is a free-form object — any key-value pairs you include will be persisted and returned when you retrieve the payroll.

Custom Fees (Platforms)

Platforms can pass a customFees array on the save request to add platform-specific fee line items to the payroll invoice. Each item requires a name and amount. These are additive — they supplement standard per-seat subscription fees and are included in the total amount collected by Cadana on your behalf.

{
  "customFees": [
    { "name": "Platform Fee", "amount": { "amount": 50000, "currency": "USD" } },
    { "name": "Processing Fee", "amount": { "amount": 10000, "currency": "USD" } }
  ]
}

Custom fee items do not participate in revenue share calculations. Validation returns 400 for empty names, non-positive amounts, or missing currency.

Save Errors

When saving entries fails validation, the API returns 400 with an invalid_request_body code. Each error in the params object is prefixed with a [ErrorType] tag you can use to programmatically filter or map errors. Response format:

{
  "code": "invalid_request_body",
  "message": "One or more input values are invalid. Please re-renter valid values",
  "params": {
    "entry-0-paymentInfo": "[EmptyWalletDetails] Jane Doe has invalid payment method set: Wallet details cannot be empty for wallet payments",
    "entry-1-personId": "[PersonNotFound] Person ID 8ef9a712-cdae-4110-b1ea-9ba95abbee6e is not a valid person in the system"
  }
}

Error types:

Error Type	Description
`NoPaymentMethod`	Person has no payment method configured
`PersonNotFound`	Person ID does not match any person in the system
`EmptyWalletDetails`	Wallet details are missing when payment method is wallet
`InvalidPreferredMethod`	Preferred method is not a supported type
`RestrictedCountry`	Beneficiary country is restricted for payments
`InvalidBankDetails`	Bank payment validation failed (e.g., missing account name, invalid IBAN)
`InvalidMomoDetails`	Mobile money validation failed (e.g., missing phone number, provider)
`InvalidWalletDetails`	Wallet validation failed (e.g., invalid currency)
`InvalidCryptoDetails`	Crypto wallet validation failed (e.g., missing address, unsupported chain)
`InvalidAchDetails`	ACH payment validation failed
`InvalidSwiftDetails`	SWIFT payment validation failed
`InvalidCardDetails`	Card payment validation failed
`InvalidProxyDetails`	Proxy payment validation failed
`InvalidPaymentDetails`	Catch-all for unrecognized payment method types

To extract the error type programmatically, split the param value on "] " — the text before it is the error type (without the leading [).

Step 3: Approve

Once you’re satisfied with the entries, approve the payroll. This triggers fund collection and schedules disbursement. Returns 204 on success. The payroll status moves to approved. After approval:

If the business has insufficient funds, the payroll moves to awaiting funds. If a bank account is connected, an ACH debit initiates automatically.
If the scheduled date is in the future, the payroll will be processed on the scheduled day.
Once funds are available, the payroll processes and disburses payments to workers automatically.

Tracking Payroll Status

Poll the payroll to check its current status and see calculated totals. Response:

{
  "payrollId": "a1b2c3d4-e5f6-7890-abcd-ef0123456789",
  "workerType": "CONTRACTOR",
  "status": "completed",
  "type": "ONE_OFF",
  "invoiceId": "8dbaa174-b5a0-4396-8c87-77e746b50917",
  "payrollDate": "2026-02-28",
  "numPeople": 2,
  "debit": { "amount": 175000, "currency": "USD" },
  "gross": { "amount": 175000, "currency": "USD" },
  "net": { "amount": 175000, "currency": "USD" },
  "tax": { "amount": 0, "currency": "USD" },
  "pension": { "amount": 0, "currency": "USD" },
  "payPeriod": {
    "fromDate": "2026-02-01",
    "toDate": "2026-02-28"
  },
  "entries": [
    {
      "personId": "8ef9a712-cdae-4110-b1ea-9ba95abbee6e",
      "salary": { "amount": 100000, "currency": "USD" }
    },
    {
      "personId": "3c7d9e21-fa4b-4a12-bc89-0d1234567890",
      "salary": { "amount": 75000, "currency": "USD" }
    }
  ]
}

Once a payroll reaches completed, the response includes an invoiceId. Use GET /v1/invoices/{invoiceId} to retrieve a detailed breakdown of fees charged for the payroll run.

List All Payrolls

Response:

{
  "data": [
    {
      "payrollId": "a1b2c3d4-e5f6-7890-abcd-ef0123456789",
      "workerType": "CONTRACTOR",
      "status": "completed",
      "type": "ONE_OFF",
      "payrollDate": "2026-02-28",
      "numPeople": 2,
      "debit": { "amount": 175000, "currency": "USD" },
      "gross": { "amount": 175000, "currency": "USD" },
      "net": { "amount": 175000, "currency": "USD" },
      "tax": { "amount": 0, "currency": "USD" },
      "pension": { "amount": 0, "currency": "USD" },
      "payPeriod": {
        "fromDate": "2026-02-01",
        "toDate": "2026-02-28"
      }
    }
  ]
}

Status Flow

created → saved → approved → scheduled → processing → completed
                      ↓
                awaiting funds

Status	Meaning
`created`	Empty payroll shell, no entries yet
`saved`	Entries added, ready for approval
`approved`	Approved, Cadana is collecting funds
`awaiting funds`	Insufficient balance — payroll will proceed once funded
`scheduled`	Funds collected, scheduled for the payroll date
`processing`	Disbursements being sent to workers
`completed`	All disbursements confirmed

For the full lifecycle including webhooks and multi-currency handling, see Payroll Lifecycle.

Webhooks

Subscribe to payroll and transaction events to track progress without polling. Payroll status changes:

JSON

{
  "id": "e13b9e14-c062-42ea-8563-8fc9223b29b5",
  "status": "completed",
  "tenantKey": "cad95193904"
}

Individual transaction events (transaction.initiated, transaction.succeeded, transaction.failed) fire for each worker’s payment. See Webhooks to configure your endpoint and Events for all event types.

Troubleshooting

Issue	Cause	Solution
`401 Unauthorized`	Invalid or missing API key	Check your API key in the Dashboard
`400` on save	Missing required fields	Ensure `payrollDate`, `payPeriod`, and at least one entry with `personId` and `salary` are provided
Stuck in `awaiting funds`	Insufficient business account balance	Fund your business account, then the payroll will proceed automatically
Payroll won’t approve	Entries not saved	Save entries (Step 2) before approving

Next Steps

Payroll Lifecycle

Full status flow, webhooks, and multi-currency handling

Onboard Workers

Set up Person records and payment methods

Webhooks

Real-time notifications for payroll and transactions

Workforce API Reference

Full API documentation

Get Started

Workforce Management

Payroll & Compliance

White-Label UI

Platform Integration

Payments

Wallets

Prerequisites

Step 1: Create a Payroll

Payroll Types

Step 2: Save Entries

Custom Metadata

Custom Fees (Platforms)

Save Errors

Step 3: Approve

Tracking Payroll Status

List All Payrolls

Status Flow

Webhooks

Troubleshooting

Next Steps

Payroll Lifecycle

Onboard Workers

Webhooks

Workforce API Reference

Get Started

Workforce Management

Payroll & Compliance

White-Label UI

Platform Integration

Payments

Wallets

​Prerequisites

​Step 1: Create a Payroll

​Payroll Types

​Step 2: Save Entries

​Custom Metadata

​Custom Fees (Platforms)

​Save Errors

​Step 3: Approve

​Tracking Payroll Status

​List All Payrolls

​Status Flow

​Webhooks

​Troubleshooting

​Next Steps

Payroll Lifecycle

Onboard Workers

Webhooks

Workforce API Reference

Prerequisites

Step 1: Create a Payroll

Payroll Types

Step 2: Save Entries

Custom Metadata

Custom Fees (Platforms)

Save Errors

Step 3: Approve

Tracking Payroll Status

List All Payrolls

Status Flow

Webhooks

Troubleshooting

Next Steps