Payroll Admin

Configure Malaysian payroll for a company, put employees into pay groups with salaries and bank details, and run each month from draft through calculate, approve, finalize, bank file and Post GL, with the statutory files generated from the run. Two things the status path does not show: Finalize does not lock the payslips, and Post GL writes three lines into the payroll module’s own journal and nothing anywhere else — bring the month into your accounts with a manual journal, and check the journal rather than the status. It is not separately installable and nothing installs it today: HR & Payroll is a planned module, not yet offered, so read this page to judge what payroll will and will not do, not to run this month’s payroll.

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

Screens and menus

The applet has four menu items and one gear. Everything you do here is in one of them, and the pay run is the only screen with a state machine behind it.

Main menu

Settings (gear)

Payroll Configuration

System Configuration

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

1. Create a calendar for the company (MONTHLY frequency is the Phase-1 path).
2. Create pay periods under that calendar with Period Start, Period End, and Payment Date.
3. Keep period status OPEN until 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 and deduction types carry flags such as taxable, EPF/SOCSO/EIS/PCB applicable, pre-tax and recurring; they are stored for the record and Calculate does not read any of them — what it reads is the component type on each of the employee’s salary lines. See Fields.

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:

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 the company name, 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:

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

1. Select a pay run.
2. Run a statutory or payroll report.
3. Result opens in a dialog with row preview and TXT / base64 download when the backend returns a file.

Configuration

Payroll has two quite different configuration surfaces, and only one of them matters. The Settings (gear) entries above — company setup, calendars, periods, structures, allowance and deduction types, statutory rates and GL mapping — are the payroll masters, and they are what a first-time setup consists of. The generic Application Settings and Default Selection screens that every Wavelet applet carries are almost entirely inert here.

Applet settings

Settings → Application Settings opens the shared field-configuration screen. The applet declares a settings model of about 120 keys — the standard HIDE_*, EXPAND_*, ENABLE_CUSTOM_STATUS_*, NAME_CUSTOM_STATUS_* and dimension families inherited by every applet built from the same template — and none of them changes what payroll does. They hide columns on the listings. See how settings are stored and who they apply to.

Settings → Default Selection holds the three that are read: default company, default pay group and default currency, used to pre-fill the pay-run and roster forms. They are a convenience, not a constraint — every form lets you change them.

On the screen and doing nothing

Named rather than quietly left out, because each one looks like it decides money and does not.

• Allowance Type → Taxable · EPF Applicable · SOCSO Applicable · EIS Applicable · PCB Applicable · HRDF Applicable, and the same six on a Salary Structure line. They are captured, stored and shown as a column, and the pay-run calculation never consults them. Every earning on a salary structure is added to gross, and EPF, SOCSO, EIS and PCB are all computed on gross — see Fields.
• Deduction Type → Pre-tax and Recurring. The same: Pre-tax changes nothing because there is no pre-tax step; Recurring changes nothing because the calculation reads the employee’s salary lines each time, not a recurrence rule.
• Application Settings → the HIDE_* / EXPAND_* / custom-status families. Template keys. Setting one hides a listing column at most.

Both of these are configuration that has shipped ahead of the calculation meant to use it, rather than settings that were removed. Fill them in if you want the master data to be right for later; do not expect this month’s pay to change.

Which means deciding what each component attracts is a person’s job, done on paper, and it is a real decision rather than a formality — the four Malaysian schemes do not agree with one another. Overtime is not EPF wages but is SOCSO wages. An annual bonus is EPF wages but is not SOCSO or EIS wages. Payment in lieu of notice is not EPF wages; payment for unutilised annual leave is. The HRD Corp levy is on basic pay and fixed allowances only, with bonus, commission and overtime all excluded. Whoever owns payroll writes the component-by-component table down once, has it approved, and re-reads it whenever a new allowance is introduced. The check is that a sample payslip’s EPF base equals the components that table calls EPF wages — which, today, it will not, because everything is on gross.

Who can change what

The applet defines no client-side permissions. There is therefore no per-field or per-button gating inside the applet, and no way to let one person run a pay run while another may only read it.

Access is all-or-nothing inside the applet: whoever has it installed can open every screen, including Approve, Finalize and Post GL. The boundary that does exist is at the API, and it is better than it looks — the payroll endpoints carry six separate permissions on the pay run (CALCULATE, APPROVE, FINALIZE, BANK_FILE_GENERATE, GL_POST, FILE), not one write permission, and the run header records who calculated, who approved and who finalised it in three separate columns.

What it does not do is check that those are three different people, and that is the whole of segregation of duties in payroll. So it is an assignment decision, made by the tenant administrator at implementation, not by the software at run time: give Calculate to the person who prepares the run, Approve to somebody who did not, and the bank file to a third if you have one. Where the company is too small for three, the compensating control is that a second person compares the bank file’s total and record count against the approved run before it is uploaded, and signs the comparison. You know the separation is real when a payroll login gets a 403 on approve — check it once, on the day the permissions are assigned, rather than assuming it.

Configuration checklist (first company)

Use this order once per company. Full narrative with the GadgetSphere example: Configure and run monthly payroll.

1. Company exists in Organisation; chart of accounts + payroll expense / liability codes exist.
2. Employees exist in Employee Maintenance with bank payment config.
3. Company Setup — employer numbers.
4. Statutory Rates — EPF / SOCSO / EIS / PCB headers + tiers.
5. Pay Calendar → Pay Period for the month.
6. Salary Structure / allowance / deduction types as needed.
7. Pay Group linked to calendar (and structure).
8. Employees roster — salary + pay group + bank + statutory flags.
9. GL Mapping — three COA codes, tick Default.
10. Default Selection — optional default company / pay group / currency.
11. Create Pay Run → Calculate → Approve → Finalize → Bank file → Post GL.
12. Reports — generate statutory TXT and keep the download pack.

Permissions and install

There is no install path today (see Availability at the top). With no registry row there are also no client-side permission definitions for this applet; the payroll backend endpoints enforce the standard tenant API permissions.

Fields

The forms themselves are ordinary — the screens above name every tab and every box. What is not on any of those screens is which stored field ends up in which number on a payslip, and that is the question you will actually be asked when somebody’s pay looks wrong. This is the map, read from the calculation itself.

The rates the calculation uses when your Statutory Rates are missing

This is the single most surprising thing about a first pay run. Calculate looks up the Statutory Rates master for the country and the employee’s salary — and if that lookup fails for any reason it falls back, without a message, to constants compiled into the backend:

The SKBBK zero needs reading carefully. The code comments that the scheme “may not apply until gazette / company opt-in”. PERKESO’s LINDUNG 24 Jam commenced on 1 June 2026: it is an employee-only contribution taken off the Act 4 Third Schedule column, capped at the RM6,000 ceiling, mandatory for foreign workers, and the opt-out window for local employees ran from 13 July to 31 August 2026. So a zero here is not evidence that the scheme does not apply to you. Whoever owns payroll checks each employee’s SKBBK position against PERKESO’s ASSIST portal and adds a SKBBK Statutory Rates header before the first live run; the check that it worked is that a foreign worker’s payslip carries a non-zero SKBBK line.

These are not the gazetted tables. They are placeholders that keep the calculation running, and a pay run built on them will produce plausible, wrong statutory amounts and a CP39 / EPF Form A that agrees with them. Create the Statutory Rates headers before the first live run, and then check the payslip’s calculation trace to confirm which set was used.

The calculation trace — where every number on a payslip came from

Every payslip Calculate builds also writes seven trace rows, in order: GROSS · EPF · SOCSO · EIS · PCB · SKBBK · NET. Each records the inputs it used and the result, and the EPF, SOCSO and EIS rows carry a label that says which source the rate came from — EPF master 11% EE / 13% ER when your Statutory Rates were read, or EPF fallback when they were not. That label is the fastest answer to “why is this employee’s EPF wrong”, and it is not shown on any screen: read it through the payroll API for the payslip.

The traces, the payslip and its lines are destroyed and rebuilt on every Calculate — see Lifecycle and effects.

Lifecycle and effects

A pay run is not a document in the usual sense. It has no document type, no amounts that post through the ordinary document posting, and it lives in the payroll module’s own records. So none of the usual document machinery applies to it: nothing moves stock, nothing raises an e-Invoice, and no background job runs for payroll at all.

The status path, and the two transitions that are looser than they look

DRAFT → CALCULATED → APPROVED → FINALIZED → BANK_GENERATED → POSTED → FILED

Two of those are worth reading twice. Generate Bank File accepts an APPROVED run, so a run can reach the bank without ever being finalised; and Post GL accepts a FINALIZED run, so a run can be posted without a bank file having been generated. Neither is blocked and neither warns. Anything else is refused with Cannot move pay run from <current> to <target>. Allowed from: […].

What Post GL actually posts

Post GL writes three lines into the payroll module’s own journal — and nothing anywhere else.

The journal is stamped POSTED immediately, numbered PRJ-<pay run code>, and dated the run’s payment date.

What a finalised run does not do

• It does not pay anybody. The bank file is a file you download and upload to your bank’s portal.
• It does not file anything with KWSP, PERKESO or LHDN. File statutory builds the TXT packs and attaches them to the run; submitting them is a separate, manual step outside BigLedger. And FILED means three files were attempted, not three files were produced: each generator runs in its own try/catch, a failure is recorded as an error key inside the run’s properties, nothing is surfaced, and the run reaches FILED regardless. Open all three files before you believe the status.
• It does not check the file against the regulator’s current specification, and three of them are known not to match. The EPF Form A generator writes a fixed-width file where KWSP’s i-Akaun (Majikan) channel takes a CSV; the PERKESO generator writes a pipe-delimited file where a combined fixed-width contribution file becomes compulsory on 1 October 2026; and the CP39 generator hard-codes country MY with a blank passport, which is wrong for every foreign employee. So whoever files checks each file in the regulator’s own portal before the 15th — upload it, read the validation response, and keep the acknowledgement — rather than treating a downloaded file as a filed return.
• It does not lock the employee’s salary or the masters behind the run. Changing a salary structure changes what the next Calculate produces; a run already calculated keeps its payslips until somebody recalculates it.
• It does not notify anyone. There is no approval e-mail, no reminder and no scheduled job. The calendar is a person’s: every Malaysian monthly obligation — EPF, SOCSO, EIS, SKBBK, PCB/MTD and the HRD Corp levy — falls on the 15th of the month after the wage month, moving to the next working day if the 15th is a holiday. Whoever files puts all six in a diary at the start of the year; the check is six acknowledgements on file by the 16th.

Related applets

Payroll Admin holds almost no master data of its own. Nearly every value a pay run needs is owned by another applet, which is why a first-time setup is mostly a tour of the five below.

Payroll Admin is not in the applet registry, so none of those five pages links back to this one today and you will not meet it by browsing from them. Reach it from the HR & Payroll module page or from Configure and run monthly payroll.

Troubleshooting

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