Skip to main content
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

1

API key from Dashboard

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

Onboarded workers

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

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.
bash
curl -X PUT 'https://api.cadanapay.com/v1/persons/8ef9a712-cdae-4110-b1ea-9ba95abbee6e/ipSetting' \
  -H 'Authorization: Bearer YOUR_API_KEY'
Returns 204 on success.

​
Get a Person’s Setting

bash
curl -X GET 'https://api.cadanapay.com/v1/persons/8ef9a712-cdae-4110-b1ea-9ba95abbee6e/ipSetting' \
  -H 'Authorization: Bearer YOUR_API_KEY'
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.
FieldTypeDescription
accessPercentageintegerDefault percentage of earned wages workers can access (0–100)
numDaysBeforePayrollintegerNumber of days before the payroll date when instant pay becomes unavailable
requiresApprovalbooleanWhether instant pay requests require business approval before disbursement
contractorAccessbooleanWhether 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.
bash
curl -X GET 'https://api.cadanapay.com/v1/persons/8ef9a712-cdae-4110-b1ea-9ba95abbee6e/instantPays' \
  -H 'Authorization: Bearer YOUR_API_KEY'
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.
bash
curl -X GET 'https://api.cadanapay.com/v1/persons/8ef9a712-cdae-4110-b1ea-9ba95abbee6e/instantPays' \
  -H 'Authorization: Bearer YOUR_API_KEY'

​
Transaction Statuses

StatusMeaning
completedFunds have been disbursed to the worker
processingWithdrawal is in progress
failedWithdrawal 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