Payroll Processing

​

Pay Periods

1. 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 - 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 - Retrieve detailed information about processed pay periods.

​

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

​

Pay Period Status

​

🔹 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

​

Async Payroll Imports

• Rollfi still validates the request up front. Validation errors are returned immediately in the API response.
• If validation succeeds, the import work is queued and the endpoint returns a Pending response instead of waiting for every employee mutation to finish.
• While the import is running, getPayPeriodDetails returns a 400 error instead of returning stale payroll data.
• The error message is: Payroll data import is in progress for this pay period. Please try again shortly.
• Once the import completes, Rollfi sends the payperiod.payperiodstatus.update webhook.
• That .update does not introduce a new public completion status. It restores the pay period to the same visible status you observed before the import started (for example, new or cancelled), which signals that import processing has completed.
• When some employee-level mutations fail during async processing, the completion webhook may include a top-level error object with failure details.

​

Import behavior:

• Both APIs return immediate validation errors when the request is invalid.
• Both APIs return Pending when validation succeeds and processing is queued.
• Both APIs block stale reads via getPayPeriodDetails returning 400 while import processing is active.
• Both APIs use the same payperiod.payperiodstatus.update completion signal and the same optional top-level error summary on partial failures.

​

Example async import:

{
  "importRegularPayrollLData": {
    "status": "Pending",
    "message": "Payroll data validated successfully. Import is in progress. The payperiod.payperiodstatus.update webhook will be sent once the process is complete."
  }
}

{
  "trigger": {
    "eventId": "f1d8f4a9-8b6a-4de4-a07d-0f7c4f17b0e2",
    "eventType": "payperiod.payperiodstatus.update",
    "eventTimeStamp": "07/20/2026 14:37:11"
  },
  "payload": [
    // ... [PayPeriod payload omitted] ...
  ],
  "error": {
    "code": 400,
    "message": "Payroll changes not processed for 2 user(s) due to negative net pay",
    "userIds": [
      "A9275709-E4E0-476F-AE77-BD85F7BDEECD",
      "96069AD6-C3EB-476B-BD3E-E334270EEFA4"
    ]
  }
}

1. Call importRegularPayrollData or importDifferentialPayrollData.
2. If the response returns a validation error, fix the payload and retry.
3. If the response returns Pending, treat the import as accepted but not yet complete.
4. If you call getPayPeriodDetails before the import finishes, expect a 400 response rather than stale data.
5. Wait for the payperiod.payperiodstatus.update webhook.
6. On completion webhook receipt, re-fetch the pay period or payroll details.
7. If the webhook includes a top-level error, treat the import as completed with partial failures and surface the failed userIds for remediation.

​

Submission Deadlines

​

Webhooks