Instant Pay

Instant Pay (also known as Earned Wage Access) lets workers withdraw a portion of their earned wages before the next scheduled payroll date. Workers request instant pay through the Cadana app — the developer API lets you configure per-person access limits and track transactions.

Prerequisites

API key from Dashboard

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

Onboarded workers

Workers must be onboarded as Persons — you’ll use their personId to configure settings and view transactions. See Onboard Workers.

Instant Pay enabled for your business

Contact your Cadana account manager to enable Instant Pay. This is a business-level feature that must be activated before workers can use it.

Configure Per-Person Access

By default, workers inherit the business-level accessPercentage. Use the per-person setting to override this for individual workers — for example, to grant a higher limit to a long-tenured employee or restrict access for a new hire.

Update a Person’s Setting

Set the percentage of earned wages a person can access via instant pay. The value must be between 0 and 100. Returns 204 on success.

Get a Person’s Setting

Response:

{
  "accessPercentage": 50
}

Business-Level Settings

When Instant Pay is enabled, the business object includes an instantPaySettings field with the defaults configured by your Cadana account manager. These are visible via GET /v1/businesses/{businessId} but can only be changed by Cadana.

Field	Type	Description
`accessPercentage`	integer	Default percentage of earned wages workers can access (0–100)
`numDaysBeforePayroll`	integer	Number of days before the payroll date when instant pay becomes unavailable
`requiresApproval`	boolean	Whether instant pay requests require business approval before disbursement
`contractorAccess`	boolean	Whether contractors (in addition to employees) can use instant pay

Example on the business object:

{
  "instantPaySettings": {
    "accessPercentage": 30,
    "numDaysBeforePayroll": 4,
    "requiresApproval": false,
    "contractorAccess": true
  }
}

Per-person settings (via PUT /v1/persons/{personId}/ipSetting) override the business-level accessPercentage for that individual worker.

Track Transactions

Retrieve instant pay transactions for a specific person. Each transaction represents a single instant pay withdrawal. Response:

{
  "data": [
    {
      "id": "d52e4a13-7b6f-4c8d-a9e1-2f3b5c7d8e9a",
      "amount": {
        "currency": "USD",
        "amount": 50000
      },
      "status": "completed",
      "createdTimestamp": 1693782273
    },
    {
      "id": "f74a6c35-9d8e-4b0f-c1a2-4e5f7a8b9c0d",
      "amount": {
        "currency": "USD",
        "amount": 25000
      },
      "status": "processing",
      "createdTimestamp": 1693868673
    }
  ]
}

Filter by Unpaid

Use the isUnpaid query parameter to only return transactions that haven’t been reconciled against a payroll yet.

Transaction Statuses

Status	Meaning
`completed`	Funds have been disbursed to the worker
`processing`	Withdrawal is in progress
`failed`	Withdrawal failed — the worker can retry

Amounts are in the lowest denomination of the currency. For USD, 50000 = $500.00.

Webhook Event

instant-pay.succeeded

Fires when an instant pay withdrawal is successfully disbursed to a worker. Subscribe via the Dashboard or see Webhooks for setup.

JSON

{
  "id": "c5d6e7f8-a901-2345-cdef-567890123456",
  "personId": "e13b9e14-c062-42ea-8563-8fc9223b29b5",
  "amount": {
    "currency": "USD",
    "amount": 50000
  },
  "tenantKey": "cad95193904"
}

See Events for all event types and payload details.

Next Steps

Onboard Workers

Create Person records before configuring instant pay

Pay Workers via Payroll

Run payroll to reconcile instant pay advances

Webhooks

Set up real-time notifications for instant pay events

Events

Full list of webhook event types and payloads

Get Started

Workforce Management

Payroll & Compliance

White-Label UI

Platform Integration

Payments

Wallets

Prerequisites

Configure Per-Person Access

Update a Person’s Setting

Get a Person’s Setting

Business-Level Settings

Track Transactions

Filter by Unpaid

Transaction Statuses

Webhook Event

instant-pay.succeeded

Next Steps

Onboard Workers

Pay Workers via Payroll

Webhooks

Events

​Prerequisites

​Configure Per-Person Access

​Update a Person’s Setting

​Get a Person’s Setting

​Business-Level Settings

​Track Transactions

​Filter by Unpaid

​Transaction Statuses

​Webhook Event

​instant-pay.succeeded

​Next Steps

Onboard Workers

Pay Workers via Payroll

Webhooks

Events

Prerequisites

Configure Per-Person Access

Update a Person’s Setting

Get a Person’s Setting

Business-Level Settings

Track Transactions

Filter by Unpaid

Transaction Statuses

Webhook Event

instant-pay.succeeded

Next Steps