Payroll

Overview#

The payroll system supports multi-country payroll processing with a plugin-based calculation architecture. The ERP backend is country-agnostic -- it stores employee data, receives pre-calculated results, and handles GL posting and payments. Country-specific tax calculation logic lives in separate plugins that can be added without changing the core system.

Key Features#

• Effective-dated compensation records
• Plugin-based country-specific tax calculations
• Pre-tax and post-tax deductions with limits
• Multi-step processing (draft, calculated, approved, paid)
• Risk-based approval workflows
• Employee-direct payments via bank accounts
• Dual payee payment batches (vendor lines for taxes + employee lines for net pay)

Supported Countries#

• Estonia -- Income tax (22%), social tax (33%), unemployment, funded pension
• Additional countries can be added by creating new plugins -- no backend code changes required

---

Plugin-Based Architecture#

The backend provides data and receives results. Plugins handle all country-specific logic:

ERP Backend (Data)        Plugin (Calculations)        ERP Backend (Results)

1. Read employee data  -->  2. Calculate payroll    -->  3. Submit results
   - compensation             using country-specific      via submit_calculation
   - tax settings              plugin formulas
   - deductions                                         4. Store detail records
   - tax jurisdictions                                  5. Generate GL lines
                                                        6. Create payment batch

This design means:

• Rate changes require no code changes -- update tax jurisdiction rates in the database
• New countries require no backend changes -- create a new plugin with the country's formulas
• All intelligence stays in plugins -- the backend is a dumb data store and validator

---

Three-Table Data Architecture#

Plugins read three tables at calculation time:

---

Employee Data#

Compensation Records#

Compensation records track salary and wage information with effective dates:

Tax Settings#

Tax settings are country-agnostic with per-country specifics:

Common fields:

• Country and state/locality codes
• Tax identification (SSN, personal ID, etc.)
• Filing status and allowances
• Additional withholding amounts

US-specific:

• W-4 version and steps
• State code and state allowances

Estonia-specific:

• Pension tier (2%, 4%, or 6% for II pillar)
• Basic exemption application (700 EUR/month)
• Employment register ID

Employee Deductions#

Deductions support multiple calculation methods and tax treatments:

Each deduction specifies:

• Calculation method -- Fixed amount, percentage of gross, or per-hour rate
• Annual limits -- Maximum deduction per year (e.g., 401(k) contribution limit)
• Employer match -- Match percentage and limit
• Tax treatment -- Pre-tax or post-tax, which taxes it reduces

---

Payroll Processing#

Payroll Periods#

Pay periods define the time range and pay date for each payroll cycle:

Payroll Run Lifecycle#

Draft --> Calculated --> Approved --> Paid
                     --> Voided (if errors found)

Processing Steps#

1. Create payroll run -- Select entity, period, and run type (regular, correction, bonus, final)
2. Plugin calculates -- Plugin reads employee data, applies country-specific formulas, submits results
3. Review results -- Review per-employee breakdown: gross pay, taxes, deductions, net pay
4. Approve -- Approval required (red lane workflow due to financial impact)
5. Execute payment -- Creates payment batch with dual payee lines

Per-Employee Calculation Results#

For each employee, the calculation produces:

Earnings:

• Gross pay, regular pay, overtime pay
• Bonus pay, commission pay, other earnings

Employee Taxes Withheld:

• Federal/state/local income tax
• Social security and Medicare (US)
• Unemployment insurance (employee portion)
• Pension contributions

Employer Taxes:

• Social tax (e.g., Estonia 33%)
• Employer social security and Medicare (US)
• Federal and state unemployment (US)

Deductions:

• Pre-tax deductions (401(k), HSA)
• Post-tax deductions (Roth 401(k), garnishments)

Net Pay:

• Gross pay minus employee taxes minus deductions

Vendor-Linked Detail Lines#

Each tax and deduction amount is linked to a specific vendor (e.g., tax authority, insurance provider) and GL account. This enables:

• Accurate AP tracking for tax remittances
• Automated payment batch creation with vendor lines
• Clear audit trail from payroll calculation to payment

---

Payment Integration#

Payroll runs create dual payee payment batches:

Employee payments use the employee's configured bank account with split deposit support. Tax and deduction payments go to the mapped vendor for each line type.

---

Vendor Configuration#

Each tax and deduction type is mapped to a vendor and GL accounts per legal entity:

This mapping is configured per entity, allowing different vendors and accounts for different countries and jurisdictions.

---

Workflow Summary#

---

Estonian Payroll Example#

For an Estonian employee earning 3,000 EUR/month with 2% II pillar pension and basic exemption applied:

---

Best Practices#

1. Set up tax settings before running payroll -- Every employee must have tax settings with the correct country code
2. Keep tax jurisdiction rates current -- Update when rates change (yearly for most countries)
3. Map vendors before first run -- Ensure all tax and deduction types have vendor mappings
4. Review before approving -- Check per-employee breakdowns, especially for new employees
5. Use correction runs for errors -- Never manually adjust; create a correction run instead
6. Close periods after completion -- Prevents accidental re-runs for the same period