Building a Cross-Country Payroll API: The Weird Problems I Didn't Expect
webdev #fintech #ai #javascript
Last year, while trying to estimate the real take-home pay of a potential job abroad, I started building my own German payroll tax engine.
At first it was a simple question:
"What would actually be left from the salary after taxes and deductions?"
But once the German calculation layer existed, adding other countries felt almost inevitable. So I expanded into Austria, Switzerland, the UK, Ireland, the US, Canada, and Australia — the goal being a unified API layer for cross-country salary comparison.
The problem was that the deeper I went, the less universal the concept of "salary" actually became.
The "same salary" illusion
My initial assumption was that cross-country salary comparison was mostly a math problem: feed in a gross salary, apply taxes, compare the outputs. That assumption collapsed surprisingly quickly.
A €60k salary in Germany behaves fundamentally differently from €60k in Switzerland or the US — not just because of different tax rates, but because each country structures payroll, insurance, pensions, and mandatory obligations in its own way. Germany embeds a large portion of social costs directly into payroll deductions. Switzerland externalizes major costs like health insurance outside the payroll system entirely. The US fragments responsibilities across federal taxes, state taxes, FICA contributions, and employer-sponsored systems.
The API inputs looked identical on the surface. Semantically, they represented completely different economic realities. I wasn't comparing salaries anymore — I was trying to expose incompatible social systems through a stable API contract.
Building the normalization layer
The architecture eventually split into two distinct concerns. The first layer handles country-specific payroll execution: tax brackets, pension systems, social insurance rules, filing classes, payroll periods, and deduction logic. The second attempts to normalize those outputs into something comparable across countries — effective tax rates, disposable income, after-rent estimates, and purchasing power signals.
That split sounds clean conceptually, but it introduced the central engineering tension of the entire project. Internally, every country demanded highly specific rules and exceptions. Externally, developers still expected a coherent and predictable API surface. The challenge wasn't building country-specific logic — it was preventing the API contract from collapsing under the weight of semantic inconsistency.
The hardest part was not taxes
Surprisingly, implementing the actual tax calculations was rarely the hard part. The harder problem was defining what the output fields were even supposed to mean.
Take something as seemingly simple as "net": 45000. What exactly does "net" include? Does it assume mandatory health insurance? Private insurance? Pension obligations? Housing? Childcare? Post-payroll deductions?
Different countries hide or expose costs in completely different places. Germany pushes many obligations directly into payroll deductions. Switzerland leaves major mandatory costs visible after payroll. The US introduces further fragmentation depending on employer structures and state-level rules.
At some point the project stopped feeling like a tax engine and started feeling more like a semantic normalization problem. The API wasn't just calculating numbers anymore — it was trying to make structurally different economic systems look comparable without hiding their differences.
Designing for workflows and AI agents
Things became even more interesting once I started exposing the calculation layer through OpenAPI specs, MCP endpoints, and automation platforms like Pipedream and Postman. That completely changed how I thought about API design.
Human users tolerate ambiguity surprisingly well. Automation systems do not. A developer reading documentation can usually infer missing context from examples or surrounding explanations. An AI agent consuming a tool schema often treats every field as globally stable and semantically precise. That forced the API design to become much stricter: deterministic outputs, stable response contracts, explicit validation behavior, consistent naming, forward compatibility, and machine-readable assumptions throughout.
One unexpectedly valuable experience was integrating Obolus into the Pipedream ecosystem. The review process forced me to rethink parts of the implementation that had evolved fairly organically — authentication handling, naming conventions, request abstractions, action ergonomics, and advanced parameter exposure. It was a useful reminder that API design is heavily shaped by the ecosystems your API participates in, not just by your own architecture preferences.
Salary comparisons become political very quickly
One thing I genuinely didn't anticipate was how quickly salary comparison discussions become political. Once you normalize outcomes across countries, uncomfortable questions start appearing naturally: How much does housing dominate disposable income? How much is hidden inside payroll systems? Which systems redistribute more aggressively? What actually produces financial freedom?
Two countries can produce the same nominal salary and completely different lived realities. In some places, taxes are high but essential services are embedded directly into the system. In others, nominal salaries appear stronger while major obligations remain externalized. Trying to compare outcomes consistently forces you to confront how differently societies structure healthcare, pensions, labor costs, housing, and risk distribution. At some point, the project accidentally became as much about systems design as software design.
What the project became
Originally, Obolus was just a relocation comparison experiment. Over time it slowly evolved into something closer to infrastructure for cross-country financial decisions — with payroll calculation endpoints, cross-country comparison APIs, OpenAPI specifications, MCP integrations, workflow automation support, and developer tooling.
The biggest lesson for me was realizing that building a calculation engine is only one part of the problem. The much harder part is designing abstractions that remain understandable across countries, payroll systems, developers, automation workflows, and AI agents simultaneously.
And honestly, I still feel like I'm only scratching the surface of how difficult financial normalization across countries really is.
