CITEditor: Created page with "= ERPNext Payroll Proof of Concept (POC) - Step-by-Step Guide = This guide outlines the process to validate ERPNext for your payroll requirements, specifically tailored for a Philippine context (BIR compliance, attendance-based pay, and multi-entity rollout). Reference: [https://docs.frappe.io/hr/payroll-setup Payroll Setup] == Phase 1: The Foundation (Prerequisites) == ''Goal: Prepare the system with the minimum data required to process a dummy transaction.'' === 1..."

2026-02-25T07:21:25Z

Created page with "= ERPNext Payroll Proof of Concept (POC) - Step-by-Step Guide = This guide outlines the process to validate ERPNext for your payroll requirements, specifically tailored for a Philippine context (BIR compliance, attendance-based pay, and multi-entity rollout). Reference: [https://docs.frappe.io/hr/payroll-setup Payroll Setup] == Phase 1: The Foundation (Prerequisites) == ''Goal: Prepare the system with the minimum data required to process a dummy transaction.'' === 1..."

New page

= ERPNext Payroll Proof of Concept (POC) - Step-by-Step Guide =

This guide outlines the process to validate ERPNext for your payroll requirements, specifically tailored for a Philippine context (BIR compliance, attendance-based pay, and multi-entity rollout).

Reference: [https://docs.frappe.io/hr/payroll-setup Payroll Setup]

== Phase 1: The Foundation (Prerequisites) ==

''Goal: Prepare the system with the minimum data required to process a dummy transaction.''

=== 1.1 Accounting Setup (Chart of Accounts) ===

Ensure the following accounts exist in your '''Chart of Accounts''' (Accounting > Chart of Accounts):

* '''Expenses (Profit & Loss):'''
** Salaries and Wages
** Employer's SS Contribution (SSS/PhilHealth/HDMF share)
** ''Provision for Separation/Redundancy (Optional for Forecasting)''
* '''Liabilities (Balance Sheet):'''
** Payroll Payable (Net Pay)
** SS Payable (Employee + Employer share)
** Withholding Tax Payable (BIR)

=== 1.2 Master Data Setup ===

# '''Company:''' Ensure "ESCO" (or your target entity) is set up.
# '''Department:''' Create basic departments (e.g., HR, IT, Operations).
# '''Designation:''' Create basic roles (e.g., Officer, Manager).
# '''Holiday List:''' Create a "Regular Holidays 2025" list.
#* ''Note:'' This is crucial for calculating "Working Days."

== Phase 2: Scenario A - Fixed Salary (No Attendance) ==

''Goal: Generate a Salary Slip and Accounting Entries for a regular employee without worrying about daily attendance tracking.''

=== 2.1 Create Salary Components ===

Go to '''Payroll > Salary Component > New'''.

# '''Basic Pay:''' Type = Earning.
# '''Allowance:''' Type = Earning.
# '''SSS Contribution:''' Type = Deduction.

=== 2.2 Create Salary Structure ===

Go to '''Payroll > Salary Structure > New'''.

* '''Name:''' "Regular - Monthly Fixed"
* '''Company:''' ESCO
* '''Earnings Table:''' Add Basic Pay and Allowance.
* '''Deductions Table:''' Add SSS Contribution.
* '''Mode of Payment:''' Bank Transfer.

=== 2.3 Create Employee ===

Go to '''HR > Employee > New'''.

* '''First Name:''' Juan
* '''Last Name:''' Dela Cruz (Fixed)
* '''Date of Joining:''' 3 months ago.
* '''Status:''' Active.

=== 2.4 Assign Salary Structure ===

Go to '''Payroll > Salary Structure Assignment > New'''.

* '''Employee:''' Juan Dela Cruz (Fixed).
* '''Salary Structure:''' "Regular - Monthly Fixed".
* '''Base Pay:''' Enter the monthly amount (e.g., 25,000).
* '''Condition:''' Leave blank for now.

=== 2.5 Process Payroll (The Workflow) ===

# '''Payroll Entry:''' Go to '''Payroll > Payroll Entry > New'''.
#* Select Payroll Period.
#* Check "Validate Attendance" = '''Unchecked''' (Crucial for this step).
#* Click "Get Employees" -> "Create Salary Slips".
# '''Verify Slips:''' Open the generated Salary Slip. Check if Basic + Allowance - SSS = Net Pay is correct.
# '''Submit:''' Submit the Payroll Entry.
# '''Accrual (Journal Entry):''' Click "Make Bank Entry" or check the Journal Entry created automatically.
#* ''Result:'' Debit Salary Expense, Credit Payroll Payable.

== Phase 3: Scenario B - Attendance-Based & Variable Pay ==

''Goal: Prove the system can handle "No Work, No Pay", Lates, and Absences based on uploaded data.''

=== 3.1 Setup "Daily" Components ===

# '''Salary Component:''' Create "Basic (Daily)".
# '''Salary Structure:''' Create "Rank and File - Attendance Based".
#* '''Formula:''' <code>base * (payment_days / total_working_days)</code> or specific daily rate logic.

=== 3.2 Create Employee & Assignment ===

# '''New Employee:''' "Maria Santos (Attendance)".
# '''Assignment:''' Assign the "Attendance Based" structure.

=== 3.3 Import Attendance Data (The Spreadsheet Test) ===

Instead of manual entry, use the '''Data Import''' tool.

# '''Download Template:''' Go to Data Import > New > Document Type: '''Attendance'''. Download the CSV template.
# '''Fill Data:''' Populate the CSV with:
#* Present days (Status: Present).
#* Absent days (Status: Absent).
#* ''Note:'' Ensure dates match the payroll period you are testing.
# '''Upload:''' Attach and Import the CSV.

=== 3.4 Process Payroll with Validation ===

# '''Payroll Entry:''' Create New.
# '''Settings:''' Check '''"Validate Attendance"'''.
# '''Execution:'''
#* The system will auto-calculate Payment Days (Total days in month - Absents - LWP).
#* Check Maria's Salary Slip. If she was absent 2 days, her Basic Pay should be pro-rated (or deducted, depending on your formula).

== Phase 4: Earnings, Deductions & Tax Compliance (PH Context) ==

''Goal: Achieve the "Complete Salary" requirement, including progressive tax calculation.''

=== 4.1 Income Tax (Progressive/Annualized) ===

* '''Concept:''' Philippine tax is based on ''net taxable annual income''. Monthly deductions are merely "withholdings" (advance payments). As income fluctuates (OT, LWOP, Bonuses), the projected annual tax bracket changes.
* '''Option A (Standard Tax Slab):''' Setup '''Payroll > Income Tax Slab'''. Use the annualized TRAIN law tables.
** ''ERPNext Logic:'' The system typically projects annual income by taking (Current Month Earnings * Remaining Months) + YTD Earnings. It then applies the tax slab to find the annual tax, divides it by months to find the monthly deduction.
* '''Option B (Simplified POC Formula):''' For the POC, you can use a Python formula in the Salary Component to mimic the manual calculation if the projection logic is too complex for the initial test.

=== 4.2 Statutory Deductions (SSS, PhilHealth, HDMF) ===

* '''SSS:''' Create a '''Salary Component Formula''' using the base amount to look up the deduction bracket, or use ERPNext's '''PH Localization''' app if available (which has standard tables).
** ''POC Shortcut:'' For the POC, just use a fixed deduction or a simple % formula to prove the deduction line appears.

=== 4.3 BIR Form 2307 vs. 2316 ===

* '''Important Distinction:'''
** '''BIR 2316:''' This is the Certificate of Compensation Payment. This is generated for '''Regular Employees''' (Phase 2 & 3). ERPNext has a standard report for this or a "Tax Deduction" report that maps to it.
** '''BIR 2307:''' This is for '''Expanded Withholding Tax''' (Creditable). This is typically for '''Contractors/Consultants''' (Job Order), NOT regular employees.
* '''POC Action for 2307:'''
** If you pay consultants via Payroll: You must create a separate Salary Structure (e.g., "Consultant Fees") and a Tax Component (e.g., "EWT 2%").
** ''Recommendation:'' Usually, 2307 is generated via '''Accounts Payable (Purchase Invoice)''' in ERPNext, not Payroll. If you ''must'' do it in Payroll, you will likely need a Custom Print Format to print the data onto the 2307 layout.

=== 4.4 Year-End Annualization (The "Tax Refund/Payable" Scenario) ===

* '''The Logic:''' In December (or separation), you must reconcile:
** (Total Actual Annual Taxable Income × Tax Rate) - (Total Taxes Withheld Jan-Nov) = December Tax Due (or Refund).
* '''POC Simulation Steps:'''
*# '''Simulate Fluctuation:''' Run payroll for Oct & Nov with different amounts (add OT in one, LWOP in another) to create a variation in tax withheld.
*# '''The 13th Month:''' Process 13th Month Pay (ensure the first 90k is set as non-taxable in the component settings).
*# '''The December Run (Annualization):'''
*#* Run the final payroll.
*#* '''Validation:''' Manually calculate the total annual tax due in Excel. Compare it with the ''cumulative'' tax deducted in ERPNext by the end of Dec.
*#* '''Adjustment:''' If the system calculation differs from your manual "Annualization" (due to rounding or specific PH logic nuances), use the '''"Additional Salary"''' tool to insert a specific "Tax Adjustment" component to force the final tax figure to match the penny.

== Phase 5: Advanced Calculations & Roadmap ==

''Goal: Move beyond basic net pay to "Total Cost of Ownership" forecasting and prepare for automated statutory reporting.''

=== 5.1 Severance & Redundancy Forecasting (Total Cost of Employment) ===

Companies often underestimate the liability accrued per year of service. To accurately forecast the '''Total Cost of Ownership (TCO)''' of an employee, we must account for potential redundancy pay mandated by the Philippine Labor Code.

* '''The Law (Redundancy):''' An employee terminated due to redundancy (superfluous position) is entitled to '''at least one (1) month pay for every year of service'''. (Article 283/298 of the Labor Code).
** ''Note:'' This is distinct from Retirement Pay (RA 7641), which is 22.5 days per year. Redundancy is more expensive.
* '''Forecasting Method:'''
** Create a '''Report''' (Script Report) in ERPNext that calculates: Current Monthly Basic * Years of Service.
** This figure represents the "Contingent Liability" if the company decides to downsize or restructure today.
** '''POC Action:''' Demonstrate a custom report or a spreadsheet export from ERPNext Employee Master that computes this column dynamically.

=== 5.2 Roadmap for Automation (Comfac Customization) ===

Before Comfac develops the custom apps/scripts to generate Philippine statutory reports automatically, we must document the '''Manual Pre-Customization Workflow'''.

'''The "Alphalist" (BIR) Roadmap:'''

# '''Current State (Manual):'''
#* Export "Salary Register" from ERPNext to Excel.
#* Manually map columns to the '''BIR Alphalist Data Entry Module''' (Part 1 - Sched 1).
#* '''Pain Point:''' Consolidating data from multiple "Payroll Entries" throughout the year.
# '''Target State (Automated):'''
#* '''Custom Script:''' A button "Generate Alphalist DAT File" in the Payroll Module.
#* '''Logic:''' It aggregates all ''Submitted'' Salary Slips for the fiscal year, groups them by Employee TIN, and formats the output into the specific DAT file structure required by the BIR eSubmission validation tool.

'''Statutory Contributions Roadmap:'''

* '''SSS (R-3 / Collection List):'''
** ''Manual:'' Pivot table of Salary Slips > Deductions > SSS.
** ''Automated:'' Generate the standard SSS text file format for bank upload.
* '''PhilHealth (RF-1) & HDMF (MCRF):'''
** ''Manual:'' Excel export and manual formatting.
** ''Automated:'' XML/Excel export matching the agency's specific template columns.

== Phase 6: Mapping & Documentation ==

''Goal: Record the evidence for stakeholders.''

=== 6.1 Screen Recording List ===

Record these specific clips (1-2 mins each) for the POC presentation:

# '''"The Setup":''' Briefly showing the Employee Master and Salary Structure.
# '''"The Input":''' Showing the Data Import of the Attendance CSV.
# '''"The Process":''' Clicking "Create Salary Slips" and seeing the batch generated.
# '''"The Result":''' Opening a PDF Salary Slip showing Earnings, Deductions, and Net Pay.
# '''"The Accounting":''' Showing the General Ledger entry (Debits/Credits).

=== 6.2 Rollout Plan (Entity Sequence) ===

# '''ESCO (Pilot):''' Run parallel payroll (ERPNext + Excel) for 1 month.
# '''Comfac:''' Copy Salary Structures from ESCO, adjust for specific allowances.
# '''CTOGS/CTONZPH:''' Specialized structures (e.g., project-based pay).

== Checklist for "Complete Salary" ==

* [ ] '''Gross Pay:''' Accurate based on attendance/fixed rate.
* [ ] '''Overtime:''' Added via "Additional Salary" or Timesheets.
* [ ] '''Deductions:''' SSS, PHIC, HDMF visible on slip.
* [ ] '''Tax:''' Withholding tax calculated progressively (Monthly vs Annualized).
* [ ] '''Annualization:''' Year-end tax adjustment (Refund/Payable) verified.
* [ ] '''Severance Forecast:''' Report created to show accrued redundancy liability per employee.
* [ ] '''Net Pay:''' Matches manual Excel computation to the centavo.
* [ ] '''Accounting:''' Journal Entry balances.
* [ ] '''Bank Advice:''' "Bank Remittance" report generated for the bank.

[[Category:ERPNext]]
[[Category:Payroll]]
[[Category:Philippines]]
[[Category:Comfac]]

ERPNEXT Payroll POC 251212 - Revision history