💵 Submit Payroll (POST /payroll)

Submitting payroll through FlexPay is the critical moment when all the preparation — adding employees, verifying payment methods, selecting pay dates, and assigning compensation — comes together into a finalized pay cycle. This API endpoint (POST /payroll) is where your organization formally instructs FlexPay to calculate pay, validate funds, and begin processing disbursements to your workforce. Each submission includes one or more employees, each with their gross pay, hours worked, and optional adjustments like bonuses and deductions. A successful call kicks off internal workflows such as validation, bank account checks, compliance checks, fund routing, and paystub generation. Once payroll is submitted, the record becomes immutable, meaning that any changes to pay amounts or employee details must be handled through off-cycle corrections or retro pay in future runs. It is therefore vital that all included data is accurate, complete, and reflects the final intent for that pay period.

FlexPay assumes that payroll is submitted after key preparatory steps: employees have been created via the POST /employees endpoint, payment info has been securely stored (via manual entry or API call), and that all bonus or deduction rules have been calculated and handled by your backend or frontend system. While FlexPay does not compute hourly wages or tax withholdings for you directly in this version, it does enforce required fields and logical validations to help prevent critical errors. A common mistake is to include negative values for deductions or leave a field like hours_worked blank — both of which will cause errors during submission. You must also ensure your pay period dates follow an ISO 8601 format and are logically sound (e.g., pay_period_end must be after pay_period_start). Additionally, all employee IDs must be valid, current, and belong to your organization.

Once submitted, payroll is locked into FlexPay’s backend pipeline. It will first verify employee eligibility and bank setup. Then it calculates net pay based on your provided figures and prepares disbursement files to send to the appropriate banking institutions. If all conditions are met, a confirmation webhook (if configured) will be sent to your server so you can update internal records, show confirmation messages, or begin downstream processes like paystub display or ledger reconciliation. Each payroll submission is logged and available via the API for historical lookup, and paystubs become available via the GET /paystubs endpoint.

---

🔧 Endpoint Overview

bashCopyEditPOST /payroll

Use this endpoint to submit payroll for a group of employees for a defined pay period and pay date. This submission should include all employees being paid during that window — partial submissions may be supported in future versions.

---

🖼️ Annotated Request Example

pgsqlCopyEditPOST /payroll
Content-Type: application/json
Authorization: Bearer {your_token}

jsonCopyEdit{
  "pay_period_start": "2025-05-01",
  "pay_period_end": "2025-05-15",
  "pay_date": "2025-05-20",
  "employees": [
    {
      "employee_id": "emp_123",
      "gross_pay": 2400.00,
      "hours_worked": 80,
      "bonuses": 200.00,
      "deductions": 50.00,
      "notes": "Biweekly salary"
    },
    {
      "employee_id": "emp_456",
      "gross_pay": 1800.00,
      "hours_worked": 75,
      "bonuses": 0,
      "deductions": 0,
      "notes": "Part-time contractor"
    }
  ]
}

🔍 Figure 1: A Json version of the standard two-employee payroll submission, complete with earnings adjustments and notes.

Figure 1. A Standard Two Employee Payroll Submit in FlexPay

✅ Requirements Checklist

Before calling this endpoint, confirm the following:

• ✅ Every employee_id included is valid and matches an employee created via POST /employees.

• ✅ Each employee has an active bank account on file (see Can't Add Bank Info if issues arise).

• ✅ All monetary fields (like gross_pay, bonuses, and deductions) are non-negative decimals.

• ✅ Dates are formatted in YYYY-MM-DD ISO format.

• ✅ You’ve reviewed all pay values and confirmed them as final — submitted payroll cannot be edited.

• ✅ You’ve optionally set up webhooks to receive payroll status updates.

---

⚠️ Common Errors and Fixes

Error	What It Means	How to Resolve
Missing bank account info	Employee can’t be paid due to lack of ACH routing info	Add valid banking details to employee profile
Invalid date range	Start or end date is blank, reversed, or malformed	Ensure dates use YYYY-MM-DD and logical order
Negative pay	One or more values reduce net pay below $0	Adjust deductions or increase base pay
Employee not found	Provided ID does not match a current employee	Double-check the employee was created and active
Duplicate payroll window	You've already submitted payroll for these dates	Either cancel previous (if in test) or adjust run

⚠️ Tip: Try using your staging/sandbox environment for test submissions before going live.

🧾 Summary

Submitting payroll via the POST /payroll The endpoint is the most important step in your FlexPay integration. It signifies that you're ready to send real money to real people — and that all prior setup steps have been verified. From a technical perspective, this endpoint receives a structured payload of employees and calculates pay totals using your own compensation logic. FlexPay enforces basic validation (e.g., non-negative pay, valid employees, proper date ranges) but gives you the freedom to define pay logic, bonus structures, and deduction rules on your own terms. Once received, payroll entries are locked and become part of your company’s official payroll history. This improves auditability, reporting, and downstream features like tax form generation.

While submitting payroll is relatively simple in terms of mechanics — just one endpoint, one JSON payload — it’s essential to ensure everything in that payload is double-checked and final. Your app should ideally include confirmation dialogs or review pages before calling this API. If you encounter issues, your first line of defense is to inspect the error messages returned by FlexPay and refer back to this documentation. If you’ve configured webhooks, you’ll get near-instant feedback once your payroll begins processing, succeeds, or fails. From here, you’ll want to retrieve each employee’s finalized paystub, which includes a breakdown of earnings, deductions, net pay, and payment confirmation — all accessible via the GET /paystubs endpoint.

---

⏭️ What’s Next?

You’ve now submitted your first payroll! Great work.

Next, we’ll explore how to:

• 🧾 Retrieve Paystub Data — Learn how to access finalized earnings and net pay details for each employee.

• 📥 Configure Webhooks — Automatically receive status updates when payroll is approved, processed, or rejected.

• 📘 Browse Sample JSON Responses — Explore real-world examples of valid and invalid requests and responses.

Let’s continue by diving into Retrieving Paystub Data — the next key step in providing transparency and auditability for your team and your employees.