> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cadanapay.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Instant Pay

> Give workers early access to earned wages before their next payroll date

export const ApiExample = ({method = "GET", path, params, body, reference, tenantKey}) => {
  const baseUrl = "https://api.cadanapay.com";
  const query = params ? "?" + Object.entries(params).map(([k, v]) => `${k}=${v}`).join("&") : "";
  const url = `${baseUrl}${path}${query}`;
  const isPlatformPath = (/^\/(v1\/)?platform(\/|$)/).test(path || "");
  const includeTenantKey = tenantKey === undefined ? !isPlatformPath : tenantKey;
  let curl = `curl -X ${method} '${url}' \\\n  -H 'Authorization: Bearer YOUR_API_KEY'`;
  if (includeTenantKey) {
    curl += ` \\\n  -H 'X-MultiTenantKey: YOUR_BUSINESS_TENANT_KEY'`;
  }
  if (body) {
    const formatted = JSON.stringify(body, null, 2);
    curl += ` \\\n  -H 'Content-Type: application/json' \\\n  -d '${formatted}'`;
  }
  return <div>
      <CodeBlock language="bash" filename="bash" wrap>
        {curl}
      </CodeBlock>
      {reference && <div style={{
    marginTop: "-0.5rem",
    marginBottom: "1rem"
  }}>
          <a href={reference} style={{
    fontSize: "0.875rem"
  }}>
            Try it in the playground →
          </a>
        </div>}
    </div>;
};

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.

```mermaid theme={null}
sequenceDiagram
    participant B as Business
    participant P as Platform
    participant C as Cadana
    participant W as Worker

    B->>C: Enable Instant Pay (via account manager)
    P->>C: Configure per-person access (PUT /ipSetting)
    W->>C: Request instant pay (Cadana app)
    C->>W: Disburse earned wages
    C->>P: Webhook: instant-pay.succeeded
```

***

## Prerequisites

<Steps>
  <Step title="API key from Dashboard">
    Get your API key from the [Cadana Dashboard](https://app.cadanapay.com). See [Authentication](/authentication) for details.
  </Step>

  <Step title="Onboarded workers">
    Workers must be onboarded as Persons — you'll use their `personId` to configure settings and view transactions. See [Onboard Workers](/workforce/onboarding-workers).
  </Step>

  <Step title="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.
  </Step>
</Steps>

***

## 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.

<ApiExample method="PUT" path="/v1/persons/8ef9a712-cdae-4110-b1ea-9ba95abbee6e/ipSetting" body={{ accessPercentage: 50 }} reference="/api-reference/workforce/instant-pay/update-instant-pay-setting" />

Returns `204` on success.

### Get a Person's Setting

<ApiExample method="GET" path="/v1/persons/8ef9a712-cdae-4110-b1ea-9ba95abbee6e/ipSetting" reference="/api-reference/workforce/instant-pay/get-instant-pay-setting" />

**Response:**

```json theme={null}
{
  "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}`](/api-reference/workforce/businesses/get) 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:**

```json theme={null}
{
  "instantPaySettings": {
    "accessPercentage": 30,
    "numDaysBeforePayroll": 4,
    "requiresApproval": false,
    "contractorAccess": true
  }
}
```

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

***

## Track Transactions

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

<ApiExample method="GET" path="/v1/persons/8ef9a712-cdae-4110-b1ea-9ba95abbee6e/instantPays" reference="/api-reference/workforce/instant-pay/get-instant-pay-transactions" />

**Response:**

```json theme={null}
{
  "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.

<ApiExample method="GET" path="/v1/persons/8ef9a712-cdae-4110-b1ea-9ba95abbee6e/instantPays" params={{ isUnpaid: true }} reference="/api-reference/workforce/instant-pay/get-instant-pay-transactions" />

### Transaction Statuses

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

<Note>
  Amounts are in the **lowest denomination** of the currency. For USD, `50000` = \$500.00.
</Note>

***

## Webhook Event

### instant-pay.succeeded

Fires when an instant pay withdrawal is successfully disbursed to a worker. Subscribe via the [Dashboard](https://app.cadanapay.com) or see [Webhooks](/reference/webhooks) for setup.

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

See [Events](/reference/events#instant-pay) for all event types and payload details.

***

## Next Steps

<CardGroup cols={2}>
  <Card title="Onboard Workers" icon="user-plus" href="/workforce/onboarding-workers">
    Create Person records before configuring instant pay
  </Card>

  <Card title="Pay Workers via Payroll" icon="money-check-dollar" href="/workforce/pay-workers-via-payroll">
    Run payroll to reconcile instant pay advances
  </Card>

  <Card title="Webhooks" icon="bell" href="/reference/webhooks">
    Set up real-time notifications for instant pay events
  </Card>

  <Card title="Events" icon="list" href="/reference/events">
    Full list of webhook event types and payloads
  </Card>
</CardGroup>