Provider Bootstrap: From Zero to First Payslip

The Idea Behind a Provider Stub

Payroll Engine separates the calculation infrastructure from the compliance content. The open-source engine handles how payroll runs — period logic, case value storage, retro corrections, the REST API, payrun execution. The country regulations handle what the payroll calculates — tax formulas, social security contributions, statutory reporting.

As a provider, you don’t write either of those. You configure a provider stub: a thin layer that sits between the country regulation and your specific operation. It connects your company structure to the engine, defines your payroll scope, and tells the system which regulations to use for which employees.

Think of it this way: the country regulation knows how to calculate German income tax. Your provider stub tells the engine that you have a tenant called “Acme GmbH” with 50 employees in payroll division “Berlin”, and that their payroll should use the German regulation with a monthly cycle.

What You Need

The Payroll Engine stack is straightforward. Everything runs on .NET 10, and the only external dependency is a database (SQL Server or MySQL).

The first three are open source on GitHub. You can download, build, and run them without any license. The country regulation is the commercial component you acquire through PayrollEx partners.

The Bootstrap Path

The journey from zero to first payslip follows five concrete steps. None of them require writing payroll calculation logic.

Step 1: Start the backend

The backend is an ASP.NET Core application. You point it at a database, start it, and the REST API is available. The backend creates the schema automatically on first startup. At this point you have a running payroll engine — with no data in it.

Step 2: Create a tenant

A tenant represents one company in the system. Multi-tenant providers create one tenant per client company. You can create tenants through the REST API, the WebApp, or the pecmd CLI. The tenant is the isolation boundary — everything that follows happens inside this tenant.

Step 3: Deploy the country regulation

This is where the provider stub concept becomes concrete. A country regulation is delivered as an Exchange JSON package — a structured JSON file that contains the complete regulation: wage types, cases, case fields, lookups, data regulations, scripts, and integration tests.

Deployment is a single CLI command:

pecmd PayrollImport DE.Entgeltabrechnung.json

This imports the entire German regulation into your tenant. No build step, no compilation, no server restart. The regulation is immediately active and available for payrun execution. The same works for any of the eleven supported countries.

If you operate in multiple countries, you deploy multiple regulations — one per country. Each regulation is self-contained and operates independently within the same engine instance.

Step 4: Set up the payroll and employee data

With the regulation deployed, you configure the payroll structure and enter employee data. The payroll configuration defines which regulation layers the calculation uses and which period cycle to follow (monthly, bi-weekly, etc.).

Employee data entry follows the Case/CaseField model defined by the country regulation. For a German employee, this means entering the fields the regulation declares: salary, tax class, health insurance type, social security parameters, and so on. You enter exactly the fields the regulation requires — no more, no less.

Data entry happens through the WebApp (manual), the REST API (programmatic), or via adapters that import employee master data from HR platforms like Personio, Sage, or AFAS.

Step 5: Run the payroll

A payrun takes the employee data, applies the country regulation’s calculation logic, and produces results: gross-to-net breakdown, tax withholding, social security contributions, employer costs. The payrun can be executed as a preview (synchronous, no persistence — for verification), a forecast (persistent, parallel scenarios), or a legal run (persistent, with approval process).

pecmd PayrunJobStart DE.Payroll /preview

The result is a complete payslip calculation, produced by the country regulation’s statutory logic, running on the open-source engine. You didn’t write a single tax formula.

Your Provider Layer

Once the base country regulation runs correctly, most providers add a provider regulation layer on top. This is the three-layer model described in the Composable Regulation Model: country regulation (statutory), provider regulation (operational), and optionally company regulation (tenant-specific).

The provider layer is where you define the things that are specific to your operation but common across your clients:

The provider layer references the country regulation as its baseRegulation. At payrun time, the engine merges both layers: the country regulation provides the statutory calculations, the provider layer provides the operational extensions. A provider wage type for “Performance Bonus” automatically flows into the country regulation’s gross income collector and from there into the correct tax and social security calculations — without the provider needing to understand the tax formula.

This is what makes the stub approach powerful: you configure the connection between your business logic and the statutory rules, but you never implement the statutory rules yourself. The country regulation handles LSt, SolZ, KiSt, KV, PV, RV, AV, UV, and Umlagen. You handle “Performance Bonus = 5% of base salary.”

Testing Without Building

Every country regulation ships with a complete integration test suite. These aren’t unit tests — they’re full payrun executions against a live backend that verify the regulation produces correct results for documented scenarios.

As a provider, you can run the regulation’s test suite against your own engine instance to verify that the deployment is correct. The tests are part of the regulation package and execute via pecmd:

pecmd PayrunEmployeeTest DE.Entgeltabrechnung.Test

If all tests pass, you know the regulation is correctly deployed and producing verified results. If a test fails, you know something in your setup differs from the expected configuration — a missing data regulation, an incorrect payroll layer, or a configuration mismatch.

For your provider layer, you write your own tests following the same pattern: define a scenario (employee data + payrun), specify expected results (wage type values), and let the engine verify. The test framework is the same one used to develop the country regulations themselves.

Multi-Country: Same Engine, Multiple Regulations

The bootstrap path described above works for a single country. But the architecture is designed for multi-country operations from the start.

A provider running payroll in Germany, the Netherlands, and Spain deploys three country regulations into the same engine instance. Each country regulation operates independently — the German regulation doesn’t know about the Dutch one, and they don’t interfere with each other. Each tenant is configured with the regulation layers appropriate for its country.

For consolidated reporting across countries, the engine provides consolidation through standardized wage types (WT 7000–7030) that every country regulation implements with the same interface. A single query can aggregate employer costs, headcount, or net pay totals across all countries, with automatic currency conversion.

What Comes After Bootstrap

The first payslip is a milestone, not the destination. After bootstrap, providers typically follow a progression:

Operational automation. The pecmd CLI and REST API enable full automation of the payroll cycle: data import, payrun execution, result export, and report generation. Providers integrate this into their operational workflow — scheduled payruns, automated reconciliation, CI/CD pipelines for regulation testing.

Adapter integration. Instead of manual data entry, adapters pull employee master data from HR platforms automatically. Delta synchronization ensures the payroll always works with current data.

AI integration. The MCP Server gives AI agents structured access to the payroll API. Read-only queries (employee data, payrun results, regulation structure) are available through the open-source MCP Server. Write operations and consolidation queries require the MCP Server Pro.

Tenant customization. For clients with specific requirements (custom bonus structures, industry-specific allowances, collective agreement overlays), the three-layer model allows tenant-level regulation layers without touching the country regulation or the provider layer.

All of this builds on the same foundation: an open-source engine running commercial country regulations, configured through a provider stub that connects your operation to the statutory rules. The bootstrap is the first step. The architecture is designed to carry you from there.