Payroll data flowing out of your own system

Payroll integration in Nepal means your own system stays the source of truth for employees, attendance and salary structure, while a scheduled job pushes validated data into the payroll engine, the bank file and statutory returns — then pulls back the results. Get the boundary wrong and you'll pay someone twice, or not at all.

Key Takeaways

Payroll integration succeeds or fails at the boundary between systems, not at the choice of API. One owner per field, a hard cut-off before the run, control totals that match on both sides, and statutory rates held as configuration rather than code — that combination prevents almost every payroll incident we have been called in to fix.

• Your HR or ERP system should own the employee master; the payroll engine should own gross-to-net. Two owners for one field is how duplicate payments begin.
• The exported file is the contract. Employee count, gross, deductions and net must match on both sides before anyone approves the run.
• Tax slabs, contribution percentages and bonus rules change with every budget. Store them as effective-dated configuration rows, never as constants in a script.
• Attendance is the messiest input. Overtime, unpaid leave and shift allowances explain most of the variance between two payroll runs.
• Re-run safety beats speed: an idempotent run you can replay for one employee is worth more than a fast run you cannot undo.
• Salary data is personal data. Least privilege, audit logging and clean offboarding are part of the integration, not an afterthought.
• A scheduled export plus a bank file covers most Nepali SMEs. Full middleware only pays off with multiple entities or daily pay variation.

What does payroll integration in Nepal actually cover?

Payroll integration covers four flows: employee master changes, attendance and leave, the monthly gross-to-net calculation with statutory deductions, and the outputs — the bank payment file, payslips, and filings with the Inland Revenue and the Social Security Fund. Your own system owns the inputs; the payroll engine owns the arithmetic.

Most teams open with the wrong question: which API do we use? The expensive failures sit at the edges instead. A resigned employee still flagged active. An overtime hour approved two days after the cut-off. A bank account digit transposed, discovered only when the salary bounces back.

Nepali payroll adds local wrinkles. The fiscal year runs Shrawan to Ashad, so tax slabs, festival allowances and bonus rules reset on a boundary that has nothing to do with January. Gratuity accrual, Dashain allowance and leave encashment all need a home in the data model.

Why does the boundary matter more than the API?

A payroll run moves real money on a fixed date, so the boundary decides who may change what, and when. If both your HR system and the payroll tool accept edits to a salary or a bank account, reconciliation will not save you — you will just be arguing about which record is true.

Pick one owner per field and write it down. Employee identity, bank details and salary structure usually belong to the source system. Gross-to-net, deductions and the payment file belong to the payroll engine. Attendance can go either way, but the cut-off rule must be explicit — anything approved after it rolls into next month.

That is also why idempotency matters more than speed. A run you can safely replay for a single employee is worth more than one that finishes in seconds and leaves you rebuilding a month by hand.

When do you actually need a real integration — and when is a spreadsheet enough?

Under roughly thirty staff with stable monthly pay, a controlled spreadsheet export plus a bank file is genuinely fine. You need real integration when attendance changes daily, when pay varies by shift or site, when more than one entity is involved, or when an auditor asks who changed a salary and when.

Watch the number of manual corrections per month, not headcount. If your payroll officer loses a day fixing the same five categories of error, the export is the problem, not the person.

The second signal is rework after the fact. Once a payslip is issued and a bank file is paid, fixing a mistake means a supplementary run, an adjustment entry and an awkward conversation. Preventing that is the whole point.

How should the data flow?

Data should move one way per field, on a schedule, through a staging table you can inspect. Read the source, validate it, load a staging copy, run the calculation, then release the bank file only after control totals match on both sides of the boundary.

1. Snapshot the employee master — active staff, bank details, salary structure, cost centre — into a staging table. Never let payroll read live HR tables directly; a mid-run edit produces a half-updated month.
2. Pull attendance and approved leave for the period and apply the cut-off. Late entries belong to the next cycle.
3. Validate before calculating: missing bank accounts, zero salaries, duplicate employee codes, joiners without a tax identifier.
4. Run gross-to-net using rates loaded from configuration for the effective date, not constants in the script.
5. Produce the bank file and payslip set, and hold both. Nothing leaves yet.
6. Reconcile headcount, total gross, total deductions and total net.
7. On written approval, release the file, post the journal to accounting, and archive the run with a checksum.

A nightly job is usually enough. A scheduled workflow keeps the steps visible and versioned:

on:
  schedule:
    - cron: "0 2 * * *"   # 02:00 UTC daily
  workflow_dispatch:      # allow a manual re-run

If the staging load starts with TRUNCATE staging_employees, be clear about what that does: it wipes the table. Reload from source before any retry, and keep the previous run's snapshot until the month is closed. See the GitHub Actions schedule documentation for how cron triggers behave.

Which configuration settings decide whether the run is correct?

Five settings decide correctness: the fiscal-year boundary, effective-dated tax and contribution rates, the attendance cut-off, rounding rules for deductions, and the mapping from your salary heads to the payroll engine's components. Get any one wrong and every payslip in that run is wrong in the same way.

Effective dating is the one teams skip. Rates change with each budget, and a run for an earlier month must use the rates that applied then. Store rate rows with a valid-from date and let the calculation pick the row instead of overwriting last year's value.

Rounding is the quiet one. Decide whether deductions round half-up or truncate, apply it consistently, and keep the remainder so annual totals tie out. Two systems rounding differently produce a small per-person variance that turns into an audit question.

How do you verify a payroll run before money leaves?

Verify with four numbers that must match on both sides of the boundary: employee count, total gross, total deductions and total net. If those agree, and the bank file's line count equals the net-pay line count, the run is internally consistent and you can release it with evidence behind you.

Then test the exceptions deliberately. Pay one mid-month joiner, one mid-month exit, one person on unpaid leave and one with an overtime adjustment. If those four calculate correctly, the common edge cases are covered.

Keep the artefact. A run that stores its input snapshot, rate-table version and output hash can be explained a year later. One that doesn't becomes archaeology.

What breaks in production, and in what order do you debug it?

Debug in this order: duplicate or stale employees, then attendance and cut-off, then rate configuration, then file format, and only last the calculation code. In practice the calculation is almost never the bug — the input data is.

Symptoms map to causes. A total that is off by exactly one salary means a duplicate employee row. A net pay that differs by a fixed amount per person usually means a stale deduction rate. A bank file rejected wholesale is normally a header, encoding or delimiter problem rather than a wrong amount.

The nastiest failure is the partial run: the file reached the bank, then the journal posting failed, and now the ledger and the payment disagree. Reconcile monthly, not annually, and keep the bank acknowledgement next to the run record.

What does payroll integration cost to build and run?

Cost is driven by how many systems touch salary data, how custom the pay rules are, and how much of the work is reconciliation rather than code. The build is usually the smaller number; the recurring cost is the person who owns the month-end run.

Cloud and licence costs depend on instance size, the storage class you use for archived run artefacts, and whether you pay per employee for a payroll product. Confirm current figures with the vendor's own calculator before committing to a design, and talk to our team about the build side through our software development service.

There is also a real cost to doing nothing. One avoided duplicate payment or late statutory filing usually covers the work, and finance stops losing three days a month.

What are the security and privacy requirements for salary data?

Treat the payroll pipeline as a restricted system: least-privilege access, encrypted transport and storage, an audit log of who read or exported salary data, and a documented retention period. Salary data is personal data, and a leak carries both a legal cost and a staff-trust cost.

In practice: keep bank files in a private bucket with server-side encryption using a customer-managed key, never a shared drive; scope the API token to payroll only and rotate it on a schedule. The AWS KMS documentation explains the key-management side if you host on AWS.

Offboarding belongs to the same job. When someone leaves, their access to the HR system, the payroll tool, the file bucket and the CI secrets should be removed in one documented step — the checklist in our guide to removing system access when staff leave is a reasonable starting point. And never use live salary data in a test environment; generate synthetic employees instead.

What mistakes do teams make most often?

The recurring mistakes are structural rather than technical: rates hard-coded in a script, two systems accepting edits to bank details, no attendance cut-off, files emailed as spreadsheets, and one person who knows the steps. Each one is cheap to fix before a run and expensive to fix after one.

• Hard-coding tax slabs and contribution percentages instead of storing them with effective dates.
• Deleting terminated employees rather than closing their record, which destroys the history an audit needs.
• Exporting salary data to email or a personal drive because the "proper" path was slower.
• Skipping the dry run because the previous month matched.
• Letting the integration live with one engineer and no runbook.

A realistic scenario: 180 staff, three sites, one payroll deadline

A Kathmandu services company runs 180 staff across three sites, with shift allowances, a handful of foreign-currency contracts and a monthly payroll deadline that cannot move. Their HR system held the employee master, a spreadsheet held overtime, and the payroll officer reconciled by hand every month — usually late at night.

We did not replace the payroll engine. We put a staging table between the two systems, moved overtime approval into the HR tool with a visible cut-off, and loaded rates as effective-dated rows. The export became a scheduled job that writes a bank file and a control-total report; the officer now checks four numbers and releases.

Month-end went from roughly two days of reconciliation to under an hour, and the first audit after the change was answered with stored run artefacts instead of memory. Nothing about the calculation changed — only the boundary.

How do the integration approaches compare?

The approaches differ in blast radius and who has to operate them, not in how clever they are. Manual export has almost no build cost but concentrates risk in one person; middleware has the highest build and the highest ongoing ownership. Most businesses sit in the middle two rows.

Approach	Fits when	Operational overhead	Main risk
Manual spreadsheet export	Under ~30 staff, fixed monthly pay	Low build, high effort every run	Transcription errors, no audit trail
Scheduled file drop	One entity, monthly cycle, auditor needs a file	Moderate; needs monitoring and alerting	Silent failure when the job does not run
API sync with payroll engine	Attendance varies daily, many pay components	Higher build; retries and error handling	Rate limits and partial failures
Middleware or custom service	Several entities and systems, near-live finance data	Highest; someone must own it permanently	Complexity outgrows the team

If you already run accounting integration work, the same control-total discipline applies — see our notes on connecting a website or internal system to accounting software, and the general pattern in integrating two systems that were never designed to talk.

In short: keep one owner per field, freeze inputs before the run, validate into a staging table, reconcile four control totals, and release the bank file only on written approval. Store rates with effective dates, log every read of salary data, and keep the run artefacts. That is the whole discipline — the rest is plumbing.

People also search for

• What a payroll or HR integration build actually includes in a quote
• Custom payroll software vs an off-the-shelf package
• Where employee and customer data should be stored
• Why staff keep reverting to the old spreadsheet
• Digital payment integration options for salary disbursement
• Connecting your system to accounting software
• Removing system access when an employee leaves

If payroll data is leaving your system through a spreadsheet and a hope, our team can help you design a boundary that holds — a staging table, a scheduled job, control totals and an audit trail your finance team can defend. Start with a review of what exists today, then talk to us about the build.