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

# Payroll Processing

### Pay Periods

Pay periods are generated automatically based on the pay schedule configured for W2 and 1099 employees. To retrieve pay periods and their statuses you may use the following:

1. [getPayPeriod](https://developer.rollfi.xyz/api-reference/reports/getPayPeriod) - Retrieves the next pay period that should be processed for a company. This may be an overdue pay period or the upcoming pay period.
2. [getUnprocessedPayPeriod](https://developer.rollfi.xyz/api-reference/reports/getUnProcessedPayPeriod) - Retrieve the latest pay period that has not yet been processed for a company. Again, this may be an overdue pay period or the upcoming pay period.
3. [getProcessedPayperiodsDetails](https://developer.rollfi.xyz/api-reference/reports/getProcessedPayperiodsDetails) - Retrieve detailed information about processed pay periods.

## A pay period may also be created through a Supplemental Payroll.

### Pay Period Status

Each pay period has a `PayPeriodStatus` that indicates its current state in the payroll process. This dictates the actions that can be taken and helps in tracking the progress of payroll processing.

#### 🔹 new

* The pay period has been created but not yet submitted to Rollfi.
* This is the initial status where edits and changes can still be made.

#### 🔹 submitted

* The pay period has been submitted to Rollfi early and is not yet processing.
* Edits can be made up to **12:00 PM EST (noon)** on the `deadlineToRunPayroll`.
* Choosing to edit will move the payroll to **cancelled** status where it can be reinitiated.

#### 🔹 cancelled

* The pay period had previously been submitted but has been cancelled to allow edits to be made.
* If the edits are submitted before **12:00 PM EST (noon)** on the `deadlineToRunPayroll` the payroll moves to **submitted**.
* If the edits are made after **12:00 PM EST (noon)** on the `deadlineToRunPayroll` the payroll moves directly to **inProcess**.

#### 🔹 inProcess

* Payroll has been submitted and is processing.
* If the pay period is overdue, the **submitted** state is skipped and the payroll goes straight here.
* At this time edits cannot be made.

#### 🔹 processed

* The pay period is complete.
* Funds have been submitted for ACH disbursement.

#### 🔹 failed

* The pay period did not complete due to an error in processing.
* The payroll can be edited and resubmitted once the issues that caused the failure are addressed.

#### 🔹 returned

* Funds were returned after processing.
* This may occur due to issues with employee bank accounts or other reasons.

#### 🔹 skipped

* The pay period has been skipped in the system.
* Payroll can be skipped at verious stages of the process.
* These may have been administered outside of the normal payroll process.

***

### Payroll Status Flow

<div style={{ display:"grid",gap:"0.5rem",maxWidth:"600px" }}>
  <div style={{ display:"flex",alignItems:"center",gap:"0.75rem" }}>
    <svg width="14" height="14">
      <rect width="14" height="14" fill="#FACC14" />
    </svg>

    <strong>Editable</strong>

    <div style={{ display:"flex",gap:"0.5rem" }}>
      <code>Editable</code>
    </div>
  </div>

  <div style={{ display:"flex",alignItems:"center",gap:"0.75rem" }}>
    <svg width="14" height="14">
      <rect width="14" height="14" fill="#FF927C" />
    </svg>

    <strong>Processing</strong>

    <div style={{ display:"flex",gap:"0.5rem" }}>
      <code>Non-editable (processing)</code>
    </div>
  </div>

  <div style={{ display:"flex",alignItems:"center",gap:"0.75rem" }}>
    <svg width="14" height="14">
      <rect width="14" height="14" fill="#60A5FA" />
    </svg>

    <strong>Final</strong>

    <div style={{ display:"flex",gap:"0.5rem" }}>
      <code>Final</code>
    </div>
  </div>
</div>

<br />

```mermaid theme={null}
%%{
  init: {
    "theme": "base",
    "themeVariables": {
      "fontFamily": "Inter, system-ui, -apple-system, Segoe UI, Roboto, Helvetica, Arial, sans-serif",
      "lineColor": "#94A3B8",
      "textColor": "#E5E7EB",
      "fontSize": "12px",
      edgeLabelFontSize: "8px"
    }
  }
}%%

flowchart TD
  %% Nodes
  A((New))
  H[Skipped]
  B[Submitted]
  C[In Process]
  D[Cancelled]
  E[Processed]
  I[Failed]
  J[Returned]

  %% Flows
  A --> H
  A --> |Payroll submitted on time| B
  A --> |Submitted late| C
  B --> |12:00 PM EST| C


  C --> |System failure| I
  C --> |2-day ACH| E
  E -->|"ACH Issue"| J

  B --> |make edits| D
  D --> |submit before 12:00 PM EST| B

  D -->|submit after 12:00 PM EST </br> deadline| C

  I --> |fix issues| C
  J --> |fix issues| C


  %% Updated Styles
  classDef editable  fill:#FACC14,color:#000000,stroke:#3E3418,stroke-width:6px;   %% Golden Yellow interior, Dark Brown outline
  classDef processing fill:#FF927C,color:#000000,stroke:#FF4216,stroke-width:6px;  %% Light Red interior, Bold Red outline
  classDef final     fill:#60A5FA,color:#FFFFFF,stroke:#3064E3,stroke-width:6px;   %% Light Blue interior, Bold Blue outline



  %% Subtle edge color
  linkStyle default stroke:#94A3B8,stroke-width:1.25;

  %% Apply categories
  class A,D,I,J editable;
  class B,C processing;
  class E,H final;
```

***

### Submission Deadlines

⚠️ If your payroll is self-initiated, it is essential to carefully monitor and meet all submission deadlines.

🏛️ To ensure employees are paid on time (2-day ACH), payroll must be submitted and any changes made by 12:00 PM EST (noon) on the `deadlineToRunPayroll` provided by the above endpoints.

📥 Rollfi can provide automated emails and notifications—at no additional cost—to remind admins of upcoming deadlines and immediately alert them to any payroll issues. This is enabled by default for whitelabel customers and can be enabled/disabled for API customers upon request.

***

### Webhooks

📝 All payments have corresponding webhooks that notify your system of status changes. See [Webhooks](https://developer.rollfi.xyz/docs/Webhooks) for setup and management.

***