Payroll Admin
Overview
The Payroll Admin applet is where you configure Malaysian payroll for a company, assign employees to pay groups with salaries and bank details, then run each month’s pay run from draft through calculate, approve, finalize, bank-file generation, and Post GL. It also generates official statutory TXT files (CP39 / e-Data PCB, EPF Form A, SOCSO+EIS) and payroll summary reports for a selected pay run.
Where it fits
| Direction | Applet | Why |
|---|---|---|
| Upstream | Organisation | Companies you pay under |
| Upstream | Employee Maintenance | Employee identity, employment status, bank/payment config |
| Upstream | Chart of Account | GL codes used by GL Mapping and Post GL |
| Adjacent | Claim / Claim Cycle | Salary-payment claims can feed into payroll review |
| Downstream | Bank portal / KWSP / PERKESO / LHDN | Bank files and statutory TXT you download and upload outside BigLedger |
Main menu
| Menu | What it is |
|---|---|
| Pay Runs | Create and open pay runs; workspace for Calculate → Approve → Finalize → Bank file → Post GL |
| Employees | Payroll roster — link an employee to a company, pay group, salary, bank, statutory flags |
| Pay Groups | Groups of employees who share frequency / calendar / structure |
| Reports | Statutory TXT + payroll summary / register / bank payment summary for a pay run |
Settings (gear)
Payroll Configuration
| Setting | Purpose |
|---|---|
| Company Setup | Per-company employer numbers: EPF, SOCSO, EIS, PCB (E), optional HRDF, PCB category defaults |
| Pay Calendar | Cutoff and payment-day rules (e.g. salary cutoff day 25, payment day 28, frequency MONTHLY) |
| Pay Period | Concrete date ranges for a calendar. A pay run attaches to a period, so a month with no period cannot be run. The period code is locked once saved — it is the one field you cannot correct later, so decide the naming before the first period |
| Salary Structure | Template of earnings and deduction components. It is attached to a pay group or to an individual employee; changing it changes what the next Calculate produces, not what a finalised run already produced. Defaults to MONTHLY, MYR, country MY |
| Allowance Types | Definitions of what you add on top of salary. Every applicability flag starts ticked — taxable, EPF, SOCSO, EIS and PCB — so a new allowance contributes to all four statutory deductions unless you untick them. A non-contributory allowance created and saved without changing anything is the commonest reason a first Calculate comes out too high |
| Deduction Types | Definitions of what you take off. Recurring starts ticked and Pre-tax starts unticked, so a deduction you meant to apply once repeats every month, and one you meant to shelter from tax is taxed. Both are per-definition, not per-employee |
| Statutory Rates | Country MY rate headers (EPF / SOCSO / EIS / PCB) with default tier % and PCB annual threshold |
| GL Mapping | Map payroll components to chart-of-account codes (expense, net-pay liability, statutory liability). One Default mapping per company |
System Configuration
| Setting | Purpose |
|---|---|
| Application Settings (Field Configuration) | Show/hide listing columns via HIDE_* applet settings |
| Default Selection | Tenant defaults: default company, pay group, currency |
Screens in detail
Company Setup
Settings → Company Setup
Create one setup row per paying company. Required employer identifiers for Malaysian filings:
- EPF Employer No
- SOCSO Employer Code
- EIS Employer Code
- PCB Employer No (E)
- Optional HRDF Applicable + HRDF Employer No
- PCB category / EA form defaults used when generating statutory files
These values are stamped onto statutory report payloads so the TXT matches what KWSP / PERKESO / LHDN expect for that company.
Pay Calendar and Pay Period
Settings → Pay Calendar then Pay Period
- Create a calendar for the company (
MONTHLYfrequency is the Phase-1 path). - Create pay periods under that calendar with Period Start, Period End, and Payment Date.
- Keep period status
OPENuntil you are ready to close the month operationally.
Pay runs are linked to a pay period so payment date and period boundaries stay consistent.
Salary Structure, Allowances, Deductions
Define the earning and deduction catalogue the company uses, then point the Pay Group (and/or employee salary) at the structure you need. Allowance / deduction types carry flags such as taxable, EPF/SOCSO/EIS/PCB applicable, pre-tax, and recurring — Calculate uses those flags when building payslip lines.
Statutory Rates
Settings → Statutory Rates
Create one header per statutory type you need (EPF, SOCSO, EIS, PCB) for country MY. The create form stores:
- Contribution basis (default
GROSS) - Employer / employee contributes flags
- Optional salary ceiling
- Effective date
- Default tier employee % and employer % (virtual fields saved as rate lines)
- For PCB: annual threshold (default 34000 on the form)
GL Mapping
Settings → GL Mapping
Each mapping belongs to one company and maps three Chart of Account picks:
| Component | Typical use |
|---|---|
| Payroll expense | Debit side of the payroll journal |
| Net pay liability | Credit for net salary payable |
| Statutory liability | Credit for statutory payables |
Tick Default Mapping (or use the listing Default checkbox) so Post GL knows which mapping to use. Only one default is allowed per company — checking a new default clears the previous one.
Listing columns show company name (from the backend listing JOIN), the default tick, and the GL code/name for each component.
Employees (payroll roster)
Employees → Add / Edit
Assign payroll facts that the employee master alone does not carry for the run:
- Employee (from Employee Maintenance)
- Company
- Pay group
- Employment type (
FULL_TIME/PART_TIME/FREELANCER) - Salary basis and basic amount
- Frequency / currency
- Payment method and bank account link
- Statutory membership flags (EPF / SOCSO / EIS / PCB as applicable)
- Optional On Hold to exclude from payroll until cleared
- Effective date
Employees on hold can still appear in a calculated run as excluded, depending on how you manage the workspace Exclude checkbox.
Pay Groups
Pay Groups (main menu) or settings pay-group master
Group employees who share company, frequency, calendar, and optionally a salary structure. Create the pay run against a pay group so Calculate pulls the right roster.
Pay Runs workspace
Pay Runs → open a run
Workflow statuses the UI advances through:
| Status | Primary action |
|---|---|
DRAFT | Calculate — build employee lines and amounts |
CALCULATED | Review, Exclude employees if needed, edit leave/claim/deduction inputs, then Approve |
APPROVED | Finalize — lock the run |
FINALIZED | Pick bank format → Generate Bank File |
| Bank file ready | Download file → Post GL |
Supported bank format codes in the workspace (do not invent others):
MAYBANK_M2E_TXT— Maybank M2U Biz / M2E fixed-width TXT- Additional formats exposed by the same option list in the applet (searchable dropdown)
After Calculate, you can open a Payslip for an employee line when available. Recalculate is only allowed while the run is still in draft/calculated territory — the UI blocks recalculate after approve/finalize.
Reports
Reports
- Select a pay run.
- Run a statutory or payroll report.
- Result opens in a dialog with row preview and TXT / base64 download when the backend returns a file.
| Report key | Label | Notes |
|---|---|---|
cp39 | CP39 / e-Data PCB | LHDN MTD TXT for e-PCB Plus |
epf | EPF Form A | KWSP Form A TXT for i-Akaun |
socso | SOCSO + EIS | PERKESO Assist combined TXT |
eis | EIS / SIP | EIS-focused file |
ea / e | Form EA / Form E | Draft / Phase-2 annual packs — monthly summary only |
summary | Payroll Summary | Totals for the run |
register | Payroll Register | Line-level register |
bank | Bank Payment Summary | Bank payment view |
variance | Variance | Draft |
Configuration checklist (first company)
Use this order once per company. Full narrative with the GadgetSphere example: Configure and run monthly payroll.
- Company exists in Organisation; chart of accounts + payroll expense / liability codes exist.
- Employees exist in Employee Maintenance with bank payment config.
- Company Setup — employer numbers.
- Statutory Rates — EPF / SOCSO / EIS / PCB headers + tiers.
- Pay Calendar → Pay Period for the month.
- Salary Structure / allowance / deduction types as needed.
- Pay Group linked to calendar (and structure).
- Employees roster — salary + pay group + bank + statutory flags.
- GL Mapping — three COA codes, tick Default.
- Default Selection — optional default company / pay group / currency.
- Create Pay Run → Calculate → Approve → Finalize → Bank file → Post GL.
- Reports — generate statutory TXT and keep the download pack.
Permissions and install
Access is by installing the applet for the login (same pattern as other Wavelet applets). There is no separate client-side permission matrix documented in the applet menu model beyond standard tenant API permissions enforced by the payroll backend endpoints.
Common failure modes
| Symptom | Likely cause | Fix |
|---|---|---|
Create GL mapping fails on effective_date / debit_credit | Backend older than DCO defaults | Upgrade API, or ensure FE sends defaults |
| Company column shows GUID | Listing JOIN not deployed | Deploy GL mapping listing enrichment; refresh |
| Multiple defaults for one company | Older data | Use listing Default checkbox — keeps one default |
| Calculate race / GUID errors | Concurrent recalculate or stale line | Follow workspace status; recalculate only from allowed statuses |
| Company Settings listing 417 | Wrong orderBy column | Applet uses modified_date on company queries |
| Statutory TXT missing employer no | Company Setup incomplete | Fill EPF/SOCSO/EIS/PCB numbers, re-run report |
| Post GL has nothing to post | No default GL mapping / incomplete COA | Set Default mapping with valid glcodes |
Related documentation
- Configure and run monthly payroll — user guide
- HR & Payroll Module — module context
- Employee Maintenance — employee master
- Chart of Accounts Setup — COA before Post GL