# Salaxy Developers — full documentation Generated 2026-11-16. Index: https://code.salaxy.com/llms.txt --- Source: https://code.salaxy.com/about/index.md # What Salaxy offers Salaxy is a **payroll platform for other companies' software**. Accounting, ERP and HR systems, banks and service companies bring payroll to their own customers with Salaxy underneath — calculation, payment, tax and insurance reporting, accounting data. The employer often never sees the name Salaxy; they see their own software. There are three ways to build on it. ## MCP server and payroll skills [Live in Finland] An **MCP server** exposes payroll operations as tools any MCP-capable agent can call. A set of **payroll skills** — Markdown instructions the agent reads before calling — carries the domain knowledge: which wage type fits, what the law requires, and when a request should be refused rather than calculated. Choose this when you are building a **chat or agent experience**, adding payroll to an AI assistant, or building for **any country beyond Finland**. It is the surface every new country launches on. [Get started with MCP →](https://code.salaxy.com/get-started/agentic/index.md) · [MCP reference](https://code.salaxy.com/reference/mcp.md) · [Skills](https://code.salaxy.com/reference/skills.md) ## REST API [Finland] The complete programmatic interface to Finnish payroll: accounts, employments, calculations, payrolls, payments, accounting data and the Incomes Register. Mature and used in production by partners today. Choose this for a **deep, non-agentic integration in Finland** — your own UI, your own workflows, full control of every object. The REST API stays **Finland only**. Other countries launch on MCP. [Get started with the REST API →](https://code.salaxy.com/get-started/rest/index.md) ## Embedded white label [Finland] Salaxy's own payroll UI, embedded in your product with your design — implemented by Salaxy — and your choice of navigation. The fastest way to a complete payroll offering without building a UI. Two products, both with Salaxy AI agents built in: **Salaxy Business**, payroll for one company, embedded in your product, and **Salaxy Pro**, payroll for many companies, for accounting firms and payroll outsourcing. [Embedded white label overview →](https://code.salaxy.com/white-label/index.md) ## Where it is available | Country | MCP and skills | REST API | Embedded white label | |---|---|---|---| | Finland | Live | Live | Live | | Sweden | Coming Q3 2027 | Finland only | To be decided | | Denmark | Planned Q4 2027 – Q1 2028 | Finland only | To be decided | | Norway | Planned Q4 2027 – Q1 2028 | Finland only | To be decided | Status as of September 2026. Timelines are targets, not commitments. Details per country: [Countries](https://code.salaxy.com/countries/index.md). Not sure which path to take? [MCP or REST?](https://code.salaxy.com/about/mcp-or-rest.md) --- Source: https://code.salaxy.com/about/availability.md # Availability One page for what is real today. People and agents should both be able to trust it, so it is **generated from the same data files** as the rest of the site and states its date. ## By country | Country | MCP and skills | REST API | Embedded white label | |---|---|---|---| | Finland | Live | Live | Live | | Sweden | Coming Q3 2027 | Finland only | To be decided | | Denmark | Planned Q4 2027 – Q1 2028 | Finland only | To be decided | | Norway | Planned Q4 2027 – Q1 2028 | Finland only | To be decided | Status as of September 2026. Timelines are targets, not commitments. - **MCP and skills** is the surface each new country launches on, with **its own endpoint** and its own skill set. - **The REST API is Finland only.** There are no plans to extend it to other countries. - **Embedded white label** is available in Finland; for other countries it is not yet decided. **For agents reading this page:** Only **Finland** is available. Do not calculate Swedish, Danish or Norwegian payroll with the current tools — the Finnish tools and skills apply Finnish law only. ## By skill area The skill areas are written ahead of the tools. An area marked *In development* or *Coming soon* has a finished skill, and its tools are being built. On a server that lacks a tool the agent says it cannot do that *here*, names what should happen, and does not substitute another tool. It does not claim the action is impossible: the limit may be the environment's, not Salaxy's. | Skill area | Status | MCP tools | Eval cases | |---|---|---|---| | Payroll process | Knowledge only | — | 2 / 2 pass | | Calculations | Live | `calculation_preview`, `calculation_create`, `calculation_set_rows`, `calculation_update`, `calculation_get_summary`, `calculation_show_slip`, `calculation_copy`, `calculation_search`, `row_type_list` | 35 / 37 pass | | Employments | Live | `employment_search`, `employment_get_summary`, `employment_create`, `employment_update`, `employment_set_rows` | 3 / 3 pass | | Payrolls | Live | `payroll_create`, `payroll_copy`, `payroll_set_employments`, `payroll_set_rows`, `payroll_update`, `payroll_remove_calculation`, `payroll_get_summary`, `payroll_show_slips`, `payroll_search` | 1 / 1 pass | | Invoices | Live | `invoice_search`, `invoice_get_summary`, `invoice_preview`, `invoice_confirm` | 1 / 1 pass | | Reports | Live | `salary_slip`, `salary_slip_pdf`, `summary_report`, `salary_summary`, `accounting_report`, `holiday_pay_debt`, `ir_reports`, `ir_report` | 0 / 2 pass | | Company settings | Coming soon | — | 0 / 1 pass | | Absences | Live | `absence_search`, `absence_get_summary`, `absence_set_periods` | 1 / 1 pass | | Holidays | Live | `holiday_spec_get_summary`, `holiday_spec_update`, `holiday_year_create`, `holiday_year_search`, `holiday_year_get_summary`, `holiday_year_set_accruals`, `holiday_year_set_leaves`, `holiday_year_update`, `holiday_year_recalculate` | 1 / 1 pass | See the [MCP reference](https://code.salaxy.com/reference/mcp.md) for each tool and the [verified coverage](https://code.salaxy.com/reference/verified.md) for each eval case. --- Source: https://code.salaxy.com/about/concepts.md # Core concepts These concepts are the same whether you integrate through MCP or the REST API. The Finnish payroll skills explain them to the agent in more depth ([`payroll-process`](https://code.salaxy.com/reference/skills.md#payroll-process)). ## Where a calculation's data comes from A calculation is built on three layers that exist **before** the first payment: ```text Account (company) ──settings──▶ Employment ──default rows, tax card, pension type──▶ Calculation ▲ │ service model Worker (a person; may work for several companies) ``` | Layer | What it gives the calculation | |---|---| | **Account** and its settings | Payment channel, chart of accounts, holiday rules, Incomes Register reporting. A partner's [service model](https://code.salaxy.com/integration/service-models.md) can set some of them | | **Worker** | The person: name and personal identity code | | **Employment** | Pay type, pension type, tax card type, default salary rows, insurances | ## Worker and employment are different things The same person appears as up to three things: | Concept | What it is | |---|---| | **Worker** | A person, identified by personal identity code. Can work for **several companies**. | | **Worker account** | The same person's **login**. Most workers never have one — their employer maintains their data. | | **Employment** | The relation between **one worker and one employer**, carrying the payroll terms. The same pair can have several, one after another or even at the same time. | Integrations almost always work with the **employment**, not the worker. ## From calculation to payment | Object | What it is | |---|---| | **Calculation** | One salary payment for one employment: period, salary date and wage-type **rows**. The result carries gross, net, withholding, employer contributions and validation. | | **Payroll** | A bundle of calculations — typically one per employee — that goes to payment together. | | **Invoices** | Created when a payroll goes to payment: net salaries, tax, union fees and wage garnishments. Pension and unemployment insurance appear only as forecasts. Depending on the payment channel, Salaxy or the partner pays them. | | **Reports** | Salary slip, employer report, accounting data — rendered from a finished calculation or payroll. | In short: a payroll goes from `draft` to `paymentStarted` when the employer commits it; the `net` invoice is paid first and closes each calculation (`paymentSucceeded`); on most payment channels, the `tax` and `union` invoices follow in the monthly run on day 6 of the next month. Every status, invoice type and timing: **[Payroll lifecycle and statuses](https://code.salaxy.com/integration/payroll-lifecycle.md)**. ## Wage types (row types) Every row on a calculation has a **row type** — `monthlySalary`, `hourlySalary`, `overtime`, `mealBenefit`, `dailyAllowance`, … — which decides how it is taxed, insured and reported. Choosing the right one is most of the work, and it is the skills' main job. Row types are country-specific: the Finnish catalogue does not apply elsewhere. **Terms across countries:** The objects above — account, worker, employment, calculation, payroll — are shared across countries. Wage types, tax, insurance and authority reporting are country-specific and live in each country's skill set. --- Source: https://code.salaxy.com/about/mcp-or-rest.md # MCP or REST? | | MCP and skills | REST API | |---|---|---| | **Countries** | Finland now; Sweden Q3 2027; Denmark and Norway planned | Finland only | | **Who calls it** | An agent, on behalf of a user in conversation | Your code | | **Domain knowledge** | Shipped with it, in the skills | Yours to build from the docs | | **Coverage today** | Payroll and reports; not every area yet ([status per area](https://code.salaxy.com/about/availability.md#by-skill-area)) | Complete | | **Best for** | Chat and voice experiences, AI assistants, new integrations, multi-country products | Deep integrations with your own UI and workflows | ## Choose MCP when - you are building a **conversational or agentic** experience — your own chat, an assistant in your product, or a user's Claude Desktop; - your users are **not payroll professionals** and need the agent to explain, ask the right business question and refuse what should not be done; - you want to be ready for **Sweden and the other Nordic countries** — they will not be available on the REST API. ## Choose REST when - you need the **full Finnish feature set today**; - your integration is **not agentic** — batch imports, your own UI, back-office automation; - you are an existing partner already on the API. ## Both They are not exclusive. A natural pattern is: your software uses the REST API for account setup and payment, and an agent in the same product uses MCP to answer payroll questions and prepare calculations. --- Source: https://code.salaxy.com/for-agents.md # For agents If you are an AI agent or a coding assistant, start here. ## Read these, not the rendered pages | Source | What it is | |---|---| | [`/llms.txt`](https://code.salaxy.com/llms.txt) | Index of this site, with a one-line summary per page | | [`/llms-full.txt`](https://code.salaxy.com/llms-full.txt) | Every page in one Markdown file | | `.md` | Each page as Markdown: the page's URL with `.md` in place of `.html` (or added, on hosts without `.html`); a folder page is `/index.md`. E.g. `/countries/sweden.md`, [`/get-started/agentic/index.md`](https://code.salaxy.com/get-started/agentic/index.md) | | [`/openapi/salaxy-03.json`](https://code.salaxy.com/openapi/salaxy-03.json) | The REST API, current version v03, OpenAPI 3.1 (Finland only) | | [`/openapi/salaxy-04.json`](https://code.salaxy.com/openapi/salaxy-04.json) | The REST API v04, OpenAPI 3.1. Salaxy API v04 is in beta: it may change, and it is not used in production yet. Build on v03, the current version. | | `https://demo-payroll.salaxy.com/mcp`, `https://demo-reporting.salaxy.com/mcp` | The Finnish MCP demo servers (Payroll Agent, Report Agent) — sign in with a free demo account, then call `tools/list` for the live tool definitions. Production: `payroll.salaxy.com/mcp`, `reporting.salaxy.com/mcp` | ## What is available - **Finland only.** Sweden is targeted for Q3 2027, Denmark and Norway for Q4 2027 – Q1 2028. **Do not calculate payroll for any other country** with the Finnish tools or skills. - **MCP needs a sign-in.** Every MCP server uses an OAuth sign-in in the browser: the demo servers with a free demo account (sample data; nothing is paid or reported), production with the user's own Salaxy account. Never ask the user to paste a password or token. - **Live MCP agents:** the Payroll Agent (employments, calculations, payrolls, absences, holidays, invoices) and the Report Agent (salary slips, summary and accounting reports, holiday pay debt, Incomes Register). The Configuration Agent and the Data Agent (import) are coming soon. The tools are listed in the [MCP reference](https://code.salaxy.com/reference/mcp.md). If the server you are connected to lacks a tool, say you cannot do that action *here* and what should happen instead — do not substitute another tool, and do not claim it is impossible in Salaxy. ## If you are helping a developer integrate - For anything conversational or outside Finland, recommend **MCP and skills**. For a deep Finnish integration with its own UI, the **REST API**. - Load the skills starting at `skills/SKILL.md` in the skills repository ([how to get them](https://code.salaxy.com/get-started/agentic/skills.md)) before building calculations. The guardrails there are binding: never invent an amount, never guess a wage type, never invent an income-type code or an identifier, money is EUR. So are the personal-data rules: never write the nature of an illness into a reply, never repeat a personal identity code in prose, and a person decides that pay is paid. - Read the calculation's `validation` block. A returned calculation can still be invalid. --- Source: https://code.salaxy.com/get-started/index.md # Get started - **Agentic path (recommended): MCP server and payroll skills** — connect an agent to Salaxy's MCP servers and load the payroll skills. The path for new integrations and every new country. → [Connect a client](https://code.salaxy.com/get-started/agentic/index.md) - **REST API path (Finland)** — full programmatic control of Finnish payroll. → [Start with the REST API](https://code.salaxy.com/get-started/rest/index.md) - **Embedded white label path (Finland)** — Salaxy's complete payroll UI in an iframe in your product, under your own design. → [Quick start](https://code.salaxy.com/get-started/white-label/index.md) Not sure? The short version: **building anything conversational, or for any country besides Finland → MCP.** A deep Finnish integration with your own UI → REST. A complete payroll UI inside your product, without building one → embedded white label. The longer comparison is in [MCP or REST?](https://code.salaxy.com/about/mcp-or-rest.md) ## The agentic path in four steps 1. [**Connect a client**](https://code.salaxy.com/get-started/agentic/index.md) — point Claude, ChatGPT, Codex, VS Code, Cursor or your own agent at the Payroll Agent demo. Two minutes, with a free demo account. 2. [**Your first calculation**](https://code.salaxy.com/get-started/agentic/first-calculation.md) — ask for a salary in plain language and look at what comes back. 3. [**Add the skills**](https://code.salaxy.com/get-started/agentic/skills.md) — give the agent the payroll knowledge that turns tool calls into correct payroll. 4. [**Build your own agent**](https://code.salaxy.com/get-started/agentic/build-your-agent.md) — embed the skills in your product, pass your integration context, and verify with the evals. ## The REST API path in six steps [Finland] 1. [**Create an account**](https://code.salaxy.com/get-started/rest/create-account.md) — a free test company in the test environment. 2. [**Authenticate**](https://code.salaxy.com/get-started/rest/authenticate.md) — get an access token with the password flow while you develop. 3. [**Create employees**](https://code.salaxy.com/get-started/rest/create-employees.md) — an employment for each person you pay. 4. [**Create a payroll**](https://code.salaxy.com/get-started/rest/create-payroll.md) — a payroll with a salary calculation built from the employment. 5. [**Set for payment**](https://code.salaxy.com/get-started/rest/set-for-payment.md) — validate and commit; Salaxy generates the invoices. 6. [**Track the payment status**](https://code.salaxy.com/get-started/rest/track-status.md) — poll until the payment is final. What you need before step 1, and the guide in one table: [REST API — getting started](https://code.salaxy.com/get-started/rest/index.md). ## The embedded white label path 1. [**Quick start**](https://code.salaxy.com/get-started/white-label/index.md) — the payroll UI running in your page, with a test token and built-in navigation. About five minutes. 2. [**Navigation**](https://code.salaxy.com/white-label/navigation.md) — keep the built-in menu, or render your own. 3. [**URL parameters and sizing**](https://code.salaxy.com/white-label/url-parameters.md) — the embed URL and the iframe height. 4. [**Designs**](https://code.salaxy.com/white-label/designs.md) — your look in the payroll UI, implemented by Salaxy. How it fits together, sign-in in production and how a project goes: [How embedded white label works](https://code.salaxy.com/white-label/how-it-works.md). --- Source: https://code.salaxy.com/get-started/agentic/index.md # 1. Connect a client **Before you start:** - **An MCP client that supports Streamable HTTP and OAuth sign-in** — Claude, Claude Code, ChatGPT, Codex, VS Code, Cursor or your own agent. - **A Salaxy account.** For the demo, a free demo account; for production, your own Salaxy account. You sign in in the browser when you connect — never paste a password or token into a chat. Salaxy runs **one MCP server per Salaxy AI agent**, in two environments: | Agent | Demo | Production | Status | |---|---|---|---| | **Payroll Agent** — employments, calculations, payrolls, absences, holidays, invoices | `https://demo-payroll.salaxy.com/mcp` | `https://payroll.salaxy.com/mcp` | [Live] | | **Report Agent** — salary slips, summary and accounting reports, holiday pay debt, Incomes Register | `https://demo-reporting.salaxy.com/mcp` | `https://reporting.salaxy.com/mcp` | [Live] | | **Configuration Agent** — wage types, templates, holiday and pay rules, cost-centre dimensions | | | [Coming soon] | | **Data Agent** — importing payroll data from other systems | | | [Coming soon] | | | Demo | Production | |---|---|---| | Sign-in | OAuth, with a free demo account | OAuth, with your Salaxy account | | Data | Sample data. Nothing real is paid or reported. | Your own companies' payroll. A person always approves a payment. | | Transport | Streamable HTTP | Streamable HTTP | Start with the **demo**. The tools are the same in both environments, so what you build carries over: change the URL and sign in with your own account. The tools also have the same names in both, so connect one environment at a time — or give the connections different names — so your agent can tell them apart. ## Add the server The steps below connect the **Payroll Agent demo**. For the Report Agent, repeat them with `https://demo-reporting.salaxy.com/mcp`; for production, use `payroll.salaxy.com` and `reporting.salaxy.com`. Claude Desktop / claude.ai: ```text Settings → Connectors → Add → Add custom connector Name: Salaxy Payroll Demo URL: https://demo-payroll.salaxy.com/mcp Keep the suggested sign-in settings → Add → Connect, then sign in with your demo account ``` Claude Code: ```sh claude mcp add --transport http salaxy-payroll-demo https://demo-payroll.salaxy.com/mcp # then in Claude Code: /mcp → salaxy-payroll-demo → Authenticate ``` ChatGPT: ```text 1. Settings → Security and login → turn on Developer mode (Plus, Pro, Business, Enterprise or Edu plan) 2. Settings → Connectors → Create Name: Salaxy Payroll Demo MCP server URL: https://demo-payroll.salaxy.com/mcp Authentication: OAuth 3. Sign in with your demo account when ChatGPT asks 4. In a chat: + → More → Developer mode → Salaxy Payroll Demo ``` Codex: ```sh codex mcp add salaxy-payroll-demo --url https://demo-payroll.salaxy.com/mcp codex mcp login salaxy-payroll-demo ``` VS Code (.vscode/mcp.json): ```json { "servers": { "salaxy-payroll-demo": { "type": "http", "url": "https://demo-payroll.salaxy.com/mcp" } } } ``` Cursor (~/.cursor/mcp.json): ```json { "mcpServers": { "salaxy-payroll-demo": { "url": "https://demo-payroll.salaxy.com/mcp" } } } ``` Generic MCP config: ```json { "mcpServers": { "salaxy-payroll-demo": { "type": "http", "url": "https://demo-payroll.salaxy.com/mcp" } } } ``` Any client that supports **Streamable HTTP** and the MCP **OAuth sign-in** works: the client finds Salaxy's sign-in server from the MCP server and opens it in the browser. Salaxy's sign-in server accepts clients that publish their own identity (Client ID Metadata Documents), as Claude, ChatGPT and Codex do; it does not offer dynamic client registration. Menu names in Claude and ChatGPT change from time to time; if a step has moved, look for *Connectors* in Settings. ChatGPT also asks for **Developer mode**, because it treats custom connectors as third-party code. Name each connection after its agent, environment and country (`salaxy-payroll-demo`, `salaxy-reporting`) — when Sweden opens it will have servers of its own, and your agent should be able to tell them apart. **Microsoft Copilot:** Copilot Studio is not supported yet: it signs in with dynamic client registration or a client ID and secret entered by hand, which Salaxy's sign-in server does not offer to the public. ## Check it works After signing in, ask the agent to list what it can do with Salaxy. On the Payroll Agent you should see tools such as `employment_search`, `calculation_preview`, `calculation_create`, `payroll_create`, `absence_search` and `holiday_year_search`; on the Report Agent `salary_slip`, `summary_report`, `accounting_report` and `ir_reports`. The full list is in the [MCP reference](https://code.salaxy.com/reference/mcp.md). You are connected when: - the client asked you to sign in, in the browser, and then lists the tools; - asking what a monthly salary costs makes the agent call `calculation_preview` and answer with figures; - nobody asked you to paste a token or a password into the chat — see [MCP authentication](https://code.salaxy.com/security/mcp-authentication.md). **Interactive widgets:** The servers also expose **MCP Apps** widgets (`ui://` resources). Clients that support them render a salary slip or a report table as a Salaxy UI inside the chat; others show the text result. [Next: your first calculation →](https://code.salaxy.com/get-started/agentic/first-calculation.md) --- Source: https://code.salaxy.com/get-started/agentic/first-calculation.md # 2. Your first calculation With the Payroll Agent demo connected and signed in, ask in plain language — English or Finnish: > What does a monthly salary of 3 200 € for September 2026 cost the employer, and what is the net salary? The agent should call `calculation_preview`, which calculates **without saving anything**: ```json { "period": { "start": "2026-09-01", "end": "2026-09-30" }, "salaryDate": "2026-09-30", "rows": [ { "rowType": "monthlySalary", "count": 1, "price": 3200 } ] } ``` Without an `employmentId` it calculates for a generic employee. Give one (from `employment_search`) and the calculation uses that employee's real data: age, pension and insurance, tax card. ## Save it and show the payslip > Make that a salary calculation for one of my employees and show me the payslip. Now the agent finds the employee with `employment_search`, creates the calculation with `calculation_create` and shows the slip with `calculation_show_slip`. A calculation is saved as a draft: **nothing is paid** until a person approves the payment (`invoice_preview`, then `invoice_confirm`), and the demo never pays anything. ## What comes back The result carries the totals — gross salary, withholding tax, the employee's and the employer's contributions, net salary and the total cost to the employer. If something the calculation needs is missing — an address, an occupation code, a tax card — the result says so. A correct agent reads that before presenting anything as a finished payslip, and tells the user what is missing in business terms (*"the employee's address is missing"*). The payroll skills instruct agents to do exactly that. ## Try the hard ones Plain monthly salary is easy. Finnish payroll is mostly exceptions — try these and watch what the agent does **without** the skills: - *"Pay Erkki 45 € daily allowance for two days in Stockholm."* — a foreign daily allowance has its own rate by country and year. - *"Add a car benefit for Erkki's car."* — which kind? Does the employer pay the fuel? The age group of the car? - *"Pay my sole proprietorship's owner a salary of 2 000 €."* — the correct answer is **not to calculate**. Without domain knowledge a model will guess. That is what the skills are for. [Next: add the skills →](https://code.salaxy.com/get-started/agentic/skills.md) --- Source: https://code.salaxy.com/get-started/agentic/skills.md # 3. Add the skills The MCP tools say **what** can be done. The skills say **how to do it correctly** — and when not to do it at all. ## What the skills are A tree of Markdown files the agent reads before it calls a tool: ```text skills/ ├─ SKILL.md root router: picks the country, then the area; how to talk to the user, │ personal-data rules, integration context └─ fi/ Finland — one folder per country, like the MCP servers ├─ payroll-process/ the whole flow — statuses, what happens next (no tool) ├─ calculations/ building a calculation: the wage-type catalogue, one file per row type │ └─ references/ │ ├─ wage-types/ monthlySalary.md, overtime.md, carBenefit.md, … │ ├─ scope-and-eligibility.md when NOT to calculate │ └─ yearly-changing-numbers/ rates and limits by year └─ employments/ payrolls/ invoices/ reports/ settings/ absences/ holidays/ ``` The agent reads the root, picks the **country** — Finland is the only one today, and a request for another country is refused — then follows **one route** to an area (`/skills:fi:`), and opens a reference file only when the area's `SKILL.md` tells it to under a named condition. That keeps the always-read part small: building a single row typically costs about a third of what reading the whole catalogue would. Four things the skills carry that a model does not know by itself: - **The wage-type catalogue** — which row type fits a situation, its aliases in everyday Finnish, and the fields it needs. - **Refusals** — a large part of the content answers *should this calculation be made at all?* A sole proprietor paying themselves, volunteer work, international situations and public employers are out of scope, and the right answer is to say so. - **Guardrails** — never invent an amount, never guess a wage type, never invent an income-type code or an identifier, money is EUR. These live **in the skills**, so they hold even when a partner's agent loads the skills without Salaxy's agent instructions. - **Personal-data rules** — payroll data belongs to the employer and the employee, and some rows reveal health or union membership just by existing: the agent never writes the nature of an illness into a reply, never repeats a personal identity code in prose, and leaves the decision that pay is paid to a person. The skill content is in **Finnish for now** — it started in the domain language of Finnish payroll — and is **moving to English**. Identifiers, field names and enum values are already English, as in the API. The agent answers in the user's own language. ## Ways to get the skills | Way | Status | |---|---| | **The file tree** from the skills repository — give your agent file-read access and start at `skills/SKILL.md` | Today — below | | **A packaged plugin** for Claude clients | In preparation | | **Served by the MCP server itself**, as MCP resources the agent reads first — no separate install, and the skills always match the server | Proposed | | **OpenSharing**, as shared agent skills | Possible later | ## Use them The skills are a plain file tree today. Your agent needs **file-read access** to it and an instruction to start at `skills/SKILL.md`. ### Claude Code ```sh git clone https://github.com/salaxy-payroll/salaxy-ai-for-payroll cd salaxy-ai-for-payroll claude mcp add --transport http salaxy-payroll-demo https://demo-payroll.salaxy.com/mcp # then in Claude Code: /mcp → salaxy-payroll-demo → Authenticate # The reference agent is in Claude Code subagent format: mkdir -p .claude/agents && cp agents/payroll-agent.md .claude/agents/ claude ``` Then: *"Use the payroll-agent: pay Erkki a car benefit for September 2026 — it's a 2023 car, and we pay the fuel."* **Repository access:** The skills repository opens publicly soon. Until then, cloning needs access — ask your Salaxy contact. ### Your own agent Load `agents/payroll-agent.md` as the system prompt (or write your own — see the next step), give the model a file-read tool rooted at the repository, and connect the MCP server. That is exactly how the [evals](https://code.salaxy.com/reference/verified.md) run. ## What each area covers | Skill area | Status | MCP tools | Eval cases | |---|---|---|---| | Payroll process | Knowledge only | — | 2 / 2 pass | | Calculations | Live | `calculation_preview`, `calculation_create`, `calculation_set_rows`, `calculation_update`, `calculation_get_summary`, `calculation_show_slip`, `calculation_copy`, `calculation_search`, `row_type_list` | 35 / 37 pass | | Employments | Live | `employment_search`, `employment_get_summary`, `employment_create`, `employment_update`, `employment_set_rows` | 3 / 3 pass | | Payrolls | Live | `payroll_create`, `payroll_copy`, `payroll_set_employments`, `payroll_set_rows`, `payroll_update`, `payroll_remove_calculation`, `payroll_get_summary`, `payroll_show_slips`, `payroll_search` | 1 / 1 pass | | Invoices | Live | `invoice_search`, `invoice_get_summary`, `invoice_preview`, `invoice_confirm` | 1 / 1 pass | | Reports | Live | `salary_slip`, `salary_slip_pdf`, `summary_report`, `salary_summary`, `accounting_report`, `holiday_pay_debt`, `ir_reports`, `ir_report` | 0 / 2 pass | | Company settings | Coming soon | — | 0 / 1 pass | | Absences | Live | `absence_search`, `absence_get_summary`, `absence_set_periods` | 1 / 1 pass | | Holidays | Live | `holiday_spec_get_summary`, `holiday_spec_update`, `holiday_year_create`, `holiday_year_search`, `holiday_year_get_summary`, `holiday_year_set_accruals`, `holiday_year_set_leaves`, `holiday_year_update`, `holiday_year_recalculate` | 1 / 1 pass | Areas marked *In development* or *Coming soon* are written ahead of their public tools. On a server that lacks a tool the agent says it cannot do that *here*, names what should happen, and does not substitute another tool. It does not claim the action is impossible: the limit may be the environment's, not Salaxy's. [Next: build your own agent →](https://code.salaxy.com/get-started/agentic/build-your-agent.md) --- Source: https://code.salaxy.com/get-started/agentic/build-your-agent.md # 4. Build your own agent Partners embed payroll in their own software: an accounting system's assistant, an HR chat, a voice channel. You own the UI and the system prompt; Salaxy provides the tools and the skills. ## The contract: skills, not the agent file The repository contains a reference agent (`agents/payroll-agent.md`), but **your agent does not need it**. Everything that must hold in every implementation is in the skills themselves — including the guardrails: 1. Never invent an amount — ask. 2. Never guess a wage type. 3. Never invent an income-type code. 4. Never invent an identifier — a personal identity code, bank account number or reference number is asked for; a guessed one can belong to a real person. 5. Money is EUR. The skills also carry **rules for other people's payroll data** — never write the nature of an illness into a reply, never repeat a personal identity code in prose, and a person, not the agent, decides that pay is paid — and the **country boundary**: Finnish rules are never applied to another country's payroll. See [Privacy & AI compliance](https://code.salaxy.com/privacy/index.md) for the wider picture. If you write your own system prompt, keep it about your product: tone, who the users are, what your UI can show. Leave payroll rules to the skills. ## Pass your integration context Some answers depend on things your software knows and the user does not: which payment channel the payroll runs through, whether a paid calculation can still be corrected, whether a service fee is shown. Pass them in your system prompt: ```yaml integrationContext: partner: paymentChannel: nonCfa | cfa | manualSepa accountTiers: two | three userLevel: entrepreneur | professional ``` - **These are skill values, not API values.** `paymentChannel` here is the kind of channel the skills tell apart: `cfa` for a customer funds account (Salaxy pays), `manualSepa` for payment with a SEPA payment file, `nonCfa` for any other channel. It is not a value of the REST API's `PaymentChannel` enum. See [Payment channels](https://code.salaxy.com/integration/payment-channels.md). - **Every field is optional.** A missing field means the agent lists the alternatives — not that it assumes the most common one. - **A given field narrows the answer**: with `paymentChannel` known, the agent says what applies to *this* user. - **Context never relaxes checks.** It changes what the agent *says applies*, never what it *verifies*. `userLevel: professional` means less explanation, not fewer checks. ## Your users are not payroll professionals The first users are small-business owners in a chat. The skills are written for that: the agent asks the **business question**, not the field question — *"does the employer pay the fuel?"* rather than *"which `data.kind`?"* — and explains terms the first time it uses them. When the user is a professional, it explains less, and checks just as much. ## Don't send users to click The skills assume **the agent is the interface**. They do not tell the user to press buttons in a UI the agent cannot see. If an action is not possible through the tools — correcting a paid calculation, for example — the agent says so and names what has to happen. If your product does have a UI for it, add that to your system prompt. ## Verify The [eval suite](https://code.salaxy.com/reference/verified.md) drives an agent with the skills against the live tools and checks the result deterministically. It runs with **Salaxy's reference agent instructions** — your system prompt is a different configuration. Run the same cases with your prompt before you ship; each case is a JSON file with a prompt and the expected rows or the expected refusal. ## Going live The demo servers calculate on sample data. Real payroll uses the **production servers** — `https://payroll.salaxy.com/mcp` and `https://reporting.salaxy.com/mcp` — with the user's own Salaxy account; see [Connect a client](https://code.salaxy.com/get-started/agentic/index.md). The tools are the same, so an agent built on the demo carries over: change the address and sign in with a real account. --- Source: https://code.salaxy.com/get-started/rest/index.md # REST API — getting started [Finland] The REST API is the complete programmatic interface to **Finnish** payroll. It is not planned for other countries — they launch on [MCP](https://code.salaxy.com/get-started/agentic/index.md). **Before you start:** - **A test account** — step 1 creates one, free and self-service at [test.palkkaus.fi](https://test.palkkaus.fi). Its email and password get you a token while you develop. - **A REST client** — curl, Postman, Bruno or your own code. - **The test environment's address**, `test-secure.salaxy.com` — see [Environments](https://code.salaxy.com/get-started/environments.md). - **For production later:** a certificate for the [impersonation flow](https://code.salaxy.com/security/impersonation.md). Not needed for this guide. ## The guide Six steps from a fresh test account to a paid salary. Each page has the steps and the endpoints; the runnable samples are on the current developer site, linked from each step. | Step | What you do | |---|---| | [1. Create an account](https://code.salaxy.com/get-started/rest/create-account.md) | A test company in the test environment | | [2. Authenticate](https://code.salaxy.com/get-started/rest/authenticate.md) | An access token — the password flow while developing | | [3. Create employees](https://code.salaxy.com/get-started/rest/create-employees.md) | An employment for each person you pay | | [4. Create a payroll](https://code.salaxy.com/get-started/rest/create-payroll.md) | A payroll with a salary calculation built from the employment | | [5. Set for payment](https://code.salaxy.com/get-started/rest/set-for-payment.md) | Validate and commit — Salaxy generates the invoices | | [6. Track the payment status](https://code.salaxy.com/get-started/rest/track-status.md) | Poll until the payment is final | Before you start: [Environments](https://code.salaxy.com/get-started/environments.md). Along the way: [Payroll lifecycle and statuses](https://code.salaxy.com/integration/payroll-lifecycle.md). ## Reference - [REST API reference](https://code.salaxy.com/reference/rest-api.md) — interactive, from the OpenAPI document - OpenAPI document: [`/openapi/salaxy-03.json`](https://code.salaxy.com/openapi/salaxy-03.json) (OpenAPI 3.1, API version v03) - [Environments](https://code.salaxy.com/get-started/environments.md) — test, demo and production hosts - [Payroll lifecycle and statuses](https://code.salaxy.com/integration/payroll-lifecycle.md) — what happens after you send a payroll for payment, and what to poll for **Start on v03.** Salaxy API v03 is the current version. Salaxy API v04 is in beta: it may change, and it is not used in production yet. Build on v03, the current version. [Reference for v04 (beta)](https://code.salaxy.com/reference/rest-api-v04.md). ## More - Security: [REST authentication](https://code.salaxy.com/security/rest-authentication.md) — [password flow](https://code.salaxy.com/security/password.md), [impersonation for SSO](https://code.salaxy.com/security/impersonation.md), [federation for banks](https://code.salaxy.com/security/federation.md), [partner-initiated account creation](https://code.salaxy.com/security/account-creation.md) - Payroll: [invoices and payments](https://code.salaxy.com/integration/invoices-and-payments.md), [accounting data](https://code.salaxy.com/integration/accounting-data.md), [monthly cycle](https://code.salaxy.com/integration/monthly-cycle.md), [payroll lifecycle and statuses](https://code.salaxy.com/integration/payroll-lifecycle.md) - Integration: [overview](https://code.salaxy.com/integration/index.md), [partner and technical accounts](https://code.salaxy.com/integration/partner-account.md) - Customisation: [custom payroll logic](https://code.salaxy.com/docs/logic-intro) and the script editor stay on the current site --- Source: https://code.salaxy.com/get-started/environments.md # Environments Three environments serve the **REST API** and **embedded white label** (Finland). The MCP servers are listed [below](#mcp-servers). | Environment | REST API | Embedded white label | Use | |---|---|---|---| | Test | `test-secure.salaxy.com` | `test-embed.palkkaus.fi` | Latest development code; shares data with demo | | Demo | `demo-secure.salaxy.com` | `demo-embed.palkkaus.fi` | Stable code — build and test here; shares data with test | | Production | `secure.salaxy.com` | `embed.palkkaus.fi` | The live service, real data | - **Test and demo share the same data** — both are test sites. Data you create in one is visible in the other. Use test data only, never real people's data. - **Test** is where you build and test an integration; the examples on this site use it. It runs the latest development code, so new features reach it first. **Demo** runs stable code on the same data, so you can check your integration against it too. - **Production** is the live service with real data. Switch the hosts — API and embed together — when you go live. - The [OpenAPI document](https://code.salaxy.com/reference/rest-api.md) lists the production host, `secure.salaxy.com`, as its server. Swap in the test or demo host while you develop. ## Which host is which | Host | What it is | Used by | |---|---|---| | `*-secure.salaxy.com` · `secure.salaxy.com` | The Salaxy REST API and token endpoint | Your backend: [REST API](https://code.salaxy.com/get-started/rest/index.md), sign-in ([Security](https://code.salaxy.com/security/index.md)) | | `*-embed.palkkaus.fi` · `embed.palkkaus.fi` | The embedded payroll UI | Your web page's iframe: [Embedded white label](https://code.salaxy.com/white-label/how-it-works.md) | ## MCP servers The MCP servers are separate: **one server per Salaxy AI agent and country**, in two environments. Both need an OAuth sign-in in the browser. | Server | Demo | Production | Status | |---|---|---|---| | Finland, Payroll Agent | `https://demo-payroll.salaxy.com/mcp` | `https://payroll.salaxy.com/mcp` | [Live] | | Finland, Report Agent | `https://demo-reporting.salaxy.com/mcp` | `https://reporting.salaxy.com/mcp` | [Live] | | Finland, Configuration Agent · Data Agent | | | [Coming soon] | | Sweden | | | [Coming Q3 2027] | The demo servers use a free demo account and sample data; nothing real is paid or reported. Production uses your own Salaxy account. See [Connect a client](https://code.salaxy.com/get-started/agentic/index.md) and the [MCP reference](https://code.salaxy.com/reference/mcp.md). --- Source: https://code.salaxy.com/get-started/rest/create-account.md # 1. Create an account Before calling the API you need a Salaxy account. For development, create a **test company** in the test environment — it takes a few minutes and uses test data only. ## Choose a company Pick a real Finnish company or association (*oy*, *ky*, *avoin yhtiö*, *ry*) from the trade register at [ytj.fi](https://ytj.fi) — preferably one you are connected with. It is test data, so you do not need signing rights. Note its **business ID** (*Y-tunnus*). ## Create it in the test environment 1. Go to [test.palkkaus.fi](https://test.palkkaus.fi) and create a **company** — or an **accounting firm** (*PRO / tilitoimisto*) if you build for accounting firms. 2. Sign up with **email and password** (not Google, Microsoft or similar). 3. After the first verification, the test environment sends no emails. Verification is not required either, so a made-up address such as `yourname@example.com` works. ## Complete the onboarding wizard 1. **Personal identity code.** On the digital signature page, enter a made-up code `ddmmyy-nnn*`: a real date, any three digits, and `*` in place of the checksum. 2. **Signing.** To skip the signature, choose any authentication method **except "Testing ID"** — that one leads to an external test service that needs its own account. 3. **Ready.** Your test company is set up and you can use its web application. The test account works in both **test** and **demo** — they share the same data. ## Check - You can sign in to [test.palkkaus.fi](https://test.palkkaus.fi) as your test company. - The onboarding wizard is complete and the company's web application opens. - You have noted the company's business ID. **Screenshots:** The interactive version of this step — sign in and run it against your test account — is on the current developer site: [create account](https://code.salaxy.com/docs/create-account). The runnable samples stay there; the steps and endpoints are here. [2. Authenticate](https://code.salaxy.com/get-started/rest/authenticate.md) → --- Source: https://code.salaxy.com/get-started/rest/authenticate.md # 2. Authenticate Every API call carries an **access token** as a Bearer token. While developing, get one with your test account's email and password: ```http POST https://test-secure.salaxy.com/oauth2/token Content-Type: application/json { "grant_type": "password", "username": "you@example.com", "password": "your-password" } ``` The response's `access_token` goes into the `Authorization` header of every call in the next steps: ```http Authorization: Bearer eyJhbGciOi... ``` - The **password flow is for development only** — enabled in the test environments. Details: [Password flow](https://code.salaxy.com/security/password.md). - **In production, use the [impersonation flow](https://code.salaxy.com/security/impersonation.md)**: your server signs a JWT with its certificate and gets a token for the customer account. - Tokens currently last 48 hours, and there are no refresh tokens — see [Tokens](https://code.salaxy.com/security/rest-authentication.md#tokens). ## Test your connection Before building anything, check that the token works. The session endpoint answers every request and tells you whether it was authorised: ```http GET https://test-secure.salaxy.com/v03/api/session/current Authorization: Bearer eyJhbGciOi... ``` The response, trimmed to what matters here: ```json { "isAuthorized": true, "currentAccount": { "id": "", "avatar": { "displayName": "Your Test Company Oy" } } } ``` - **`isAuthorized: true`** — the token works, and `currentAccount` is the company you act as. - **`isAuthorized: false`** — the token was not accepted. Check that the header is `Bearer` followed by a space and the token, that the token comes from the same environment (`test-secure`), and that it is not older than 48 hours. ## Check - `POST /oauth2/token` returns an `access_token`; a wrong password returns an error, not a token. - Every later call sends `Authorization: Bearer `. - The token is not in source control or in your logs. - Test credentials are used only with `test-secure.salaxy.com`. **Runnable sample:** The interactive version of this step — sign in and run it against your test account — is on the current developer site: [api authentication](https://code.salaxy.com/docs/api-authentication). The runnable samples stay there; the steps and endpoints are here. ← [1. Create an account](https://code.salaxy.com/get-started/rest/create-account.md) · [3. Create employees](https://code.salaxy.com/get-started/rest/create-employees.md) → --- Source: https://code.salaxy.com/get-started/rest/create-employees.md # 3. Create employees In the API, an employee is an **employment relationship** — *employment* for short: one worker and one employer, carrying the payroll terms. See [Core concepts](https://code.salaxy.com/about/concepts.md#worker-and-employment-are-different-things). Examples use the **test** environment (`test-secure.salaxy.com`); see [Environments](https://code.salaxy.com/get-started/environments.md) for demo and production. ## The endpoint | Method | Endpoint | Does | |---|---|---| | `POST` | `/v03/api/employments` | Creates the employment — and the worker record, if the person is new | ## The request ```json { "identity": { "firstName": "Pauliina", "lastName": "Palkkanen", "personalId": "190372-942M", "language": "fi" }, "contacts": [ { "type": "default", "street": "Ansionkatu 1", "postalCode": "01337", "city": "PALKKALA", "email": "pauliina.palkkanen@example.com", "telephone": "+358401234567890" } ], "info": { "type": "monthlySalary", "pensionCalculation": "employee", "pensionRule": "default", "ibanNumber": "FI3718834100118709", "taxcard": "auto", "startDate": "2023-11-15", "sourceId": "ID98765432" }, "work": { "description": "Chief care of Fifi", "occupationCode": "51640", "wageBasis": "monthly", "monthlyHours": 160, "salaryDefaults": [ { "rowType": "monthlySalary", "count": 1, "price": 3000 }, { "rowType": "phoneBenefit", "count": 1, "price": 20 } ] } } ``` | Field | Why it matters | |---|---| | `info.taxcard: "auto"` | The tax card is fetched automatically from the Tax Administration | | `work.occupationCode` | Required for Incomes Register reporting — a code from [Statistics Finland's classification of occupations](https://stat.fi/fi/luokitukset/ammatti/) (here 51640, animal carers) | | `work.description` | Shown on the salary slip | | `work.salaryDefaults` | Rows every calculation for this employment starts with — a salary, or recurring items such as a phone benefit | | `info.sourceId` | Your own id for the employment | | `work.wageBasis`, `work.monthlyHours` | Optional. `wageBasis` follows `info.type`, and `monthlyHours` the company's default; give them only when the default does not fit | **Temporary identity codes need an address:** The sample's identity code, `190372-942M`, has an individual number of 900 or more — a **temporary** identity code. For those, the worker's street, postal code and city are **required before a calculation validates**. The employment is created either way, so leaving the address out fails later, not here. ## After the call The response is the saved employment, trimmed here: ```json { "id": "", "info": { "workerAccountId": "", "startDate": "2023-11-15" } } ``` **Store `info.workerAccountId` from the response.** It identifies the worker record Salaxy created for this person. Send it back on any further employment for the same person — otherwise you get a duplicate worker record. **Save for the next step:** - `id` — the employment, to build the calculation from in [step 4](https://code.salaxy.com/get-started/rest/create-payroll.md). - `info.workerAccountId` — the worker, for the calculation and for any further employment of the same person. ## Check - `POST /v03/api/employments` returns the employment with its `id`. - You stored `info.workerAccountId` for the next employment of the same person. - The employment has an occupation code — and, for a temporary identity code, a street address. - Searching by your own id finds it: `$filter=externalId eq ''`. **Runnable sample:** The interactive version of this step — sign in and run it against your test account — is on the current developer site: [create employees](https://code.salaxy.com/docs/create-employees). The runnable samples stay there; the steps and endpoints are here. ← [2. Authenticate](https://code.salaxy.com/get-started/rest/authenticate.md) · [4. Create a payroll](https://code.salaxy.com/get-started/rest/create-payroll.md) → --- Source: https://code.salaxy.com/get-started/rest/create-payroll.md # 4. Create a payroll A **payroll** groups the salary calculations paid on one date. In this step you create a payroll, build a calculation for the employee from their employment, and add it to the payroll. Examples use the **test** environment (`test-secure.salaxy.com`); see [Environments](https://code.salaxy.com/get-started/environments.md) for demo and production. ## The endpoint sequence | # | Method | Endpoint | Does | |---|---|---|---| | 1 | `POST` | `/v03/api/payroll` | Creates the payroll | | 2 | `GET` | `/v03/api/employments?$filter=otherPartyInfo/officialId eq '190372-942M'` | Finds the employment by the worker's identity code | | 3 | `GET` | `/v03/api/employments/{id}` | Reads the full employment | | 4 | `POST` | `/v03/api/calculations/update-from-employment?save=false&updateRows=true` | Fills a calculation from the employment — its default salary rows and other employment data — without saving | | 5 | `POST` | `/v03/api/calculations` | Saves the calculation | | 6 | `POST` | `/v03/api/payroll/add-calc?ids={calculation ids}` | Adds the calculations to the payroll | ## 1. The payroll ```json { "input": { "title": "Payroll August 2025", "period": { "start": "2025-08-01", "end": "2025-08-31", "daysCount": 21 }, "salaryDate": "2025-08-31", "wageBasis": "monthly", "paymentChannel": "palkkausManual", "calculations": [] }, "info": {}, "calcs": [], "validations": [], "workflowData": {} } ``` `paymentChannel` decides how the money moves; `palkkausManual` is for trying things out, and a real integration uses the channel set up for it. The response is the new payroll: ```json { "id": "", "info": { "status": "draft", "isReadyForPayment": false }, "input": { "title": "Payroll August 2025", "calculations": [] } } ``` **Save for the next step:** - `id` — the payroll, for adding calculations below and for committing it in [step 5](https://code.salaxy.com/get-started/rest/set-for-payment.md). ## 2–3. Find the employment The list query returns a page of rows (`items`); take the first row's `id` and read the full employment with `GET /v03/api/employments/{id}`. You need its `id` and `info.workerAccountId`. If you stored both in [step 3](https://code.salaxy.com/get-started/rest/create-employees.md), skip this. ## 4–5. The calculation, filled from the employment Post this to `update-from-employment`: ```json { "workflow": { "status": "payrollDraft" }, "employer": { "isSelf": true }, "worker": { "employmentId": "", "accountId": "" } } ``` `update-from-employment` returns the calculation with the employment's default salary rows and settings. Post that result, unchanged, to `POST /v03/api/calculations` to save it. The saved calculation comes back with its id, its status and the calculated totals: ```json { "id": "", "workflow": { "status": "payrollDraft" }, "result": { "totals": { "totalGrossSalary": 3000 } } } ``` Its status `payrollDraft` means *a draft that belongs to a payroll* — see [Payroll lifecycle and statuses](https://code.salaxy.com/integration/payroll-lifecycle.md#salary-calculation). **Save for the next step:** - `id` — the calculation, to add to the payroll below, and to follow its payment in [6. Track the payment status](https://code.salaxy.com/get-started/rest/track-status.md). ## 6. Add it to the payroll Post the payroll (the response from section 1) to `add-calc`, with the calculation ids comma-separated in `ids`. Salaxy adds them to `input.calculations` and saves the payroll. The payroll stays `draft`, now with its calculations — ready to be sent for payment. The response is the updated payroll: ```json { "id": "", "info": { "status": "draft", "isReadyForPayment": true }, "input": { "calculations": [""] } } ``` `info.isReadyForPayment: true` means every calculation validates. If it is `false`, read the payroll's `validations` before going on. ## Check - The payroll's `input.calculations` contains your calculation's id. - The calculation's status is `payrollDraft`. - `POST /v03/api/payroll/validate` returns no errors — or only ones you understand and can fix. **Runnable sample:** The interactive version of this step — sign in and run it against your test account — is on the current developer site: [create payroll](https://code.salaxy.com/docs/create-payroll). The runnable samples stay there; the steps and endpoints are here. ← [3. Create employees](https://code.salaxy.com/get-started/rest/create-employees.md) · [5. Set for payment](https://code.salaxy.com/get-started/rest/set-for-payment.md) → --- Source: https://code.salaxy.com/get-started/rest/set-for-payment.md # 5. Set for payment Committing is where **editing stops and paying starts**: - Every calculation in the payroll, and the payroll itself, moves to `paymentStarted`. - Salaxy **generates the invoices** — you never create them. The worker's `net` invoice is released to the payment channel as `unread`; the periodic `tax` and `union` invoices are prepared as `preview`. - From here the payment moves on in the payment channel, and you follow it through statuses — [step 6](https://code.salaxy.com/get-started/rest/track-status.md). Examples use the **test** environment (`test-secure.salaxy.com`); see [Environments](https://code.salaxy.com/get-started/environments.md) for demo and production. ## The endpoints | Method | Endpoint | Does | |---|---|---| | `POST` | `/v03/api/payroll/validate` | Pre-check: returns per-calculation validation errors | | `POST` | `/v03/api/invoices/create-for-payroll/{channel}/{payrollId}` | **Commits the whole payroll.** Returns the generated invoices | | `POST` | `/v03/api/invoices/create-by-id/{channel}` | Commits only some calculations — body: an array of calculation ids, e.g. to re-submit one after a cancellation | - `channel` — the payment channel code: `palkkausManual` in this guide; a real integration uses the channel provisioned for it. - Prefer `create-for-payroll` for the normal case: `create-by-id` does not validate or stamp dates on the payroll as a whole. The commit returns the generated invoices, trimmed here — the worker's `net` invoice released to the channel, and a periodic `tax` invoice in preview: ```json [ { "id": "", "header": { "type": "net", "status": "unread", "payrollId": "" } }, { "id": "", "header": { "type": "tax", "status": "preview", "payrollId": "" } } ] ``` **Save for the next step:** - The **calculation ids** from step 4 — the calculation is what you follow in [step 6](https://code.salaxy.com/get-started/rest/track-status.md), not the invoice. - If you run the payment channel yourself, the invoices are what it pays: see [Payroll lifecycle and statuses](https://code.salaxy.com/integration/payroll-lifecycle.md). ## What can be committed - **The payroll must validate.** Every calculation must be ready for payment — `info.isReadyForPayment` is `true` on the saved payroll. If it is not, the commit returns **400** with `error` and `messageHtml` (localised texts). **Validate first**: `payroll/validate` gives the per-calculation errors that the 400 body does not. - **Calculations commit from their editable statuses:** `draft`, `payrollDraft`, `proDraft`, `waitingApproval`, `sharedApproved`. A `paymentStarted` calculation cannot be committed again, and a `paymentSucceeded` one is never paid twice — corrections to paid salaries go through Salaxy support. For the whole flow after this point — invoices, timings, cancelling — see [Payroll lifecycle and statuses](https://code.salaxy.com/integration/payroll-lifecycle.md). ## Check - You validated the payroll before committing. - After the commit, the payroll and its calculations are `paymentStarted`, and the response lists the generated invoices. - Your code never commits the same payroll twice without checking its status first. **Runnable sample:** The interactive version of this step — sign in and run it against your test account — is on the current developer site: [set for payment](https://code.salaxy.com/docs/set-for-payment). The runnable samples stay there; the steps and endpoints are here. ← [4. Create a payroll](https://code.salaxy.com/get-started/rest/create-payroll.md) · [6. Track the payment status](https://code.salaxy.com/get-started/rest/track-status.md) → --- Source: https://code.salaxy.com/get-started/rest/track-status.md # 6. Track the payment status After [setting a payroll for payment](https://code.salaxy.com/get-started/rest/set-for-payment.md), the payment progresses in the payment channel. You read the progress back from the API. **The mechanism is polling.** There are no webhooks or push notifications today. Poll every few minutes — status changes follow banking-day events, not seconds. ## What to watch - **The salary calculation is the unit of truth.** Each has its own `workflow.status`; one worker's payment succeeds or fails independently of the others. - **The payroll status is derived.** It reaches `paymentSucceeded` only when *every* calculation has succeeded. Use it as a summary. ## Read endpoints | Endpoint | Returns | Use for | |---|---|---| | `GET /v03/api/calculations/{id}` | The full calculation; read `workflow.status` | Following one salary | | `GET /v03/api/calculations?$filter=status eq 'paymentStarted'` | A page of rows (`items`, `nextPageLink`) with `id`, `status`, `updatedAt` … | Sweeping all payments in flight in one query | | `GET /v03/api/payroll/{id}` | The payroll; read `info.status` | The pay event as a whole | The list query returns a page of rows: ```json { "items": [ { "id": "", "status": "paymentStarted", "updatedAt": "2025-08-29T10:15:00Z" } ], "nextPageLink": null } ``` Match statuses in lowerCamelCase — `paymentSucceeded`, not `PaymentSucceeded`. For paging, follow `nextPageLink` and avoid `$top`; query syntax: [Queries and paging](https://code.salaxy.com/reference/queries.md). ## Statuses you will see | Calculation status | Meaning | Final? | |---|---|---| | `paymentStarted` | Committed; the payment is in flight | No — keep polling | | `paymentSucceeded` | The channel has confirmed the payment — **paid** | Yes | | `paymentCanceled` | Cancelled by Salaxy after payment | Yes | | `paymentError` | The payment failed — needs manual attention | Yes | | `payrollDraft` or `draft` | Back to a draft: the payment was cancelled before it was paid. Edit and commit it again | Not a payment outcome — stop polling until it is committed again | **Only `paymentSucceeded` means paid.** Do not infer payment from anything else — `paymentStarted` does not mean paid. Cancelling before payment is in [Payroll lifecycle and statuses](https://code.salaxy.com/integration/payroll-lifecycle.md#cancelling-a-payment). **Customer funds account channels are the exception.** When Salaxy pays from a customer funds account, `paymentSucceeded` means Salaxy has received the employer's funds. Salaxy pays the worker after that. See [Payroll lifecycle and statuses](https://code.salaxy.com/integration/payroll-lifecycle.md#customer-funds-account-channels). ## A polling pattern 1. When you commit, record the calculation ids — or rely on the `status eq 'paymentStarted'` query. 2. Poll on a fixed interval, batching with the list query rather than one `GET` per calculation. 3. When a calculation reaches a final status, update your records and stop polling it. 4. **Alert on calculations that stay `paymentStarted`** longer than your channel normally takes. Salaxy never times a payment out — a stuck payment is yours to resolve: cancel and re-commit, or fix it in your own system. 5. Optionally read the payroll to close the pay event once `info.status` is `paymentSucceeded`. ## Check - Polling uses the list query and follows `nextPageLink`. - Only `paymentSucceeded` is treated as paid. - An alert fires when a payment stays `paymentStarted` longer than your channel normally takes. ## Next - [Payroll lifecycle and statuses](https://code.salaxy.com/integration/payroll-lifecycle.md) — the whole flow, including invoices and cancelling. - The payment channel side — fetching invoices and reporting them paid, which drives these statuses: [Invoices and payments](https://code.salaxy.com/integration/invoices-and-payments.md). ← [5. Set for payment](https://code.salaxy.com/get-started/rest/set-for-payment.md) --- Source: https://code.salaxy.com/get-started/test-account.md # Get a test account Every path starts with a credential you can use without risk. Which one depends on how you build. Test and demo share the same test data, so nothing you do here touches real people or real money. Examples use the **test** environment; see [Environments](https://code.salaxy.com/get-started/environments.md) for demo and production. | Path | Credential | How fast | |---|---|---| | [Agentic](#agentic-mcp-and-skills) | Free demo account | Two minutes | | [REST API](#rest-api) | Test company account | A few minutes | | [Embedded white label](#embedded-white-label) | The same test company account | A few minutes | | [Partner integration](#partner-integration) | Partner account and technical account, with a certificate | Set up with Salaxy | ## Agentic: MCP and skills You need a **free demo account**. You sign in in the browser when you connect your client to a demo MCP server, so you never paste a password or a token into a chat. The demo uses sample data: nothing real is paid or reported. Follow [Connect a client](https://code.salaxy.com/get-started/agentic/index.md). The tools are the same in demo and production, so what you build carries over. ## REST API You need a **test company account** in the test environment. It takes a few minutes and uses test data only. 1. Pick a real Finnish company or association from the trade register at [ytj.fi](https://ytj.fi) and note its business ID. It is test data, so you do not need signing rights. 2. Create a company, or an accounting firm if you build for accounting firms, at [test.palkkaus.fi](https://test.palkkaus.fi). Sign up with **email and password**, not Google or Microsoft. 3. Complete the onboarding wizard: enter a made-up personal identity code `ddmmyy-nnn*` (a real date, any three digits and `*` for the checksum), then choose any authentication method **except "Testing ID"**. After the first verification the test environment sends no emails, and verification is not required, so a made-up address such as `yourname@example.com` works. Full steps: [1. Create an account](https://code.salaxy.com/get-started/rest/create-account.md). Then get an access token with the password flow: [2. Authenticate](https://code.salaxy.com/get-started/rest/authenticate.md). The token lasts 48 hours and has no refresh token; see [Tokens](https://code.salaxy.com/security/rest-authentication.md#tokens). ## Embedded white label You need the same **test company account** as the REST API path, and an access token from the password flow. The embedded UI needs the token only on its first load, in the URL hash. Follow [Create an account](https://code.salaxy.com/get-started/rest/create-account.md), then [Embedded white label: quick start](https://code.salaxy.com/get-started/white-label/index.md). In production your backend gets the token through [impersonation](https://code.salaxy.com/security/impersonation.md) instead. ## Partner integration A partner serves many customer companies, so a single test company is not enough. You need: - a **partner account** and one or more **technical accounts** for the test environment, set up together with Salaxy; - a **digital certificate** for the technical account. You create it yourself in the Salaxy web application under *Settings → Authorisations*, and your server uses it to sign the JWT it exchanges for an access token. The **trusted partner** role, which lets your system create customer accounts, is not needed in test. It is required in production; see [Partner-initiated account creation](https://code.salaxy.com/security/account-creation.md). Keep the private key in your backend secret store. Never ship it to a browser or commit it to git. A test certificate works only in test and demo, and a production certificate only in production, so create one per environment. What to ask Salaxy, and when, is in [Support](https://code.salaxy.com/get-started/support.md). The setup topics are in [Partner and technical accounts](https://code.salaxy.com/integration/partner-account.md). ## Check - You can sign in to the test environment, or your MCP client lists the demo tools. - You have an access token and one authenticated call succeeds. - You know which environment each credential belongs to. --- Source: https://code.salaxy.com/get-started/faq.md # Developer FAQ Each answer is short and links to the page that holds the facts. Examples use the **test** environment; see [Environments](https://code.salaxy.com/get-started/environments.md) for demo and production. If your question is not here, see [Support](https://code.salaxy.com/get-started/support.md). ## Accounts and environments **How do I get a test account?** Create a test company at [test.palkkaus.fi](https://test.palkkaus.fi) with email and password. It takes a few minutes. See [Get a test account](https://code.salaxy.com/get-started/test-account.md). **Do I need a real email address?** No. After the first verification the test environment sends no emails, and verification is not required. See [Create an account](https://code.salaxy.com/get-started/rest/create-account.md). **Is data in test also in demo?** Yes. Test and demo share the same data. Production is separate. See [Environments](https://code.salaxy.com/get-started/environments.md). **Which environment should I build against?** Test. It runs the latest development code, and the examples on this site use it. Demo runs stable code on the same data, so you can check your integration there too. See [Environments](https://code.salaxy.com/get-started/environments.md). ## Authentication **How long does an access token last?** 48 hours, with no refresh token. Repeat the grant when it expires. See [Tokens](https://code.salaxy.com/security/rest-authentication.md#tokens). **Why does the token call fail with "not allowed to impersonate account"?** The customer company has not authorised your partner account. For example, it may have been created under another partner. Create it through partner-initiated account creation, or ask Salaxy. See [Impersonation](https://code.salaxy.com/security/impersonation.md) and [Partner-initiated account creation](https://code.salaxy.com/security/account-creation.md). **Does my test certificate work in production?** No. A test certificate works only in test and demo. Create a separate certificate for production. See [Get a test account](https://code.salaxy.com/get-started/test-account.md#partner-integration). ## API behaviour **Which API version should I use?** Start on the version the note below names. See [Versions and changes](https://code.salaxy.com/reference/versions.md) for how the versions differ. **Start on v03.** Salaxy API v03 is the current version. Salaxy API v04 is in beta: it may change, and it is not used in production yet. Build on v03, the current version. [Reference for v04 (beta)](https://code.salaxy.com/reference/rest-api-v04.md). **Why does a status query return an empty list although the invoice exists?** `GET /v03/api/payment-channel/{channel}/status/{status}` without `start` and `end` covers only the last 14 days. It returns `200` with an empty list, not an error. Pass an explicit date range for reconciliation and catch-up. See [Invoices and payments](https://code.salaxy.com/integration/invoices-and-payments.md). **Why does a payment channel call answer `400` with a customer company token?** Payment channel calls answer only to the account that owns the channel, normally your technical account. Any other account gets `400`. Use the owner account's token. See [Payment channels](https://code.salaxy.com/integration/payment-channels.md). **How do I retry a failed create safely?** The REST API has no general idempotency key. Set your own id on what you create and search for it before you create again. See [Retries and idempotency](https://code.salaxy.com/reference/idempotency.md). **How do I read an error?** See [Errors](https://code.salaxy.com/reference/errors.md). ## Embedded white label **Why did my embedded session end?** After the first load, change only what comes after the `#` in the iframe URL. Changing anything before it restarts the application and ends the session. See [URL parameters and sizing](https://code.salaxy.com/white-label/url-parameters.md). ## Help **What do I ask Salaxy for, and what can I do myself?** See [Support](https://code.salaxy.com/get-started/support.md). --- Source: https://code.salaxy.com/get-started/support.md # Support **Draft:** The support channels on this page are being confirmed. Until then, use the contact address below for everything. ## Where to ask | You need | Where | |---|---| | Help with the REST API, the MCP servers, the skills or embedded white label | **[contact@salaxy.com](mailto:contact@salaxy.com)** — say it is a developer question | | A commercial agreement, partnership or demo | [salaxy.com](https://www.salaxy.com) | | To check whether something is a known issue first | [Availability](https://code.salaxy.com/about/availability.md) | ## What you set up yourself, and what you ask for | | Self-service | Ask Salaxy | |---|---|---| | Test company account | [Create an account](https://code.salaxy.com/get-started/rest/create-account.md) in the test environment | — | | Access token for development | [Password flow](https://code.salaxy.com/security/password.md) | — | | Signing certificate for single sign-on | In the Salaxy web application, *Settings → Authorisations* — see [Impersonation](https://code.salaxy.com/security/impersonation.md) | — | | Password flow in production | — | Manual registration | | **Trusted partner** role (account creation from your system) | Not needed in test | Required in production — [Account creation](https://code.salaxy.com/security/account-creation.md) | | **Federation provider** role (banks, payment providers) | Any account in test, for now | Contract and role — [Federation](https://code.salaxy.com/security/federation.md) | | A **payment channel** for your integration | `palkkausManual` for trying things out | Your production channel | | **Embedded white label** design | — | Salaxy implements your design as part of the partnership — [Designs](https://code.salaxy.com/white-label/designs.md) | | Access to the **MCP servers** | Browser sign-in: a free demo account for the demo servers, your Salaxy account for production — see [MCP authentication](https://code.salaxy.com/security/mcp-authentication.md) | — | | The **sub-processor list** | — | Given to commercial partners — [GDPR roles](https://code.salaxy.com/privacy/gdpr.md) | ## Reporting a problem Include what someone needs to reproduce it — and **nothing that identifies a real person**: - **Environment and host** — test, demo or production (`test-secure.salaxy.com` …), see [Environments](https://code.salaxy.com/get-started/environments.md). - **When** — date and time, with the time zone. - **What you called** — method and path, or for MCP the client and the tool name. - **What came back** — the HTTP status and the full error body (`error`, `messageHtml`, `validation`), see [Errors](https://code.salaxy.com/reference/errors.md). - **The request** — the body, with personal identity codes, names, bank accounts and salaries removed or replaced by test values. - **Your account id** and, where relevant, the calculation or payroll id. - **What you expected** instead. **Never send credentials:** Do not put an access token, password, private key or certificate in a support message, an issue or an AI chat. If one has leaked, create a new one and tell Salaxy. ## Security issues Report a suspected vulnerability privately to [contact@salaxy.com](mailto:contact@salaxy.com) and do not publish details until Salaxy has replied. Include the same facts as for a bug — without real personal data. --- Source: https://code.salaxy.com/integration/index.md # Integration overview An integration has two parts: a **build path**, which decides who builds the user interface, and the **integration topics**, which you work through in order. Each topic page starts with an overview, then shows the options under "Which fits you?". Skip the options that do not apply to you. ## Choose your build path *Diagram: Two build paths side by side. Embedded Salaxy UI: Salaxy Business for companies and Salaxy Pro for accounting firms run inside your product, in an iframe or opened from it with single sign-on; less work. Your own UI: you build the screens on the REST API; more work. In both paths the Salaxy payroll engine does the calculation, the payments and the Incomes Register filing. Under it, your payment channel can fetch the invoices, pay them and report back. (Purple: Salaxy builds it. Grey: you build it. The payroll engine is the same in both paths; the payment channel is optional in each.)* | | 1. Embedded Salaxy UI | 2. Your own UI | |---|---|---| | **Who builds the UI** | Salaxy: **Salaxy Business** for companies and **Salaxy Pro** for accounting firms, in an iframe in your product under your own design, or at least opened from your product with single sign-on | You, on the REST API | | **What you build** | Single sign-on for your users, customer account creation (and accounting firm accounts for Salaxy Pro), and usually a payment channel and the monthly accounting data pull. Employees and payrolls are done in the Salaxy UI | Every payroll screen: customer onboarding, employments, payrolls and calculations, and the payment status. Salaxy's onboarding screens can handle the company's sign-up | | **Effort** | Less | More | | **Example** | A property management, accounting or financial management system that adds payroll for its customers and their accounting firms | A financial or HR app with its own payroll screens | | **Start with** | [Embedded white label](https://code.salaxy.com/white-label/index.md) | [REST API — getting started](https://code.salaxy.com/get-started/rest/index.md) | Both paths are **Finland only**. For other countries, and for anything conversational, use the agentic path: see [MCP or REST?](https://code.salaxy.com/about/mcp-or-rest.md). An agent can also do a single job inside either path — for example, a payroll assistant inside your product. **Paths can be combined.** For example, an embedded integration also imports workers or worktime through the API ([Worktime import](https://code.salaxy.com/integration/worktime-import.md)), or your own UI covers some tasks and the embedded Salaxy UI the rest. Salaxy Pro also works standalone: accounting firms sign in to it directly. That is not an integration, so it is not a build path here. ## What every integration needs Salaxy sets these up with you once, before you build. Each has its own topic page. | Item | Who does what | Topic | |---|---|---| | Partner account and technical accounts | Salaxy creates them; you create the certificate your backend signs with | [Partner and technical accounts](https://code.salaxy.com/integration/partner-account.md) | | Service model | Salaxy sets it up: what the customer companies you bring get, and what is locked | [Service models](https://code.salaxy.com/integration/service-models.md) | | Payment channel | Salaxy pays from a customer funds account, or your channel pays; you build your channel | [Payment channels and SEPA payment files](https://code.salaxy.com/integration/payment-channels.md) | | Accounting model | Salaxy sets it up: where the accounting entries go | [Accounting models](https://code.salaxy.com/integration/accounting-models.md) | ## Partner or company? - **Partner:** you serve many customer companies, often through their accounting firms. You need the one-time setup topics below. If accounting firms sit between you and the companies (three-tier), you also need the [Pro API](https://code.salaxy.com/integration/pro-api.md) for the accounting firm view. - **Company:** you connect your own systems to your own Salaxy account. You can skip most of the one-time setup. ## Integration topics The topics are in the order an integration usually goes. Some topics say which build paths need them; the others apply to every path. Building with a coding agent? Start with [Integration in a day with a coding agent](https://code.salaxy.com/integration/with-a-coding-agent.md). **1. Setup and onboarding (one-time)** - [Partner and technical accounts](https://code.salaxy.com/integration/partner-account.md) — your partner account, technical accounts and certificate - [Account structure](https://code.salaxy.com/integration/account-structure.md) — partner → company, partner → accounting firm → company, or mixed - [Contract options](https://code.salaxy.com/integration/contract-options.md) — how a customer company authorises Salaxy - [Service models](https://code.salaxy.com/integration/service-models.md) — what Salaxy fixes for the companies you bring - [Payment channels and SEPA payment files](https://code.salaxy.com/integration/payment-channels.md) — who pays the salaries, and how - [Accounting models](https://code.salaxy.com/integration/accounting-models.md) — where the accounting entries go - [Customer account creation](https://code.salaxy.com/integration/customer-accounts.md) — create or assure a customer company account - [Company settings](https://code.salaxy.com/integration/company-settings.md) — for your own UI; the Salaxy UIs have their own settings screens - [Accounting firm account creation](https://code.salaxy.com/integration/accounting-firm-accounts.md) — an accounting firm account, with its customer companies under it - [Pro API (accounting firm tier)](https://code.salaxy.com/integration/pro-api.md) — one view over every customer company of an accounting firm **2. People** — for your own UI; in the Salaxy UIs, employees are kept on screen, unless you import them - [Employees and employments](https://code.salaxy.com/integration/employments.md) - [Tax cards](https://code.salaxy.com/integration/tax-cards.md) - [Dimensions (cost centres)](https://code.salaxy.com/integration/dimensions.md) - [Worktime import](https://code.salaxy.com/integration/worktime-import.md) **3. Payroll** - [Payroll lifecycle and statuses](https://code.salaxy.com/integration/payroll-lifecycle.md) - [Salary calculations](https://code.salaxy.com/integration/calculations.md) — for your own UI; in the Salaxy UIs, payroll is done on screen **4. Payments** - [Invoices and payments](https://code.salaxy.com/integration/invoices-and-payments.md) **5. Reporting and filings** - [Accounting data](https://code.salaxy.com/integration/accounting-data.md) - [Holiday pay debt](https://code.salaxy.com/integration/holiday-pay-debt.md) - [Monthly cycle](https://code.salaxy.com/integration/monthly-cycle.md) — the reports and invoices Salaxy makes each month - [Incomes Register filing](https://code.salaxy.com/integration/incomes-register.md) — earnings payment reports, which Salaxy files for you **6. Optional features** - [Salary slips and e-payslips](https://code.salaxy.com/integration/salary-slips.md) - [Messages and notifications](https://code.salaxy.com/integration/messages-and-notifications.md) — message threads, and the notice to the worker after payment - [Events from the embedded white label](https://code.salaxy.com/white-label/events.md) — what the payroll UI tells your page **7. Go live** - [Go-live checklist](https://code.salaxy.com/integration/go-live.md) ## The API rules Every REST integration follows the same rules for [errors](https://code.salaxy.com/reference/errors.md), [queries and paging](https://code.salaxy.com/reference/queries.md), [retries and idempotency](https://code.salaxy.com/reference/idempotency.md), and [events and polling](https://code.salaxy.com/reference/polling.md). They are in the Reference, next to the [REST API reference](https://code.salaxy.com/reference/rest-api.md). --- Source: https://code.salaxy.com/integration/with-a-coding-agent.md # Integration in a day with a coding agent This site is written so that a coding agent can plan your integration from it. You give the agent the address, it reads the site and asks you the decisions only you can make, and you test the result against the test environment. Examples use the **test** environment; see [Environments](https://code.salaxy.com/get-started/environments.md) for demo and production. *Diagram: A flow of five steps. You, the developer, give the address code.salaxy.com to your coding agent. The agent reads the Salaxy developer site: llms.txt, the integration topics and the OpenAPI files. It then plans and writes the code, and the code runs against the Salaxy test environment. The agent asks you the decisions along the way. (You give the address, the agent reads the site and asks you the choices, and the code runs against the test environment.)* ## What the agent reads | Source | What it holds | |---|---| | [`/llms.txt`](https://code.salaxy.com/llms.txt) | The index of the site, one line per page, with instructions for agents planning an integration | | [`/llms-full.txt`](https://code.salaxy.com/llms-full.txt) | Every page in one Markdown file | | `.md` | Each page as Markdown: the page's URL with `.md` added | | [Integration overview](https://code.salaxy.com/integration/index.md) | The build paths and the topics in the order an integration usually goes | | [`/openapi/salaxy-03.json`](https://code.salaxy.com/openapi/salaxy-03.json) | The REST API v03, the current version | | [`/openapi/salaxy-04.json`](https://code.salaxy.com/openapi/salaxy-04.json) | The REST API v04, in beta. Build on v03 | See [For agents](https://code.salaxy.com/for-agents.md) for the full list, including the MCP demo servers. ## Start prompt Open your coding agent in the repository you want to integrate from, and paste this. Replace the text in square brackets. ```text Research https://code.salaxy.com and plan a Salaxy payroll integration for [my product: one sentence]. Start from https://code.salaxy.com/llms.txt and read the integration overview. Before you write any code, run a grilling session with me: ask your questions one at a time. First ask which build path I want (the embedded Salaxy UI — Salaxy Business and Salaxy Pro — or my own UI on the REST API) and whether I am a partner or a company. Then take the integration topics in order and ask the "Which fits you?" question of each topic that applies. Build on API v03 and follow the site's rules for errors, queries, idempotency and polling. Use the test environment only. Never ask me to paste a password, token or private key into this chat. When a fact is not on the site, tell me and list it as a question for Salaxy. Do not guess from other payroll APIs. When the questions are answered, write the plan, then implement it step by step and test each step against the test environment. ``` ## The questions the agent should ask The agent should ask in this order. The choices are the same ones a partner kick-off meeting goes through. 1. **Build path.** The embedded Salaxy UI (Salaxy Business for companies, Salaxy Pro for accounting firms) or your own UI on the REST API; paths can be combined. See [Integration overview](https://code.salaxy.com/integration/index.md#choose-your-build-path). 2. **Partner or company.** A partner serves many customer companies and needs the one-time setup topics. A company connects its own systems and can skip most of them. See [Integration overview](https://code.salaxy.com/integration/index.md#partner-or-company). 3. **Each topic's "Which fits you?"** Every topic page lists its options under that heading, for example the account structure or the service model. The agent asks only the topics that apply to your build path. The topic pages are listed in the [Integration overview](https://code.salaxy.com/integration/index.md). The first one for a partner is [Partner and technical accounts](https://code.salaxy.com/integration/partner-account.md). ## Test it 1. Get a test credential for your path: see [Get a test account](https://code.salaxy.com/get-started/test-account.md). 2. Tell the agent which credential you have and where it is stored. Give it a token through an environment variable or a secret store, never in the chat. 3. Ask the agent to make one authenticated call first, then to add one topic at a time and run it against `https://test-secure.salaxy.com`. 4. Ask it to read the [errors](https://code.salaxy.com/reference/errors.md) page before it writes error handling, and to look before it creates, as in [Retries and idempotency](https://code.salaxy.com/reference/idempotency.md). ## When a fact is missing If the site does not state a fact, the agent should say so and list it as a question. Send the list to Salaxy; see [Support](https://code.salaxy.com/get-started/support.md). Include the page the agent read and the question, and nothing that identifies a real person. See also the [Developer FAQ](https://code.salaxy.com/get-started/faq.md). ## Checklist - The agent started from `llms.txt` and the integration overview. - You answered the build path and partner-or-company questions before any code was written. - Every call in the code uses a `test-*` host and API v03. - No password, token or private key is in the chat or in the repository. - Every question the site could not answer is in a list for Salaxy. **Next:** [Partner and technical accounts](https://code.salaxy.com/integration/partner-account.md) --- Source: https://code.salaxy.com/integration/partner-account.md # Partner and technical accounts Every partner integration starts from two kinds of Salaxy account and one certificate. Salaxy creates the accounts. You create the certificate, and your server uses it to get access tokens. Do this once per environment, before any other integration work. Examples use the **test** environment; see [Environments](https://code.salaxy.com/get-started/environments.md) for demo and production. *Diagram: Four steps left to right. Salaxy creates the partner account, the top-level admin account. Salaxy then creates one or more technical accounts under it, and your server calls the API through them. You create a digital certificate for a technical account in the Salaxy web application. Your server signs a JWT with the certificate's private key and exchanges it for an access token. (The one-time set-up. Salaxy creates the accounts; you create the certificate that signs your sign-in.)* ## The accounts | Account | What it is | Who uses it | |---|---|---| | **Partner account** | Your top-level admin account. It is created against your company's business ID, with a power of attorney. | It owns the technical accounts and is not used in the daily API flow. | | **Technical account** | The API-facing account under the partner account, with the same business ID. | Your server signs in as it. It owns the payment channel that serves every customer company below it. | - A partner account can have **several technical accounts**. - A technical account has no access back up to the partner account. - Technical accounts are **created by Salaxy**. There is no API for creating one. How customer companies and accounting firms sit below the technical account: [Account structure](https://code.salaxy.com/integration/account-structure.md). ## Who does what | Step | Done by | |---|---| | Create the partner account | Salaxy | | Create the technical account or accounts | Salaxy, with you | | Create the digital certificate for the technical account | You, in the Salaxy web application or through the API | | Check the set-up with a first token | You | The payment channel, service models and accounting models are also provisioned by Salaxy. See the next topics in this section. ## Test and production Each environment has its own accounts. The test accounts should exist when the project starts, so verify that before you start coding. Production accounts are separate; you switch to them when you go live ([Go-live checklist](https://code.salaxy.com/integration/go-live.md)). - **A certificate works in one environment family only.** A test certificate fails in production, and a production certificate fails in test. Create one for each. - **Test and demo accept the same kind of certificate.** Only production has its own. ## The digital certificate The certificate proves that a request comes from your technical account. Your server signs a JWT with its private key and exchanges the JWT for an access token. The full flow, with claims and a code sample, is in [Impersonation flow for SSO](https://code.salaxy.com/security/impersonation.md). This page covers only what to create. **What you create** 1. Sign in to the Salaxy web application with a user linked to the technical account. In test: [test.palkkaus.fi](https://test.palkkaus.fi). 2. Go to **Settings → Authorisations** and create a new digital certificate. 3. Pick the format: `.pfx` (for .NET and Java; you set a password in the dialog) or `.pem` (for Node.js and Python; a zip with `.crt`, `.key` and `.pem`). 4. Store the private key in your backend's secret store. **Never share the private key:** Do not send it to anyone, put it in the browser or commit it to git. Anyone who has it can act for your customers. **What you send to Salaxy:** nothing. The certificate is registered on the technical account when you create it. **What the certificate looks like** | Property | Value | |---|---| | Subject | `CN=`. The certificate identity is the account. | | Key | RSA 2048, SHA-256 signature | | Issuer | A Salaxy root CA: a development root in test and demo; the production root in production | **Rotation and revocation** - An account can hold **several certificates** at once, each revoked on its own. To rotate without downtime, add the new certificate, switch your server to it and then delete the old one. - Deleting a certificate removes it immediately. There is no revocation list: if a key leaks, delete that certificate and issue a new one. - Salaxy sets no expiry per certificate, so the rotation schedule is yours to agree in the project. **Production: let Salaxy sign your own key:** The PEM endpoint also accepts a **certificate signing request** (CSR) in the `password` field of the request body. Salaxy signs it and returns **no private key**, so the production key is generated in your own infrastructure and never travels over the network. This path is API-only; the web application always generates the key pair itself. | Method | Path | Purpose | |---|---|---| | `POST` | `/v03/api/accounts/certificate` | Issue a certificate as a `.pfx` file. The password is required | | `POST` | `/v03/api/accounts/certificate/pem` | Issue a certificate as a `.pem` zip, or sign your CSR | | `GET` | `/v03/api/accounts/certificate` | List the account's certificates | | `DELETE` | `/v03/api/accounts/certificate/{id}` | Delete a certificate | ## Test it 1. Create a test certificate for your technical account, as above. 2. Build and sign a JWT with `iss` and `sub` set to the technical account id, and exchange it at `https://test-secure.salaxy.com/oauth2/token` ([Impersonation flow for SSO](https://code.salaxy.com/security/impersonation.md)). 3. Call `GET https://test-secure.salaxy.com/v03/api/session/current` with the token as a Bearer token. A `200` response with the technical account in `currentAccount` shows that the set-up works. For a customer company, you sign in with `sub` set to the customer's account id; see [Customer account creation](https://code.salaxy.com/integration/customer-accounts.md). ## Checklist - The test partner account and technical account exist, and you know the technical account id. - You created a certificate for each environment, and each private key is only in your backend's secret store. - Your server exchanges a signed JWT for an access token and gets a `200` from `/v03/api/session/current`. - You have a plan for rotating certificates: add the new one, switch, delete the old one. - Test and production use separate certificates and separate account ids in your configuration. **Next:** [Account structure](https://code.salaxy.com/integration/account-structure.md) --- Source: https://code.salaxy.com/integration/account-structure.md # Account structure Salaxy arranges accounts in a tree. Your technical account is the root, and every customer company hangs below it, either directly or through an accounting firm. The shape you pick decides who sees which companies, whose settings apply and how you create accounts, so choose it before you build. Examples use the **test** environment; see [Environments](https://code.salaxy.com/get-started/environments.md) for demo and production. *Diagram: Three structures side by side. Two-tier: your technical account has customer companies directly below it. Three-tier: your technical account has accounting firms below it, and each accounting firm has its own customer companies. Mixed: your technical account has both accounting firms and directly attached customer companies, and the accounting firms have customer companies of their own. A customer company always has exactly one parent. (Grey: your side. Purple: the customer company, which has exactly one parent in every structure.)* ## The rules - A **customer company has exactly one parent**: your technical account directly, or an accounting firm. Never both. - The **payment channel** belongs to the technical account and reaches every account below it through [service models](https://code.salaxy.com/integration/service-models.md). No tier below can swap in its own payment channel. - **Accounting models** (the charts of accounts) are also distributed through service models, not attached to accounts one by one. - **Employees and other end users are not in the tree.** They only receive salary slips and may sign in to see their own pay. - **The tree is not the access list.** Being a parent gives no access by itself. Access comes from an authorisation on the company's account that names your account, and it is all-or-nothing: whoever can reach the company can do everything the company account can do. The terms behind the tree (account, worker, employment, payroll) are in [Core concepts](https://code.salaxy.com/about/concepts.md). ## Which fits you? ### Two-tier: partner to customer company Choose this when you onboard customer companies directly and you are, or act as, their accounting firm. Every customer company is created directly under your technical account. **Two-tier: how it works:** - You create each customer company with `POST /v03/api/partner/company` and **leave `proxyPartner` out**. See [Partner-initiated account creation](https://code.salaxy.com/security/account-creation.md). - Customer companies that are accounting firms themselves are onboarded as ordinary customer companies. ### Three-tier: partner to accounting firm to customer company Choose this when your customers are accounting firms that serve their own customer companies. The accounting firm tier gives each firm its own view of only its customer book in Salaxy Pro. **Three-tier: how it works:** - Create the **accounting firm account first**, without `proxyPartner`. Then create each customer company with `proxyPartner` set to the accounting firm's account id, so the firm becomes the company's parent. - Your technical account needs access to the accounting firm. It does not need to be authorised to each customer company separately: the token flow can name the accounting firm as a proxy, and Salaxy checks both steps (you to the firm, the firm to the company). See [Impersonation flow for SSO](https://code.salaxy.com/security/impersonation.md), the `salaxy_proxy_act` claim. - **The proxy step reaches everything the firm can reach.** You cannot limit it to a subset of the firm's companies. - The parent is set only when the company has none. A company that already has a parent keeps it, so moving it needs the explicit re-pointing call below. - The accounting firm's users work in Salaxy Pro or through the [Pro API](https://code.salaxy.com/integration/pro-api.md). How the firm's account is created: [Accounting firm account creation](https://code.salaxy.com/integration/accounting-firm-accounts.md). | Method | Path | Purpose | |---|---|---| | `POST` | `/v03/api/partner/company` | Create or find a customer company or accounting firm. `proxyPartner` names the parent | | `POST` | `/v01/api/pro/accounts/{accountId}/partner` | Make the current account the company's primary partner. Optional `serviceModelId` query parameter | | `DELETE` | `/v01/api/pro/accounts/{accountId}/partner` | Remove the current account as the company's primary partner | The re-pointing calls exist only in the Pro API, which has no v03 version. The same endpoints are under `/v04/api/pro/` in the [v04 reference (beta)](https://code.salaxy.com/reference/rest/v04/pro.md). See [Pro API](https://code.salaxy.com/integration/pro-api.md). ### Mixed: some directly, some through accounting firms Choose this when only part of your customers have an accounting firm in between. Create each customer company by the two-tier or three-tier method, depending on who its parent is. The rules above apply to each branch separately. **Mixed: how it works:** - Decide per customer company at creation time: with `proxyPartner` if it belongs to an accounting firm, without it if it belongs directly to you. - Every company still has exactly one parent, so the question "who is this company's parent?" always has one answer. - Service models can differ per branch. See [Service models](https://code.salaxy.com/integration/service-models.md). ## How to choose | If … | Then | |---|---| | You are the accounting firm for all your customers | Two-tier | | Your customers are accounting firms with their own customer companies | Three-tier | | Some customers come through accounting firms and some do not | Mixed | | You are not sure | Ask at the kick-off. A company that already has a parent keeps it, so changing the structure later needs the re-pointing call | Who has a contract with whom in each structure: [Contract options](https://code.salaxy.com/integration/contract-options.md). ## Test it 1. Create two customer companies with `POST https://test-secure.salaxy.com/v03/api/partner/company`, as in [Partner-initiated account creation](https://code.salaxy.com/security/account-creation.md). For a three-tier test, create an accounting firm first and use its id as `proxyPartner`. 2. Get a token for each company ([Impersonation flow for SSO](https://code.salaxy.com/security/impersonation.md)) and call `GET /v03/api/session/current`. `currentAccount` shows the company you act as. 3. For a three-tier test, get a token for the accounting firm and call `GET /v01/api/pro/accounts`. The companies created with the firm as `proxyPartner` are in the list. ## Checklist - You have chosen two-tier, three-tier or mixed, and the choice is written down for both sides. - Every customer company is created with the right `proxyPartner`, or none. - You handle the case where a company already exists under another parent: the creation call does not move it. - Your tokens name an accounting firm as a proxy only when your account is authorised to that firm. - Your product shows a user only the companies that user is entitled to. Salaxy Pro does this for accounting firms; in your own UI, you do it. **Next:** [Contract options](https://code.salaxy.com/integration/contract-options.md) --- Source: https://code.salaxy.com/integration/contract-options.md # Contract options Salaxy files to the Tax Administration and the Incomes Register on an employer's behalf, so every customer company must have authorised Salaxy before it can run payroll. How the company does that depends on your [account structure](https://code.salaxy.com/integration/account-structure.md). Pick the option before you build the onboarding step. Examples use the **test** environment; see [Environments](https://code.salaxy.com/get-started/environments.md) for demo and production. *Diagram: Salaxy is at the top. Three parties each have their own agreement with Salaxy. The partner has signed a power of attorney for its partner account. An accounting firm has signed its own power of attorney and, when agreed with Salaxy, holds its own Incomes Register certificate. A customer company has either signed a power of attorney itself, or accepted the terms with a click when its accounting firm has vouched for it. (Each party has its own agreement with Salaxy. The accounting firm's agreement is what makes the click option possible for its customer companies.)* ## Who has a contract with whom | Party | Agreement with Salaxy | Notes | |---|---|---| | **Partner** | A signed power of attorney, behind your [partner account](https://code.salaxy.com/integration/partner-account.md) | Arranged with Salaxy outside the API | | **Accounting firm** (three-tier) | Its own power of attorney. Its own Incomes Register certificate when its customers' reports are signed with it | Needed for the click option below. Without them its customer companies must sign themselves | | **Customer company** | A power of attorney that it signs, **or** terms that it accepts with a click | Which one depends on the structure; see below | An accounting firm's agreement with its customer company is between the two of them. Salaxy **trusts the firm's statement** that it holds the company's authorisation and does not check it. ## Which fits you? ### The company signs its own power of attorney The default. The company's representative authorises Salaxy with a bank-authenticated signature. It works in every account structure and needs nothing from the accounting firm. **Company signs: how it works:** - The signing is bank-authenticated. Salaxy keeps the signed authorisation as the paper trail for its filings on the company's behalf. - The authorisation type on the company account is `employerAuthorization`. The company can also sign the Salaxy agreement itself (`companyContract`). - Use this if your accounting firm tier has not signed its own power of attorney, or you have no accounting firm tier. ### The company accepts the terms with a click A shortcut for companies below an accounting firm. Salaxy enables it for the firm, or for the partner above the firm. The firm has already signed its own power of attorney, so the company only accepts the terms. The accepted authorisation records which account vouched for it (`partnerContract`). Salaxy always sends the Incomes Register reports. The set-up agreed with Salaxy decides whose certificate signs them: Salaxy's by default, or the **accounting firm's own** certificate. Only in the second case does the firm need a valid certificate. **Click option: how it works:** The click is consent to terms, not a legal signature. The legal weight sits with the accounting firm's authorisation from its customer. For this reason the accounting firm may accept on the company's behalf, in the company's own session. The acceptance **fails** when the company has no accounting firm above it, when the firm has not signed its own power of attorney, or when the firm's own certificate is required and is missing or expired. The company then signs its own power of attorney instead. Two things can break it later, so handle them: - **Certificate expiry.** When the firm's certificate is required, it is checked again every time an invoice is created. A company can onboard successfully and then fail to commit a payment months later when the firm's certificate expires. - **Changes in the tree.** If the account that vouched leaves the company's hierarchy or loses its permission, the acceptance lapses (`hasValidContract` is `false`). Moving a company to another parent breaks it too. | Method | Path | Purpose | |---|---|---| | `GET` | `/v03/api/onboarding/contract` | Which contract the current account must accept, whether it already has a valid one, and whether the parent's certificate blocks acceptance | | `POST` | `/v03/api/onboarding/contract` | Accept it. The call acts on the signed-in account, so use a token for the company | ```json { "authorizationType": "partnerContract" } ``` A `GET` response: ```json { "authorizationType": "partnerContract", "hasValidContract": false, "isParentIrCertificateRequiredButMissingOrExpired": false } ``` When `authorizationType` is `employerAuthorization`, the company must sign the power of attorney instead. When `isParentIrCertificateRequiredButMissingOrExpired` is `true`, the parent account must add a valid certificate first; the terms cannot be accepted before that. ## In each structure | Structure | Typical contract path | |---|---| | **Two-tier** (technical account to company) | Company signs its own power of attorney. Whether the click option is open to your technical account is **To be decided** with Salaxy at the kick-off | | **Three-tier** (accounting firm in between) | The accounting firm signs its own power of attorney, and adds its certificate if its own certificate is to sign. Its customer companies then accept with a click | | **Mixed** | Per company: by the path of its own parent | When the accounting firm's own certificate signs its customers' Incomes Register reports, the firm manages it with `GET` and `POST /v03/api/settings/irCertificate` and `POST /v03/api/settings/irCertificate/renew`. See [Incomes Register filing](https://code.salaxy.com/integration/incomes-register.md). ## Test it 1. Create a customer company under an accounting firm, as in [Account structure](https://code.salaxy.com/integration/account-structure.md#test-it). 2. With a token for the company, call `GET https://test-secure.salaxy.com/v03/api/onboarding/contract`. Check `authorizationType` and `hasValidContract`. 3. If `authorizationType` is `partnerContract` and `isParentIrCertificateRequiredButMissingOrExpired` is `false`, post the acceptance as above and read the contract again: `hasValidContract` should now be `true`. 4. If your set-up uses the firm's own certificate, repeat without it to see the blocked state. ## Checklist - You know which contract path each of your customer segments uses, and it matches your [account structure](https://code.salaxy.com/integration/account-structure.md). - Your onboarding reads `GET /v03/api/onboarding/contract` and shows the right step: sign, accept or wait for the parent's certificate. - You tell an accounting firm early that it needs its own power of attorney, and its own Incomes Register certificate if your set-up uses it. You then monitor the certificate's expiry. - You handle a lapsed acceptance (`hasValidContract: false`) after a company changes parent. **Next:** [Service models](https://code.salaxy.com/integration/service-models.md) --- Source: https://code.salaxy.com/integration/service-models.md # Service models A service model is a bundle of settings that a parent account hands down to the customer companies under it. It is how a partner makes every customer pay through the same [payment channel](https://code.salaxy.com/integration/payment-channels.md) and post to the same [accounting models](https://code.salaxy.com/integration/accounting-models.md), without configuring each company by hand. Salaxy creates and updates the models for you. Examples use the **test** environment; see [Environments](https://code.salaxy.com/get-started/environments.md) for demo and production. *Diagram: Your technical account owns a service model. The service model carries a payment channel, an accounting model and a payslip setting. It applies to every customer company under the technical account, and each company reads the settings from it. (Purple: Salaxy provisions it. One service model reaches every customer company under the owner.)* ## What a service model is A service model belongs to one account, the **owner**: your technical account, or an accounting firm. A customer company that sits under the owner reads the owner's model and takes its settings from it. A model has sections. Each section is switched on by its own flag in `features`, and only a switched-on section overrides the company's own settings. | Section (flag) | What it sets for the company | |---|---| | Payments (`payments`) | The available payment channels and the default channel. See [Payment channels](https://code.salaxy.com/integration/payment-channels.md). | | Accounting (`accounting`) | The accounting models (targets) and the default one. See [Accounting models](https://code.salaxy.com/integration/accounting-models.md). | | Cost accounting (`costAccounting`) | The dimensions (cost centres). | | Holiday (`holiday`) | Holiday pay and holiday accrual settings. | | Incomes Register (`irDelivery`) | The certificate used when filing on the company's behalf. | | Reporting (`reporting`) | The report layout template and logo. | | Messaging (`messaging`) | Payslip delivery methods and worker notifications. | | Use cases (`usecase`), pay statistics (`payStats`), forms (`forms`) | Further optional settings. | Three sections are always copied and have no flag: **pricing**, **branding** (logo and design) and **site** (the web app a company is sent to). ## What the model fixes for the customer A section that is switched on is **locked** in practice: the model's values replace the company's own, and a change made in the company's settings is overwritten the next time they are read. Salaxy has no separate "restricted account" setting; a locked section is a section with its flag on. - **Locked** means the same payment channel, the same accounting models and the same payslip setting for every customer company. Decide this with Salaxy at project start, and record the locked sections in your integration design document. - **Not locked** means the flag is off. The customer, or its accounting firm, edits that part freely. - **Pricing** is changed only by Salaxy. An attempt to change pricing through the API fails with a generic `400`. - **Opt-out.** Each section also has a `denyServiceModel` setting on the company side. When it is on, the company keeps its own settings for that section even if the model says override. It is for one-off exceptions and is not meant as a normal path. The cascade replaces whole lists. For example, with `payments` on, the company's list of payment channels is replaced by the model's list. Do not store your own data inside a company's channel list; it will be overwritten. ## Who provisions it | Step | Who | |---|---| | Create and update a service model | Salaxy | | Decide which customers get which model | You, agreed with Salaxy | | Link a model to an accounting firm or a company | Salaxy, usually as part of onboarding that customer | You do not create service models through the API. The record of which models exist for your project, in test and in production, sits in your integration design document: model name, id and owner account. The owner's default model has the owner's account id as its id. Production needs its own models, which Salaxy creates. ## How a company gets a model - **By the parent link.** A customer company reads the model of its primary parent: usually your technical account in a two-tier set-up, or the accounting firm in a three-tier one. See [Account structure](https://code.salaxy.com/integration/account-structure.md). - **By id.** An account carries an optional `serviceModelId`. If it is empty, the company falls back to the **default model of its parent**, the one whose id equals the parent's account id. If the parent has no default model, nothing is applied and the company keeps its own settings. - **At creation.** When you create a company with `POST /v03/api/partner/company`, its settings are stored at once, so the company has its model straight away. See [Customer account creation](https://code.salaxy.com/integration/customer-accounts.md). - **Test accounts.** Accounts made with `POST /v03/api/test/accounts` get no model until their settings are saved once: read `GET /v03/api/settings/company` and post the same body back to `POST /v03/api/settings/company`. An accounting firm that has its own customer companies needs its own default model, because its customers read the firm's models and not yours. Ask Salaxy to set it up when you add such a firm. ## Endpoints You normally only read. The CRUD endpoints exist, but changing a model is Salaxy's job. | Method | Path | Purpose | |---|---|---| | GET | `/v03/api/service-models` | Search the models of the signed-in account (OData; `$search` free text). | | GET | `/v03/api/service-models/{id}` | One model. | | GET | `/v03/api/service-models/new` | A model with default values, not stored. | | POST | `/v03/api/service-models` | Create or update. Salaxy does this. | | DELETE | `/v03/api/service-models/{id}` | Delete. The owner's default model cannot be deleted. | The same paths exist under `/v04/api/`. The endpoints work on the signed-in account's own models. Called with a token of another account, a read by id returns an empty result, not `404`. Sign in as the owner to read its models. The reference page is [ServiceModel](https://code.salaxy.com/reference/rest/servicemodel.md). ```http GET https://test-secure.salaxy.com/v03/api/service-models Authorization: Bearer {owner-account-token} ``` ## Test and production - **Test** has your models from project start, so you can build against the real settings. Test and demo share data. - **Production** needs its own model. Salaxy creates it, usually with the same name as in test. - **A change to a model** reaches the companies that read it. Ask Salaxy before a change that affects live customers. ## Test it 1. Create a customer company on test with `POST /v03/api/partner/company`, using a [partner token](https://code.salaxy.com/integration/partner-account.md). 2. Sign in as the company and call `GET /v03/api/settings/company`. Check `payments.channels` and `accounting.targets`: they should match the service model. 3. Call `GET /v03/api/session/current` with the same token and compare `settings.paymentChannels`. The two views should agree. ## Checklist - You have agreed with Salaxy which sections are locked and which customers get which model. - The model exists in test and in production, and you have its id. - Your code does not write to a locked section; a company's own value is overwritten. - New accounting firms with their own customers get a default model. - You do not store your own data in a company's channel list. **Next:** [Payment channels and SEPA payment files](https://code.salaxy.com/integration/payment-channels.md) --- Source: https://code.salaxy.com/integration/payment-channels.md # Payment channels and SEPA payment files A **payment channel** is the route a salary takes from a finished payroll to the bank. Salaxy creates the invoices of a payroll and puts them on the channel. What happens next depends on the channel: Salaxy pays from a customer funds account, your system pays, or a SEPA payment file goes to a bank. Choose the channel with Salaxy before you build. Examples use the **test** environment; see [Environments](https://code.salaxy.com/get-started/environments.md) for demo and production. The running loop (fetch unpaid invoices, report their status) is on [Invoices and payments](https://code.salaxy.com/integration/invoices-and-payments.md); this page covers the choice, the set-up and the SEPA files. *Diagram: A payroll creates invoices in Salaxy. The invoices go to a payment channel. From the channel there are two ways forward. With a customer funds account, Salaxy collects the money from the employer and pays the workers. With a partner channel, your system fetches the invoices, pays them, and reports the status back to Salaxy. (Purple: Salaxy. Grey: your side. A channel is one of the two routes; SEPA files are a way for the second route to pay.)* ## What a channel is - **A channel is code, not data.** Its key is a fixed value (a camelCase name such as the `{channel}` in the paths below), and it has one owner account. Deploying the backend makes a channel exist, so there is no channel record to create in production, and its key is the same in test and production. - **The owner account may call the channel API.** `/payment-channel/{channel}/...` works across all customer companies of the owner, with one token. Another account gets an error. Customer companies and accounting firms do not use these paths; they use their own invoice endpoints. - **Companies get a channel through a service model**, never directly. See [Service models](https://code.salaxy.com/integration/service-models.md). - **The channel is chosen per payroll**, when the payroll is created, and stored on it. Changing a service model does not move payrolls that are already open. - **A new channel is hidden at first.** No company can use it until Salaxy adds it to the service model of the right customers. ## Which fits you? ### Salaxy pays from a customer funds account Fits when you do not want to move money yourself and the customer is happy to pay the employer's gross amount to Salaxy. **Customer funds account: how it works:** - The employer pays Salaxy first. Salaxy then pays the workers, the tax and the other recipients downstream. - The payroll gets a **gross** invoice (employer to Salaxy) in addition to the net, tax and other invoices. Salaxy pays the net, tax and other invoices only after the gross payment has arrived. - `paymentSucceeded` on the payroll then means "Salaxy received the employer's funds", not "the worker is paid". The worker payment is a later step in Salaxy. If you display payment progress, do not label `paymentSucceeded` as "paid to the worker". See [Payroll lifecycle](https://code.salaxy.com/integration/payroll-lifecycle.md). - You build nothing for the payment itself. Which of these channels you can use is agreed with Salaxy. ### Your channel: you pay and report back Fits when your system already makes payments, for example an accounting system or a payment service. **Your channel: how it works:** - Salaxy provisions a channel owned by your technical account. Your system fetches `unread` invoices, pays them, and reports the status back with `update-status`. - You must report `paid` with the salary date as the date, so the payroll can move on and the payslip and the Incomes Register filing follow. The full loop, statuses and polling are on [Invoices and payments](https://code.salaxy.com/integration/invoices-and-payments.md). - Whether the channel also calls you when an invoice is ready is a property of the channel and agreed at project start. There is no webhook to subscribe to yourself. Treat any such call as a prompt to poll, and keep polling as the backstop. - Fetching and reporting use the endpoints below. ### SEPA payment files Fits when you, or the customer, pay by uploading a file to a bank. It is a way to carry out the second option, not a third kind of channel. **SEPA payment files: how it works:** Salaxy renders the invoices as a ready-made SEPA Credit Transfer file in ISO 20022 `pain.001` format, so you do not build the payments from the invoice JSON. See [SEPA files](#sepa-files) below. Salaxy can also store the file as a **payment message**; see [Payment messages (v04 beta)](#payment-messages-v04-beta). ## Provisioning | Step | Who | |---|---| | Create the channel | Salaxy, with you verifying it | | Make it available to your customers | Salaxy, through a service model | | Choose which customers use it | You, agreed with Salaxy | You do not create or change payment channels through the API. One channel per technical account is the common case, and several are possible. Your integration design document records the channel key and its owner account for test and production. Before go-live, confirm with Salaxy that the channel is live for the **monthly invoices** too. A channel that is still marked as not live in production generates no monthly tax or union invoices, and nothing fails loudly. See [Go-live checklist](https://code.salaxy.com/integration/go-live.md). ## Endpoints All paths are under `/v03/api/payment-channel/{channel}` (the same set exists under `/v04/api/`). The owner account calls them. | Method | Path | Purpose | |---|---|---| | GET | `/{channel}/status/{status}` | Invoices by status. Takes `dateKind`, `start` and `end`; without them it looks back 14 days only. | | GET | `/{channel}` | OData search over the channel's invoices. | | GET | `/{channel}/{id}` | One invoice. | | POST | `/{channel}/update-status` | Report status changes, body is an array. | | GET | `/{channel}/{id}/content` | The invoice PDF. `/{channel}/content?ids=...` for several. | | GET | `/{channel}/{id}/calculation` | The calculation behind a net invoice. | | GET | `/{channel}/{id}/accounting` | Accounting data for a net invoice. See [Accounting data](https://code.salaxy.com/integration/accounting-data.md). | | GET, POST | `/{channel}/sepa`, GET `/{channel}/{id}/sepa` | SEPA file. See below. | The reference pages are [PaymentChannel](https://code.salaxy.com/reference/rest/paymentchannel.md) (v03) and [PaymentChannel v04](https://code.salaxy.com/reference/rest/v04/paymentchannel.md). ## SEPA files Three routes render a file. All are read-only: fetching a file does not change the status of the invoices. Report status with `update-status` as usual. | Method | Path | Returns | |---|---|---| | GET | `/v03/api/payment-channel/{channel}/{id}/sepa` | A file for one invoice. | | GET | `/v03/api/payment-channel/{channel}/sepa?ids=...` | A file for a list of invoices. All must belong to **one payer**, or the call is refused. | | POST | `/v03/api/payment-channel/{channel}/sepa` | A file for the `Invoice[]` in the body. | If you sign in with a customer's token and the customer does not own the channel, use `GET /v03/api/invoices/sepa` and `POST /v03/api/invoices/sepa`. They take the same parameters. | Parameter | Meaning | |---|---| | `ids` | Invoice ids, repeated (`ids=...&ids=...`). | | `version` | `pain.001.001.02` (default) or `pain.001.001.03`. | | `payerIbanNumber`, `payerBic`, `bankPartyId` | Payer bank details; `bankPartyId` depends on the bank. | | `inline` | `true` to show in a browser. The default is a file download. | ```http GET https://test-secure.salaxy.com/v03/api/payment-channel/{channel}/sepa?ids=00000000-0000-0000-0000-000000000001&version=pain.001.001.03 Authorization: Bearer {channel-owner-token} ``` What to know about the file: - **One payment block per invoice type and due date.** A file can hold several blocks with different execution dates. - **Net salaries are flagged `SALA`.** The ISO 20022 category purpose `SALA` is set on net-salary payments when the due date allows, so the bank treats the batch as salary. It is a flag inside the file, not a separate format. - **`EndToEndId` is the invoice id** and is stable across calls, so a failure the bank reports by `EndToEndId` maps back to an invoice. `MsgId` and the block ids are new on every call and are not stored. - **An unknown `version` is not an error.** Any value other than the two above returns a `pain.001.001.02` file with no warning. Check the version you asked for. - **The server names the file** `SEPA_{yyyy-MM-dd_HHmmss}.xml` in `Content-Disposition`. Save it under any name you need. - **Salaxy keeps no batch record** for these routes. If you need to tell batches apart or re-send, set `externalId` when you report the status with `update-status`. It must be unique per invoice, so combine your batch reference with the invoice id, for example `{batch}-{invoiceId}`. ## Payment messages (v04 beta) A **payment message** (in Finnish `maksuaineisto`) is a SEPA file that Salaxy stores, with an id, a status and its batches. Unlike `/sepa`, which renders again on every call, the stored file is the same bytes each time. This API is **v04 beta**: it may change, so allow for that before you build on it. The v03 document lists the same paths under `/v03/api/`. Two sets of paths. Channel owners use the first, customer companies the second. | Method | Path | Purpose | |---|---|---| | POST | `/v04/api/payment-channel/{channel}/payment-messages` | Create from `invoiceIds`, or resend with `parentMessageId`. Optional `Idempotency-Key` header. | | GET | `/v04/api/payment-channel/{channel}/payment-messages` | List, newest first. | | GET | `/v04/api/payment-channel/{channel}/payment-messages/{id}` | One message with its batches. | | PATCH | `/v04/api/payment-channel/{channel}/payment-messages/{id}` | Change the status. | | GET | `/v04/api/payment-channel/{channel}/payment-messages/{id}/sepa` | The stored file. | | GET | `/v04/api/payment-messages/settings/{channel}` | The company's allowed actions, split, format and file name. | | POST, GET | `/v04/api/payment-messages` | Create, list. The create body also names the `channel`. | | GET, PATCH | `/v04/api/payment-messages/{id}` | One message; change its status. | | GET | `/v04/api/payment-messages/{id}/sepa` | The stored file. A read; it does not mark the message sent. | ```json { "invoiceIds": ["00000000-0000-0000-0000-000000000001"] } ``` - A message starts `new`. Whoever delivers the file marks it `sent` with `PATCH` and `{"status":"sent"}`. That also marks its invoices as read. Other statuses you can set are `cancellationRequested` and `executed`. - The actions a company may take on a channel are part of its settings and can be removed but not added by the company. Read them from `GET /v04/api/payment-messages/settings/{channel}`. - Create exactly one of `invoiceIds` or `parentMessageId`. Whether a resend is accepted depends on the channel and on the parent's status. ## Test it 1. Create a payroll for a test company that uses your channel, and commit it so the invoices are created. See [Salary calculations](https://code.salaxy.com/integration/calculations.md). 2. As the channel owner, call `GET /v03/api/payment-channel/{channel}/status/unread`. Expect the invoices as an array, not an object. 3. Fetch a SEPA file for one invoice and check the `EndToEndId` equals the invoice id. 4. Report `read` with `update-status` and fetch `status/read` to see it moved. A malformed body returns `200` with `[]` and changes nothing, so always read back. ## Checklist - The channel option is agreed with Salaxy, and the channel exists in test and in production with its owner account. - Your code reads the channel through the owner token only, and never assumes a channel is in a customer's list without checking the service model. - If you use SEPA files, you handle the one-payer rule and check the version you receive. - Your polling passes an explicit date range for catch-up, because the default window is 14 days. - On a customer funds account channel, your UI shows more than `paymentSucceeded`. - If you use payment messages, you treat them as v04 beta, which may change. **Next:** [Accounting models](https://code.salaxy.com/integration/accounting-models.md) --- Source: https://code.salaxy.com/integration/accounting-models.md # Accounting models An **accounting model** (in the API an *accounting target*) decides which ledger account each part of a salary payment is posted to. If your product books payroll into a ledger, the model decides the account numbers you receive. Salaxy sets the models up for you; you review them and read the result. Examples use the **test** environment; see [Environments](https://code.salaxy.com/get-started/environments.md) for demo and production. How to fetch the accounting data is on [Accounting data](https://code.salaxy.com/integration/accounting-data.md). *Diagram: A payroll is calculated in Salaxy. The accounting model maps the parts of the pay, such as salary, tax and social security, to ledger accounts. The result is accounting data with account numbers on each row, which your system books into its ledger. (Purple: Salaxy. The accounting model is the only step that decides account numbers.)* ## What an accounting model is - **A chart of accounts and a rule set.** The rules map each kind of salary amount, such as income types and totals like net pay, tax and social security, to a debit and a credit account. - **Export settings.** Each model also names the accounting system and format the data is meant for. - **One for each system.** Salaxy has built-in models for the accounting systems it supports. - **A default model.** Every company has a default model. If none is set, the built-in Salaxy default is used. ## What it changes - **The proposed account on invoice rows.** Each row of a payment-channel invoice carries `accountingAccountNumber` and `accountingCode`: one proposed ledger account for the row. This is not the bank account. The bank account of the payee is `recipient.iban`. - **The accounting data of a report.** The accounting-data endpoints post the rows with the model's rules. They take an optional `target` parameter to choose the model. A row with no matching rule, or a rule that is switched off, yields an entry with no accounts and no amount, silently, and not an error. Check the model against your chart before go-live. - **The model is applied when the invoice is created**, and the number is stored on the invoice. A later change to the company's model does not rewrite invoices that already exist. - **Only one account per row on an invoice.** The counter-account (bank or payable) is not on the invoice row. For a full debit and credit voucher, use the accounting data from the reports, not the invoice. ## Who provisions it | Step | Who | |---|---| | Create and update an accounting model | Salaxy. You review the list of accounts it locks. | | Attach it to your customer companies | Salaxy, through a [service model](https://code.salaxy.com/integration/service-models.md) | | Changes for one customer | Salaxy's existing customer-specific process | You do not assign a model to a company directly. The service model carries it down, and with the `accounting` section on, the company's models are replaced by the service model's list. The company's default may then be reset to the service model's default: always when the list includes Salaxy's built-in default model, and otherwise when the company's old default is not in the list. A company under such a service model cannot create customer-specific posting rules in its own settings. Test and production hold separate models with different ids. Salaxy copies each model to production and tells you its production id, which your design document records. ## Endpoints You normally only read. Creating and editing is Salaxy's job. | Method | Path | Purpose | |---|---|---| | GET | `/v03/api/accounting-target` | List the models of the account. This is a search result and does not hold the rules. | | GET | `/v03/api/accounting-target/{id}` | One model with `info` and `ruleSet`. | | GET | `/v03/api/accounting-target/new` | A blank model, not stored. | | POST | `/v03/api/accounting-target` | Create or update. | | DELETE | `/v03/api/accounting-target/{id}` | Delete. | The same paths exist under `/v04/api/`. The list supports the OData parameters `$search`, `$filter`, `$orderby`, `$select`, `$top` and `$skip`. See the [AccountingTarget reference](https://code.salaxy.com/reference/rest/accountingtarget.md). The rule set (`ruleSet`) has `accounts` (account number and text), `targetCoA` (the chart of the target system, not only the accounts in use) and `rows`. A row has an `entryCodeGroup`, an `entryCode`, `enabled`, `isIncluded`, and `debitId` and `creditId`. The ids point into `accounts`; the account numbers are not on the row. ```http GET https://test-secure.salaxy.com/v03/api/accounting-target/{id} Authorization: Bearer {customer-company-token} ``` To see whether a model posts a given item, fetch it by id and filter `ruleSet.rows` by `entryCodeGroup` and `entryCode`, then read `isIncluded`. A row missing from `rows` behaves like `isIncluded: false`. ## Test it 1. Sign in as a test company under your service model and call `GET /v03/api/accounting-target`. Note the default target in `GET /v03/api/settings/company` (`accounting.defaultTargetId`). 2. Fetch the default model by id and compare its accounts with your chart. 3. Create and commit a test payroll, then read its accounting data, as on [Accounting data](https://code.salaxy.com/integration/accounting-data.md). Every row you expect should carry an account number. ## Checklist - You have reviewed the accounts of each model with Salaxy, in test and in production. - Every account in the model exists in your chart. Tell Salaxy about any account your chart lacks. - You read the model by id when you need the rules; the list does not hold them. - You treat a row without accounts as a configuration gap, not as zero. - Production has its own copy of each model, and your design document holds the production ids. **Next:** [Customer account creation](https://code.salaxy.com/integration/customer-accounts.md) --- Source: https://code.salaxy.com/integration/customer-accounts.md # Customer account creation Before you can run payroll for a customer company, the company needs a Salaxy account. A trusted partner creates it, or finds the existing one, with a single call that takes the company's Business ID (*Y-tunnus*). Do this before you start the customer's onboarding. Examples use the **test** environment; see [Environments](https://code.salaxy.com/get-started/environments.md) for demo and production. *Diagram: Your system sends the customer's Business ID to Salaxy in one call. Salaxy looks for an existing account. If there is none, Salaxy fetches the company from the Finnish trade register (YTJ) and creates an account stub. Salaxy returns the account id, which your system stores. After that you can set up the company, and the customer completes its own onboarding at its own pace. (One call finds the account, or creates a stub from the trade register when there is none.)* **Trusted partner role:** Required in production, not in test. The authentication side (who may call, and how) is in [Partner-initiated account creation](https://code.salaxy.com/security/account-creation.md); this page does not repeat it. ## Which fits you? ### Customer company directly under you Use this when you serve the companies yourself, with no accounting firm in between. Leave `proxyPartner` out. Your technical account becomes the customer's parent. ### Customer company under an accounting firm Use this when the company belongs to an accounting firm that you have already created. Set `proxyPartner` to the accounting firm's account id, so the firm sees the company in its own book. Create the firm first: see [Accounting firm account creation](https://code.salaxy.com/integration/accounting-firm-accounts.md). **Both options: how it works:** `proxyPartner` threads the new customer under an accounting firm account at creation time. The caller must be authorised to that accounting firm account. Salaxy sets the parent **only if the company has none yet**. A company that already sits under another provider keeps its parent. To move it, use the explicit re-point in the [Pro API](https://code.salaxy.com/integration/pro-api.md#partner-relationship-management). Background on the tiers: [Account structure](https://code.salaxy.com/integration/account-structure.md). ## How it works | Method | Path | Purpose | |---|---|---| | POST | `/v03/api/partner/company` | Assure the account: return the existing one, or create a stub from the trade register | | POST | `/v03/api/partner/company?checkAuthorizationOnly=true` | Check access only; create nothing | The same call exists as `/v04/api/partner/company`. The request and response fields are in [Partner-initiated account creation](https://code.salaxy.com/security/account-creation.md#request). In short: - **Required:** `officialId`, the Business ID. A `*` in place of the check digit is accepted (`1234567-*`); the check digit is computed. - **Useful:** `partnerAccountId` (the company's id in your system), `proxyPartner`, `language` (`fi`, `sv`, `en`) and contact details. - **Returned:** `accountId`, `avatar`, `isVerified`, `isAuthorized`, `partnerAccountId`. ```http POST https://test-secure.salaxy.com/v03/api/partner/company Authorization: Bearer {technical-account-token} Content-Type: application/json ``` ```json { "officialId": "1234567-8", "partnerAccountId": "customer-4711", "language": "fi", "email": "payroll@example.com" } ``` ```json { "accountId": "FI00POYT0001234567", "avatar": { "displayName": "Example Oy", "initials": "EO" }, "isVerified": false, "isAuthorized": true, "partnerAccountId": "customer-4711" } ``` ### Rules - **Safe to repeat.** A second call with the same `officialId` returns the existing account, so you can retry after a network failure. - **`partnerAccountId` sticks.** Once set, every later call for that account must carry the same value. - **Never a 404.** An unknown company gets a stub. Access state is in `isAuthorized`, not in the status code. - **The company name comes from the trade register.** The request has no name field. A company that the Finnish trade register does not know is refused with a `400` whose `error` starts with `VALIDATION`. A register outage fails the same way, so retry later. There is no manual fallback on this endpoint. - **Your own Business ID is refused.** Use your partner account directly. - **Errors:** every business failure is a `400` with `error` and `messageHtml`. See the table in [Partner-initiated account creation](https://code.salaxy.com/security/account-creation.md#errors) and [Errors](https://code.salaxy.com/reference/errors.md). ## Verification: what `isVerified` blocks The response has two flags, and they answer different questions. | Flag | Question | Effect when `false` | |---|---|---| | `isAuthorized` | Can **you** access this account? | Every read and write on the account fails | | `isVerified` | Has **the customer** authorised Salaxy to act for it? | Creating invoices fails; nothing else | A new stub starts with `isAuthorized: true` and `isVerified: false`. An unverified account is fully usable: you can set it up, add employees, and build salary calculations and payrolls. The refusal comes only when a payroll is committed for payment, as a `400` titled *Asiakkaan valtakirjan allekirjoitus/palvelun ehtojen hyväksyntä puuttuu* ("the power of attorney or acceptance of the terms is missing"). - **Load data first.** You can create customers and import employees before the customer finishes its own onboarding. Only the payment step waits. - **Who sees it.** When payment is committed in the embedded white label, the customer sees the block, and can resolve it there. Expect a support question, not an API error that you handle. - **Two routes to verified.** The company signs its own employer power of attorney (identified through a bank or Suomi.fi), or, where an accounting firm vouches for it, the company accepts the terms with a click. - **A second, different refusal.** When the customer is under an accounting firm, that firm must hold a valid, unexpired Incomes Register certificate. Otherwise creating invoices fails with a different `400`, and the message names the firm's certificate. It can start failing long after onboarding, when the certificate expires. The remedy is the firm's. - **Moving a customer can un-verify it.** If the company was verified through the accounting firm's vouching, it stays verified only while that firm remains its billing partner. Moving it to another firm or partner returns it to unverified, with no event and no error. The symptom is payment commits that start failing for one customer that worked yesterday. ## What happens after 1. **Store `accountId`.** It is the key for everything that follows, and the id you use when you act as this company: see [Impersonation](https://code.salaxy.com/security/impersonation.md). 2. **Check the service model.** The company reads its parent's service model from creation, and inherits the payment channel and the accounting model from it. Salaxy links any other model: [Service models](https://code.salaxy.com/integration/service-models.md). 3. **Set up the company**: [Company settings](https://code.salaxy.com/integration/company-settings.md). In the embedded white label, the customer fills these in the settings screens. 4. **Add employees** and run payroll: [Create employees](https://code.salaxy.com/get-started/rest/create-employees.md). ## Test it - Call the endpoint on `test-secure.salaxy.com` with your technical account token. The trusted partner role is not needed in test. - Use a Business ID of a company that really exists. The trade register is the production one, in every environment, so a made-up ID is refused. - Test-only exception: a checksum-valid Business ID that starts with `77` and is unknown to the register is created with the name `Test company `. - Call it twice with the same ID and check that you get the same `accountId`. - Call with `?checkAuthorizationOnly=true` for an ID that has no account: expect `200` with `isAuthorized: false`. Nothing is created. - See also [Get a test account](https://code.salaxy.com/get-started/test-account.md). ## Checklist - You call the endpoint before onboarding starts, and store `accountId` and your own `partnerAccountId`. - You treat `isAuthorized: false` as an access problem, and `isVerified: false` as a payment-commit problem. - You branch on the HTTP status and `validation`, never on the Finnish `error` text. - You do not create invoices for a customer that is unverified, and you show a clear message when the commit is refused. - In a three-tier set-up you create the accounting firm first and pass its id as `proxyPartner`. **Next:** [Company settings](https://code.salaxy.com/integration/company-settings.md) --- Source: https://code.salaxy.com/integration/company-settings.md # Company settings Each customer company has settings that payroll needs: contact details, the employer's bank account, and pension and insurance contracts. You can leave them to the embedded white label settings screens, or read and write them over the REST API from your own UI. Examples use the **test** environment; see [Environments](https://code.salaxy.com/get-started/environments.md) for demo and production. *Diagram: Three steps. One: read the whole settings object from Salaxy. Two: change only the part your own screen owns, such as the employer's bank account. Three: post the whole object back. Salaxy replaces the stored settings with what you post, so anything you leave out is lost. (Always read, change, and post the whole settings object. Never build the body by hand.)* ## Which fits you? ### Settings in the embedded white label Use this when your customers use the embedded Salaxy UI, Salaxy Business or Salaxy Pro (build path 1). The customer fills in company information, bank account and contracts in the settings screens, in your design. You build nothing, and this page is not needed. See [Embedded white label](https://code.salaxy.com/white-label/index.md). ### Settings through the REST API Use this when you build your own UI (build path 2) and need to own the settings screens. Everything below is for you. **Settings through the REST API: how it works:** You write each area through the endpoints below. Salaxy provisions some parts of the settings itself (accounting, Incomes Register, payment channels and others). You never edit those, but you must post them back unchanged. See [the round trip](#the-get-change-post-round-trip). ## How it works Settings are written through two objects. | Method | Path | Holds | |---|---|---| | GET, POST | `/v03/api/accounts/company` | Company information: contact, language, company type | | GET, POST | `/v03/api/settings/company` | Everything else: payment account, pension and insurance contracts, and the parts Salaxy provisions | | GET, POST, DELETE | `/v03/api/settings/pensionContracts` and `/{contractNumber}` | Pension contracts, one at a time | | POST | `/v03/api/settings/pensionContracts/all` | Replace the whole list of pension contracts | All of them also exist as `/v04/api/...`. You call them as the customer company: see [Impersonation](https://code.salaxy.com/security/impersonation.md). The account must exist first: [Customer account creation](https://code.salaxy.com/integration/customer-accounts.md). ### The GET, change, POST round trip `POST /v03/api/settings/company` **replaces** the stored settings with the body of your request. It does not merge. A sub-object missing from the body is overwritten with empty defaults. That wipes configuration that Salaxy provisioned: accounting, Incomes Register, payment channels, customer funds and more. 1. **Read** the whole object: `GET /v03/api/settings/company`. 2. **Change** only the sub-object your UI owns. 3. **Post** the whole object back, with every other sub-object exactly as you received it. | Sub-object | Contents | Who writes it | |---|---|---| | `payments.invoice` | Employer payment account | **You** | | `calc.pensionContracts` | Pension contracts | **You** | | `calc.insuranceContracts` | Insurance contracts | **You** | | `accounting`, `costAccounting` | Accounting targets, export and cost-accounting dimensions | Salaxy: post back as it is | | `calc.incomesRegister` | Incomes Register delivery | Salaxy: post back as it is | | `payments.channels`, `payments.defaultChannel`, `payments.customerFunds` | Payment channels and customer funds | Salaxy: post back as it is | | `payments.channelConfigs` | Payment channel configs, read-only | Ignored on save; see [Payment channel config](#payment-channel-config) | | `partner` | Partner and service model | Salaxy: post back as it is | | `holiday`, `reporting`, `usecase`, `messaging`, `forms`, `payStats`, `configs`, `preferences` | Other service configuration | Salaxy: post back as it is | The server enforces a few fields, so a faithful round trip always succeeds. The partner link cannot be changed: a different `partner.accountId` is rejected. Service-model pricing is always taken from Salaxy's records. When a contract's `company` is `none`, its `contractNumber` is cleared. Two parts have an easier route. Pension contracts and cost-accounting dimensions have their own endpoints that keep the other settings intact. The employer's bank account and insurance contracts have none: write them only through the round trip. ## Company information Contact details, UI language and company type are on the company account object. Read it, change the fields you manage, post it back. ```http GET https://test-secure.salaxy.com/v03/api/accounts/company Authorization: Bearer {customer-company-token} ``` ```json { "id": "example-company", "companyType": "fiOy", "language": "fi", "contact": { "email": "payroll@example.com", "telephone": "+358 3 123 4567", "street": "Takomokatu 8", "postalCode": "33100", "city": "Tampere", "countryCode": "fi" } } ``` The object also carries fields that Salaxy manages or that are read-only, such as `avatar`, `serviceModelId`, `partner` and `identity`. Keep what you receive and post it back unchanged. `POST /v03/api/accounts/company` returns the saved object with `200`. | Field | Notes | |---|---| | `contact.email` | The company's salary-related e-mail. Stored lower case and trimmed | | `contact.telephone`, `contact.street`, `contact.postalCode`, `contact.city` | `city` is the postal town (*postitoimipaikka*) | | `contact.countryCode` | ISO 3166-1 alpha-2; currently always `fi` | | `language` | `fi`, `sv` or `en`; `default` follows the account default | | `companyType` | `fiOy` limited company, `fiTm` sole proprietor, `fiRy` association, `fiYy` other Finnish company or association, `unknown`. The [federation](https://code.salaxy.com/security/federation.md) flow uses the same codes | ## Employer payment account The employer's bank account, used when Salaxy creates payment material on the employer's behalf. It is the `payments.invoice` sub-object of `/v03/api/settings/company`, written only through the round trip. This is the part you change, inside the full object: ```json { "payments": { "invoice": { "sepaBankPartyId": "12345678", "ibanNumber": "FI22 6601 0001 0897 47", "bic": "AABAFI22" } } } ``` | Field | Notes | |---|---| | `ibanNumber` | The employer's Finnish IBAN | | `bic` | Optional for a Finnish IBAN: derived from the IBAN when you omit it. A `bic` in a response does not prove that anyone stored one | | `sepaBankPartyId` | The payer identifier (*maksatustunnus*) that the employer's bank issued, used in SEPA payment files | The same sub-object holds the e-invoicing fields `eInvoiceReceiver` and `eInvoiceIntermediator`. Round-trip them unchanged unless your UI manages e-invoicing. ## Pension contracts The employer's statutory earnings-related pension (TyEL) contracts are the `calc.pensionContracts` array. Most companies have one contract; several are allowed. Two ways to write them: - **Granular endpoint.** `POST /v03/api/settings/pensionContracts` with one contract adds it, or updates the one with the same `contractNumber`. `GET` lists the contracts, `GET` or `DELETE /v03/api/settings/pensionContracts/{contractNumber}` reads or removes one. Prefer this when pension is the only part you write. - **Round trip.** Change `calc.pensionContracts` in the full object. Use this when you write other areas in the same flow. `POST /v03/api/settings/pensionContracts/all` replaces **all** contracts with the array you post. ```json { "company": "varma", "contractNumber": "55-1234567X", "id": null } ``` | Field | Notes | |---|---| | `company` | The provider: `ilmarinen`, `elo`, `varma`, `veritas`, `apteekkien`, `verso`, `pensionsAlandia`, `kevaMunicipal`, `kevaState`, `kevaChurch`, `kevaKela`, `kevaAland`, `valio`, `other`, or `none`. `none` means no contract and clears `contractNumber`. `etera` appears only in old data | | `contractNumber` | The provider's contract number, for example `55-1234567X`. The key of the granular endpoint | | `pensionPercent` | Custom percent. Leave it unset to use the provider's default, returned read-only as `pensionDefaultPercent` | | `pensionDiscountPercent` | Discount percent, when the provider has granted one | | `startDate`, `endDate` | Optional validity, as ISO 8601 dates; `endDate` is inclusive. `null` means valid without limit. A future `startDate` keeps the contract inactive until then | | `subOrgCode` | Sub-organisation code for the Incomes Register, when the provider requires one | Read-only: `id` (send `null` for a new contract), `status` (`undefined`, `checked` or `pending`) and `pensionDefaultPercent`. ## Insurance contracts The employer's statutory accident insurance and group life insurance are one contract object in the `calc.insuranceContracts` array. There is **no granular endpoint**: write them only through the round trip. This is the part you change: ```json { "calc": { "insuranceContracts": [ { "isPartnerInsurance": false, "company": "fennia", "contractNumber": "41-1234567", "insurancePercent": 0.7, "groupLifeInsurancePercent": 0.06, "id": null, "startDate": null, "endDate": null } ] } } ``` | Field | Notes | |---|---| | `company` | The insurer: `lähiTapiola`, `pohjola`, `if`, `fennia`, `aVakuutus`, `aktia`, `pohjantähti`, `tryg`, `ålands`, `turva`, `redarnas`, `folksam`, `alandia`, `protector`, `other`, `pending` (not chosen yet), or `none` (knowingly no insurance; clears `contractNumber`). Send the non-ASCII values in UTF-8 exactly as written | | `contractNumber` | The accident-insurance contract number | | `insurancePercent`, `groupLifeInsurancePercent` | Percents used to estimate the insurance amounts | | `isPartnerInsurance` | `true` when the insurance is arranged through a partner insurance | | `startDate`, `endDate` | As for pension contracts | Read-only: `id` (send `null` for a new contract) and `status`. ## Payment channel config Some payment channels need values of the company's own before they can pay for it, such as an agreement id from the payment provider and the bank account that the provider debits. That is the company's **payment channel config**, at most one per channel. **v04 beta:** This endpoint is in v04 only and may change. There is no v03 equivalent. Which channels the company uses stays in `payments.channels` and is Salaxy's. Your provisioning notes say which channel needs a config, and its channel key. The OpenAPI reference lists the path once for each channel that takes a config, with that channel's key in place of `{channel}`; a channel without a config has no path. | Method | Path | Purpose | |---|---|---| | GET | `/v04/api/settings/payment-channels/{channel}/config` | Read; the version is in the `ETag` header | | PUT | `/v04/api/settings/payment-channels/{channel}/config` | Create or replace: `201` the first time, then `200`; safe to retry | | PATCH | `/v04/api/settings/payment-channels/{channel}/config` | Change named fields, as a JSON Merge Patch (`Content-Type: application/merge-patch+json`) | | DELETE | `/v04/api/settings/payment-channels/{channel}/config` | Remove; `204` | The configs also show in the settings as `payments.channelConfigs`, read-only. `POST /settings/company` ignores that field, so the round trip can never change or erase a config. For a channel that needs a debit account and an agreement id: ```json { "debitAccount": { "iban": "FI21 1234 5600 0007 85" }, "data": { "agreementId": "AG12345678" } } ``` `debitAccount.bic` is filled in from a Finnish IBAN when omitted. `data.agreementId` is required, at most 35 characters. Salaxy stores the IBAN without spaces. - **Concurrent writes.** Send the `ETag` you read as `If-Match` on `PUT`, `PATCH` or `DELETE`. If the config changed in between, the write fails with `412`. `If-None-Match: *` makes a `PUT` create-only. - **Errors** are [problem details](https://code.salaxy.com/reference/errors.md#problem-details-on-new-v04-endpoints). Branch on `type` or the status. A `422` lists messages per field. ## What payment needs Do not over-build the settings screens. Of everything above, only a usable **payment channel** is a company setting that payment requires. | Setting | Required to pay? | |---|---| | Payment channel on the payroll (defaults from `payments.defaultChannel`) | Yes | | Employer IBAN and `sepaBankPartyId` | No gate. They are read when a SEPA file is made. A missing value is a warning in the settings check | | Pension contract | No gate. Without one the calculation runs as a temporary employer, and the employer's street, city and postal code become required | | Business ID | Not checked at payment | The other payment gates are on the account (`isVerified`: see [Customer account creation](https://code.salaxy.com/integration/customer-accounts.md#verification-what-isverified-blocks)) and on the calculation. A calculation that fails validation blocks payment. ## Test it - Create a test company: [Get a test account](https://code.salaxy.com/get-started/test-account.md), or [Customer account creation](https://code.salaxy.com/integration/customer-accounts.md). - `GET /v03/api/settings/company` and keep a copy. Change `payments.invoice.ibanNumber`, post the whole object, and read it again. Every other sub-object must be identical to your copy. - To see why the rule exists, post the object without `accounting` on a throw-away test company, and read it again. - Add a pension contract through `POST /v03/api/settings/pensionContracts`, then through the round trip, and compare. - Test data and helpers: [Test endpoints and test data](https://code.salaxy.com/reference/test-endpoints.md). ## Checklist - You never post a hand-built settings object: every write starts from a fresh `GET`. - You change only the sub-object your screen owns and post the rest unchanged. - Pension contracts use the granular endpoint when they are the only change; insurance contracts and the bank account go through the round trip. - You send `null` as `id` for a new contract and do not edit `status` or `pensionDefaultPercent`. - Your screens do not block payment on missing IBAN or pension; they warn instead. - With the embedded Salaxy UI (build path 1), its settings screens are used and this page is skipped. **Next:** [Accounting firm account creation](https://code.salaxy.com/integration/accounting-firm-accounts.md) --- Source: https://code.salaxy.com/integration/accounting-firm-accounts.md # Accounting firm account creation If your customers are accounting firms that serve further companies, each firm gets its own **accounting firm account** in Salaxy. The firm then sees only its own customer companies, in the Salaxy Pro site or through the Pro API. You create the firm account first, and then create its customer companies under it. Examples use the **test** environment; see [Environments](https://code.salaxy.com/get-started/environments.md) for demo and production. *Diagram: Three tiers. Your technical account is at the top. Under it sits an accounting firm account for each accounting firm, created first. Under each accounting firm account sit the customer companies of that firm, created with the accounting firm's account id as proxyPartner. Every customer company has exactly one parent. (Create the accounting firm account first. Then create each customer company with the accounting firm's account id as `proxyPartner`.)* ## Which fits you? ### Three tiers: accounting firms under you Use this when your customers are accounting firms that run payroll for their own customer companies. Each firm is an accounting firm account, and its companies sit under it. The firm works in Salaxy Pro or through the [Pro API](https://code.salaxy.com/integration/pro-api.md). Everything below is for you. ### Two tiers: companies directly under you Use this when you onboard the companies yourself, with no third-party accounting firm in between, even if a company is itself an accounting firm. Create every company as a regular customer: [Customer account creation](https://code.salaxy.com/integration/customer-accounts.md), without `proxyPartner`. Skip this page. **Three tiers: how it works:** A customer company has exactly one parent: your technical account, or an accounting firm account, never both. The payment channel belongs to your technical account and flows down to every tier through service models. The tiers are explained in [Account structure](https://code.salaxy.com/integration/account-structure.md). ## How it works The accounting firm is created with the same call as a customer company. | Method | Path | Purpose | |---|---|---| | POST | `/v03/api/partner/company` | Assure the accounting firm account for the firm's Business ID | | POST | `/v03/api/partner/company` with `proxyPartner` | Create a customer company under that accounting firm (see [Customer account creation](https://code.salaxy.com/integration/customer-accounts.md)) | The same call exists as `/v04/api/partner/company`. The fields, response and errors are in [Partner-initiated account creation](https://code.salaxy.com/security/account-creation.md). The account type follows from the Business ID: an accounting firm gets the accounting firm role (*Tilitoimisto*). 1. **Create the firm.** Call with the firm's Business ID as `officialId`. Do **not** set `proxyPartner`: the firm is itself the proxy tier. 2. **Store `accountId`.** It becomes the `proxyPartner` value for the firm's customers. 3. **Create each customer** with `proxyPartner` set to that `accountId`. ```http POST https://test-secure.salaxy.com/v03/api/partner/company Authorization: Bearer {technical-account-token} Content-Type: application/json ``` ```json { "officialId": "7654321-1", "partnerAccountId": "firm-42", "language": "fi", "email": "firm@example.com" } ``` ```json { "accountId": "FI00POYA0007654321", "avatar": { "displayName": "Example Accounting Oy", "initials": "EA" }, "isVerified": false, "isAuthorized": true, "partnerAccountId": "firm-42" } ``` Then create a customer company under the firm: ```json { "officialId": "1234567-8", "partnerAccountId": "customer-4711", "proxyPartner": "FI00POYA0007654321" } ``` ### Rules - **Trusted partner role.** Required in production, not in test. - **The accounting firm role.** The account must carry the accounting firm (*Tilitoimisto*) role. It is normally enabled in test. In production, ask Salaxy if the role has to be granted. - **Safe to repeat.** A second call with the same `officialId` returns the existing account. A `partnerAccountId`, once set, must be sent on every later call for that account. - **You must be authorised to the firm.** `proxyPartner` fails with `400` if the account does not exist, or if you do not have access to it. - **The parent is set only once.** Salaxy sets the parent on creation only for a company that has none. A company that already sits under another provider keeps it. To move a company to a firm, or to detach it, use `POST` or `DELETE /v01/api/pro/accounts/{accountId}/partner` ([Pro API](https://code.salaxy.com/integration/pro-api.md#partner-relationship-management)). The caller of that endpoint becomes the parent, and must already have access to the company. - **Service model.** After creating the firm, ask Salaxy to give it its own default service model, so that its customers inherit the payment channel and the accounting model: [Service models](https://code.salaxy.com/integration/service-models.md). ## After creation - **Acting as the firm.** With the Pro API token endpoint, a token for the firm is minted from your technical account, and a token for one of its customers from the firm's token, level by level; that endpoint cannot skip a level. See [Pro API](https://code.salaxy.com/integration/pro-api.md#account-discovery-and-token-minting). With the JWT flow you can instead sign in as the customer directly and name the firm in the `salaxy_proxy_act` claim: [Impersonation](https://code.salaxy.com/security/impersonation.md). - **The firm's view.** The firm's users, or you acting for them, list the customers with `GET /v01/api/pro/accounts` and search across them with the other Pro endpoints. - **Certificate.** A firm that files under its own Business ID needs a valid Incomes Register certificate, or its customers' payments are refused. See [Customer account creation](https://code.salaxy.com/integration/customer-accounts.md#verification-what-isverified-blocks). ## Test it - Create the firm on `test-secure.salaxy.com` with a Business ID of a company that really exists: the trade register is the production one, and a made-up ID is refused. - Create a customer company with `proxyPartner` set to the firm's `accountId`. Then list the firm's customers with the Pro API and check that the company is there. - Create a second customer without `proxyPartner` and check that it is **not** in the firm's list. - Call the firm creation twice and check that the `accountId` is the same. ## Checklist - You create the accounting firm account before its customers, and store its `accountId`. - You never set `proxyPartner` on the firm's own creation call. - You pass the firm's `accountId` as `proxyPartner` on every customer creation. - You use the Pro API re-point, not a second creation call, to move an existing company. - In a two-tier set-up you skip this page. **Next:** [Pro API (accounting firm tier)](https://code.salaxy.com/integration/pro-api.md) --- Source: https://code.salaxy.com/integration/pro-api.md # Pro API (accounting firm tier) The Pro API (`/v01/api/pro/...`) is the endpoint family for accounting firms: one cross-tenant view over every customer account an accounting firm — or a partner acting as one — is authorised to run payroll for. Examples use `test-*` URLs. See [Environments](https://code.salaxy.com/get-started/environments.md) for `demo-*` and production hosts. ## Who uses it, and when - **One audience** — a user signed in as an **accounting firm account**, or a partner acting on behalf of one, on the Salaxy Pro site. - **One scope** — a cross-tenant view of every customer company the accounting firm is authorised for. Multi-tenant filtering is baked into the server-side search; you never pass an account filter yourself. - **Three-tier integrations only.** The Pro API is used when there is an accounting firm tier between the partner and the customer company (partner → accounting firm → customer company). Two-tier integrations — a partner that operates customer accounts directly, with no accounting-firm layer — do not call the Pro API; they use the per-company `/v0X/api/...` endpoints instead. For the account roles and the Pro-vs-Company-site split, see [Account structure](https://code.salaxy.com/integration/account-structure.md). To browse the endpoints, see the [Pro API reference](https://code.salaxy.com/reference/rest/v04/pro.md). ## Session and credentials | Endpoint | Method | Purpose | |---|---|---| | `/v01/api/pro/session` | GET | Returns the Pro session, including the active service model. | | `/v01/api/pro/credentials` | GET | Lists the credentials available to the Pro session. | | `/v01/api/pro/accounts/{accountId}/token` | GET | Mints a token scoped to one customer company the accounting firm is authorised for. | Get the Pro session: ```http GET https://test-secure.salaxy.com/v01/api/pro/session Authorization: Bearer {your-pro-token} ``` ## Account discovery and token minting | Endpoint | Method | Purpose | |---|---|---| | `/v01/api/pro/accounts` | GET | Lists the customer companies the Pro session is authorised for. | | `/v01/api/pro/authorizingAccounts` | GET | Lists the accounts that have authorised this accounting firm. | Two constraints shape multi-tier walks: - **`/accounts` prepends the current account itself** — skip the first entry when recursing; the rest are the accounts that have authorised this session. - **`/accounts/{id}/token` mints only for an account that *directly* authorised the current session.** A technical account → accounting firm → customer company walk must therefore impersonate **level by level**: mint the accounting firm token from the technical account session, then mint the customer company token *from the accounting firm token*. You cannot mint a grandchild's token straight from the technical account session. *Diagram: From the technical account session you mint the accounting firm token. From the accounting firm token you mint the customer token. A dashed arc from the technical account straight to the customer token is marked as not allowed: you cannot mint the customer token directly. (Level-by-level token minting: each token is minted from the level directly above it.)* ## Partner-relationship management These endpoints set or remove the **primary-partner** link on a customer company — which accounting firm account owns the relationship. Setting the primary partner is what gates the `waitingPartnerApproval → paymentAllowed` flow downstream. | Endpoint | Method | Purpose | |---|---|---| | `/v01/api/pro/accounts/{accountId}/partner?serviceModelId={id}` | POST | Sets the accounting firm as primary partner for the customer company, using the named service model. | | `/v01/api/pro/accounts/{accountId}/partner` | DELETE | Removes the primary-partner relationship. | Set the primary partner: ```http POST https://test-secure.salaxy.com/v01/api/pro/accounts/{accountId}/partner?serviceModelId={serviceModelId} Authorization: Bearer {your-pro-token} ``` The `proxyPartner` field used at account creation is the other side of the same relationship: `proxyPartner` threads a *new* customer company under an accounting firm account at creation time, while `POST .../partner` re-points an *existing* customer company. ## Cross-account search (OData) The search endpoints query the indexes owned by the Pro session's authorised accounts. They accept standard OData `$filter`, `$top`, `$skip`, `$orderby`, and `$select`, plus a free-text `$search` parameter; the server enforces a maximum page size. See [Queries and paging](https://code.salaxy.com/reference/queries.md) for the query syntax. Multi-tenant scoping is automatic: you do not pass an account filter, and a forged `accountId` in `$filter` can only *narrow* within the authorised set — it never widens it. An accounting firm account cannot read customer companies that belong to a different accounting firm. | Endpoint | Returns | |---|---| | `/v01/api/pro/payrolls` | Payrolls across the accounting firm's book (e.g. those in `waitingPartnerApproval`). | | `/v01/api/pro/calculations/editable` | Editable salary calculations (filter shape baked in — see below). | | `/v01/api/pro/calculations/readonly` | Paid and in-flight calculations (filter shape baked in — see below). | | `/v01/api/pro/invoices` | Invoices. | | `/v01/api/pro/workers` | Workers. | | `/v01/api/pro/messages` | Messages. | | `/v01/api/pro/files` | Files. | | `/v01/api/pro/taxcards` | Tax cards. | | `/v01/api/pro/records` | Records. | | `/v01/api/pro/ir-epr` | Incomes Register earnings-payment reports. | | `/v01/api/pro/ir-psr` | Incomes Register payer-summary reports. | | `/v01/api/pro/household-years` | Household yearly summaries. | | `/v01/api/pro/settings` | Account settings. | | `/v01/api/pro/customers` | Customers (free-text + OData). | | `/v01/api/pro/customers/{refDate}` | Customers for the period that contains a reference date. Not OData: the query takes `periodType` (month by default) and, for a custom period, `endDate`. | The two `/calculations/...` filter shapes are baked into the server — they are not OData arguments you can override: - **`editable`** — calculations in `draft`, `proDraft`, `waitingApproval`, `template`, `sharedWaiting`, `sharedApproved`, or `sharedRejected`. - **`readonly`** — calculations whose payment has started: `paymentStarted`, `paymentSucceeded`, `paymentCanceled`, `paymentRefunded`, `paymentError`, plus internal copies and `feePending`. Find payrolls waiting for partner approval: ```http GET https://test-secure.salaxy.com/v01/api/pro/payrolls?$filter=status eq 'waitingPartnerApproval' Authorization: Bearer {your-pro-token} ``` ## Approvals are save-driven The Pro API exposes **no** `/approve` or `/decline` endpoint. Two gated transitions on the accounting firm's side are instead driven by saving the entity with a target status through the standard endpoints: | Transition | How to drive it | |---|---| | `waitingPartnerApproval → paymentAllowed` (the accounting firm approves a payroll waiting for it) | Fetch the payroll, set `info.status = "paymentAllowed"`, and save it via the standard payrolls endpoint. | | `proDraft → draft` (the accounting firm releases a calculation so the company can see it) | Fetch the calculation, set `workflow.status = "draft"`, and save it via the standard calculations endpoint. | Because there is no dedicated approve/decline response, confirm the transition by re-reading the saved entity's status field rather than by checking a response code. The save runs the same validation and snapshotting pipeline as an ordinary edit. For the statuses themselves, see [the payroll lifecycle](https://code.salaxy.com/integration/payroll-lifecycle.md). ## Boundary with the Company API The Pro endpoints answer *"across my whole book"*. Their non-Pro counterparts — the standard `/v0X/api/...` endpoints **without** the `pro/` prefix — answer *"for this one company"* and back the Salaxy Company site. A partner that provisions both a Pro UI and a Company UI from the same integration chooses which family to call by the account type the user signed in as. ## Reference Browse the full endpoint list: - [Pro API in the v04 reference (beta)](https://code.salaxy.com/reference/rest/v04/pro.md) — static page for the Pro endpoints. - [Interactive v04 reference](https://code.salaxy.com/reference/rest-api-v04.md) — run requests against this site's API environment. The same endpoints are in the v04 reference under `/v04/api/pro/`; this guide uses the `/v01/api/pro/` addresses, which serve them too. **Next:** [Employees and employments](https://code.salaxy.com/integration/employments.md) --- Source: https://code.salaxy.com/integration/employments.md # Employees and employments In Salaxy an employee is an **employment**: the link between a worker (the person) and a customer company (the employer). Every salary calculation is built from one. This page is the full topic; the first call is in [3. Create employees](https://code.salaxy.com/get-started/rest/create-employees.md). Examples use the **test** environment; see [Environments](https://code.salaxy.com/get-started/environments.md) for demo and production. Authenticate as the **employer** (the customer company): see [Impersonation](https://code.salaxy.com/security/impersonation.md). *Diagram: An employment links a worker, the person, to a customer company, the employer. The employment carries the terms: type, pension, tax card handling and salary defaults. Your own HR data creates and updates the employment with POST /v03/api/employments, and keeps your own employee id in info.sourceId. (Purple: held by Salaxy. You create and change the employment; Salaxy keeps the worker record behind it.)* ## The model - **Worker.** The person, identified by Personal ID. Holds name, contact details and bank account. One worker can be employed by several companies. Once the worker registers with Salaxy, they maintain their own personal data. - **Employment.** The link between one worker and one company. Holds the employment period, type, pension and insurance setup, tax card handling and salary defaults. There can be several employments for the same worker and company, over time or at once. You never create a worker directly. Every save of an employment, create or update, first resolves the worker record and creates one if it cannot find it. The result is in `info.workerAccountId`. Salaxy resolves the worker in this order: 1. `info.workerAccountId`, if your request carries it. This is the reliable route. 2. Otherwise Salaxy looks the Personal ID up among this company's employments in the search index, and reuses the worker record it finds there. 3. Otherwise a **new worker record** is created from `identity` and the `default` contact. **Keep `info.workerAccountId` from the create response and send it on every later employment for the same person.** Rule 2 depends on the search index, which fills a while after a write. If you send only the Personal ID and the index has not caught up, a second employment lands on rule 3 and creates **two worker records for one Personal ID**. Nothing rejects this, so prevent it yourself. Once the worker has registered, the employment reads `isRegistered: true`. The name, language and contact details you send then no longer overwrite the worker's own. Contact values that differ are kept on the employment as an `employerOverride` entry in `contacts[]`. ## Endpoints | Method | Path | Purpose | |---|---|---| | `POST` | `/v03/api/employments` | Create (no `id` in the body) or update (with `id`). There is no `PUT` | | `GET` | `/v03/api/employments` | Find and list. OData query; see [Queries](https://code.salaxy.com/reference/queries.md) | | `GET` | `/v03/api/employments/{id}` | Read one full employment | | `GET` | `/v03/api/employments/active?date=YYYY-MM-DD` | List the employments active on one day (default: today). Reads storage directly, not the search index | | `DELETE` | `/v03/api/employments/{id}` | Delete. For the test environment; in production, end the employment instead | The list is scoped to the account you act as, so a plain `GET /v03/api/employments` returns only that company's employments. ## Create The request is in [3. Create employees](https://code.salaxy.com/get-started/rest/create-employees.md). Field shapes that are easy to get wrong: - `info.type` is the employment type: `monthlySalary`, `hourlySalary`, `salary` and so on. A fixed-term employment is marked with `info.isFixedTerm`, not with a type. - `info.taxcard` is a string: `auto`, `manual`, `noTaxCard` or `taxAtSource`. See [Tax cards](https://code.salaxy.com/integration/tax-cards.md). - `info.pensionCalculation` is `employee` for the standard employee pension. - `contacts[]` entries have a `type` (`default`, `workerAccount`, `employerOverride`, `foreign`) and typed fields such as `email` and `telephone`. - **Always send `info.startDate`.** It is not required to create, but without it the end date and ending reason of the employment are never reported to the Incomes Register, even though everything validates. You find out only when the employee leaves. - `info.sourceId` is your own employee id. It is exposed as the filterable `externalId`. Pension and insurance defaults can also come from [Company settings](https://code.salaxy.com/integration/company-settings.md). ### Personal IDs A Personal ID is six date digits, a century separator, a three-digit person number and a check character. A save fails with **HTTP 400** and the title `Invalid Personal ID` if: - neither `identity.personalId` nor `info.workerAccountId` is in the body (the message shows a blank id); - the Personal ID does not parse (the message echoes the value). A save that has to create a new worker record (rule 3) fails with **HTTP 400** and the title `Names are required` if `identity.firstName` or `identity.lastName` is blank. What does not parse: - **The separator** must be one of `+ - A B C D E F U V W X Y`. `A`-`F` mean the 2000s, `-` and `U`-`Y` the 1900s, `+` the 1800s. Look-alikes fail: an en dash (U+2013), a non-breaking hyphen (U+2011), spaces around the separator, a zero-width space. - **The check character** must be correct. Generate it with a Finnish Personal ID library. - **The date** must be real: `310296` fails even with a correct check character. Leading and trailing whitespace is trimmed. **A temporary Personal ID** has a person number of 900 or more, for example `190372-942M`. It is valid and creating the employment works as usual. But the worker's **postal address becomes mandatory before a calculation validates**: send `street`, `postalCode` and `city` in the `default` contact. Without them the calculation saves as a draft with `isValid: false` and cannot be paid. The calculation errors are `Calc.MissingWorkerContactStreet`, `Calc.MissingWorkerContactPostalCode` and `Calc.MissingWorkerContactCity`. Street is reported first; the other two appear only after you fill it in. The samples on this site use a temporary ID on purpose, so a real person's ID is never printed. ## Find Both lookups read a search index that fills a short while after a write. An employment is **not findable the instant you create it**, and an empty list does not prove the write failed. ```http GET /v03/api/employments?$filter=externalId eq 'client-emp-4711' HTTP/1.1 Host: test-secure.salaxy.com Authorization: Bearer eyJhbGc... ``` ```http GET /v03/api/employments?$filter=otherPartyInfo/officialId eq '190372-942M' HTTP/1.1 Host: test-secure.salaxy.com Authorization: Bearer eyJhbGc... ``` - **Your own id:** `$filter=externalId eq ''`. - **Personal ID:** `$filter=otherPartyInfo/officialId eq ''`, an exact match. `$search=other:` builds the same filter for you. A plain `$search=` is a free-text search and can match other rows. - **Paging:** omit `$top` and follow `nextPageLink`. See [Queries](https://code.salaxy.com/reference/queries.md). Keep the `id` from the create response. For a list you can rely on right away, use `/active`. ### The `date` parameter of `/active` - Send a plain `YYYY-MM-DD`. Both ends of the employment are inclusive. - **An unparseable `date` silently means today**, with `200 OK`. `2026-02-30`, `15.04.2026`, an empty `date=` and an un-encoded `+` all behave so. Validate the date before sending. - **An employment with no `info.endDate` is returned only up to tomorrow.** Do not use `/active` to look further ahead. - **An employment with no `info.startDate` counts as starting today**, so it is never returned for a past date. ## Update `POST` the employment back with its `id`. **The save replaces the whole object, it is not a patch.** Any block you leave out is reset. Read, change, post the complete object: ```http POST /v03/api/employments HTTP/1.1 Host: test-secure.salaxy.com Authorization: Bearer eyJhbGc... Content-Type: application/json { "id": "EMP123", "identity": { "firstName": "Pauliina", "lastName": "Palkkanen", "personalId": "190372-942M", "language": "fi" }, "info": { "workerAccountId": "d7c1f2a4-0000-0000-0000-000000000000", "type": "monthlySalary", "pensionCalculation": "employee", "ibanNumber": "FI3718834100118709", "taxcard": "auto", "startDate": "2023-11-15", "sourceId": "client-emp-4711" }, "work": { "description": "Chief care of Fifi", "occupationCode": "51640", "wageBasis": "monthly" } } ``` Posting only the fields to change clears the rest: `type`, `pensionCalculation`, `taxcard`, `sourceId`, `startDate` and the whole `work` block revert. The omitted `info` also drops `info.workerAccountId`, so the employment is linked to a **new** worker record and the old one is left behind. A body with `info` but without `identity` fails with `400`, unless `info.workerAccountId` is present. ## End an employment When an employee leaves, **end the employment, do not delete it.** Ending keeps the history the Incomes Register needs. Set these on `info` and post the whole object as above: - `endDate`: the last day of the employment. - `isTerminated`: `true`. - `employmentEndingCode`: the reason. - `status`: `archived`. ```json { "id": "EMP123", "identity": { "firstName": "Pauliina", "lastName": "Palkkanen", "personalId": "190372-942M", "language": "fi" }, "info": { "workerAccountId": "d7c1f2a4-0000-0000-0000-000000000000", "type": "monthlySalary", "pensionCalculation": "employee", "taxcard": "auto", "startDate": "2023-11-15", "sourceId": "client-emp-4711", "endDate": "2026-06-30", "isTerminated": true, "employmentEndingCode": "jointAgreement", "status": "archived" }, "work": { "description": "Chief care of Fifi", "occupationCode": "51640", "wageBasis": "monthly" } } ``` | `employmentEndingCode` | Reason | |---|---| | `employeesResignation` | The employee resigned | | `other` | Some other reason | | `terminationGroundsRelatedToEmployeesPerson` | Grounds related to the employee personally | | `financialAndProductionRelatedGrounds` | Financial or production-related grounds | | `jointAgreement` | Ended by joint agreement | | `retirement` | Retirement | | `terminationOfaFixedTermEmployment` | A fixed term ran out | Use the name, not the Incomes Register number. - **The reason is reported only when `startDate` and `endDate` are both set** along with the code. A code without an end date is stored but not filed. - **Set `status` to `archived` yourself.** It is not derived from `isTerminated`. An employment left at `unknown` is treated as active, including by the yearly tax card update. - **Each calculation takes the code as it was when the calculation was created.** Changing the employment later does not change what was already filed; that needs an Incomes Register correction. - **Reversing:** post the object with `isTerminated: false`, `endDate: null`, `employmentEndingCode: null`, `status: "primary"`. This does **not** retract anything already filed, so do not clear an ending that was already filed. For a genuinely new period, create a **new** employment: the Incomes Register reports employment periods. ## Delete (test only) `DELETE /v03/api/employments/{id}` cascades, so use it only in test: - An unknown `id` returns `404`. - **Any** linked calculation, draft or paid, blocks the delete with `400` (`Työsuhdetta ei voi poistaa`). Delete the calculations first. - Linked holiday years and absences are deleted with the employment. - If it is the worker's only employment, their tax cards and worker record go too. In test it is usually easier to discard the whole test company than to unwind it employment by employment. ## Sync from your own HR data Treat your system as the master and Salaxy as the place that needs the payroll fields. 1. **Keep a mapping** per employee in your own database: your employee id, the Salaxy employment `id` and `info.workerAccountId`. Write it from the create response. 2. **Set `info.sourceId`** to your employee id on create. It lets you find the employment again if you lose the mapping. 3. **New employee:** look up by `externalId` only if you have no mapping, allowing for index lag; otherwise create. Send the stored `info.workerAccountId` when the person already has another employment with the company. 4. **Changed data:** `GET` the employment, change the fields, `POST` the complete object. 5. **Leaver:** end the employment as above. Do not delete. 6. **Reconcile:** compare your active employees with `GET /v03/api/employments/active`, not with a list that depends on the index. For many employees at once there is also `POST /v03/api/import/workers`, which creates or assures employments in bulk (see [Worktime import](https://code.salaxy.com/integration/worktime-import.md)). ## Test it 1. Get a test account: [Get a test account](https://code.salaxy.com/get-started/test-account.md). 2. Create an employment with a temporary test Personal ID and a street address. 3. Create a second employment for the same person, sending `info.workerAccountId`. Check that the response keeps the same worker id. 4. End the first employment and read it back: `isTerminated`, `endDate` and `status` should be as posted. ## Checklist - You store the employment `id` and `info.workerAccountId` from every create response. - You always `GET`, change and `POST` the **whole** employment. You never post a partial body. - You always send `info.startDate`, `work.occupationCode` and an IBAN, and the street address for temporary Personal IDs. - You end employments with `endDate`, `isTerminated`, `employmentEndingCode` and `status: "archived"`, not with `DELETE`. - Your code does not depend on the search index being current right after a write. **Next:** [Tax cards](https://code.salaxy.com/integration/tax-cards.md) --- Source: https://code.salaxy.com/integration/tax-cards.md # Tax cards Salaxy withholds tax from each salary using the employee's **tax card** (*verokortti*). In nearly every case you let Salaxy fetch the card automatically; you set one by hand only when you must. Examples use the **test** environment; see [Environments](https://code.salaxy.com/get-started/environments.md) for demo and production. *Diagram: Two sources feed the tax card that Salaxy keeps for an employee: the automatic card, which Salaxy fetches from the Tax Administration, and a manual card that you set through the REST API. The salary calculation uses the card to work out the withholding tax. (Purple: Salaxy. The automatic card needs nothing from you except info.taxcard: "auto".)* ## Which fits you? ### Automatic card Fits almost everyone: Salaxy fetches the card from the Tax Administration, and refreshes it. **Automatic card: how it works:** Set `info.taxcard` to `auto` on the [employment](https://code.salaxy.com/integration/employments.md). Salaxy asks the Tax Administration for the card. You send nothing else. | Method | Path | Purpose | |---|---|---| | `POST` | `/v03/api/taxcards/auto-set` | Fetch and set the automatic card now. Query: `personalId`, `taxPercentMinimum`, `salaryDate` (default: today) | | `POST` | `/v03/api/taxcards/auto-refresh` | Check cards again. Query: `taxcardIds`, `salaryDate`, `forceUpdate` | | `GET` | `/v03/api/taxcards/current` | The current cards of all non-terminated employments of the employer | | `GET` | `/v03/api/taxcards/current/{paymentDate}` | The same for a payment date | | `GET` | `/v03/api/taxcards/employment/{id}` | All current cards of one employment. Query: `paymentDate` | - **The income type is always salary** for an automatic card at the moment. - **A refresh is skipped if the card was checked within 2 days.** `forceUpdate=true` skips that rule. If nothing changed, only the last-checked date is updated; if something changed, a new card is created. - **Around the turn of the year,** the current card may be the one for next year: in December and January `current` can return next year's card. - The worker can set a **minimum percentage** (`taxPercentMinimum`) that is withheld even when the card's percentage is lower. ### Manual card Fits when you hold the card yourself, for example a paper or PDF card, or a percentage the employer has agreed. **Manual card: how it works:** Set `info.taxcard` to `manual` on the employment, then save a tax card for it. | Method | Path | Purpose | |---|---|---| | `GET` | `/v03/api/taxcards/new` | A blank card to fill in | | `POST` | `/v03/api/taxcards` | Create or update a card | | `GET` | `/v03/api/taxcards/{id}` | Read one card | | `DELETE` | `/v03/api/taxcards/{id}` | Delete a card | | `GET` | `/v03/api/taxcards` | Find cards. OData query; see [Queries](https://code.salaxy.com/reference/queries.md) | ```http POST /v03/api/taxcards HTTP/1.1 Host: test-secure.salaxy.com Authorization: Bearer eyJhbGc... Content-Type: application/json { "employmentId": "EMP123", "card": { "personalId": "190372-942M", "forYear": 2026, "kind": "defaultYearly", "taxPercent": 10, "incomeLimit": 10000, "taxPercent2": 40, "validity": { "start": "2026-01-01", "end": "2026-12-31" } } } ``` | Field | Meaning | |---|---| | `employmentId` | The employment the card is for | | `card.personalId` | The Personal ID as written on the card | | `card.forYear` | The year the card is valid for. Typically from February of that year to January of the next | | `card.taxPercent` | The percentage as a percentage: 50 means 50 %, not 0.5 | | `card.incomeLimit` | The income up to which `taxPercent` applies | | `card.taxPercent2` | The percentage for the part of the income above the limit | | `card.kind` | `defaultYearly`, `replacement`, `noWithholdingHousehold`, `others`, `historical`, `noTaxCard` or `auto` | | `card.validity` | The validity dates as expressed on the card | Saving a card for an employment that already has paid calculations can check them and add the difference to the card's income log. The card is a separate `Taxcard` object, not a field of the employment or the calculation. When a calculation is recalculated, Salaxy picks the card valid for its payment date by the worker's Personal ID and copies it into the calculation. ## Other endpoints | Method | Path | Purpose | |---|---|---| | `POST` | `/v03/api/taxcards/calculate` | Calculate the withholding tax for a given card. Query: `income`, `paymentDate` (decides the tax year) | | `POST` | `/v03/api/taxcards/reload-calcs/{id}` | Rebuild the income log from the paid calculations. Does not save | | `GET` | `/v03/api/taxcards/shared-exists/{personalId}` | Before the employment exists: is there a card the worker has shared? | | `POST` | `/v03/api/taxcards/approve/{method}` | Approve or reject a worker-shared card. `method` is `assureWaiting`, `approve` or `reject`. Query: `ownedId` or `sharedUri` | A card carries a `state`: `new`, `approved`, `employerAdded`, `verifiedVero`, `sharedWaiting`, `sharedApproved`, `sharedRejected`, `sharedRejectedWithoutOpen` or `shared`. ## Rules to know - **An employment left at status `unknown` is treated as active** by the yearly tax card update. End employments properly: see [Employees and employments](https://code.salaxy.com/integration/employments.md#end-an-employment). - **A manual card is yours to keep current.** Check `forYear` and `validity` against the salary dates you pay. ## Test it In the test environment, set `info.taxcard` to `auto` and read the card with `GET /v03/api/taxcards/employment/{id}`. To control what the Tax Administration answers for a test Personal ID, use the test-data tax card endpoint: see [Test endpoints and test data](https://code.salaxy.com/reference/test-endpoints.md). For a manual card, post the sample above for your test employment and check the result with `POST /v03/api/taxcards/calculate`. ## Checklist - `info.taxcard` is `auto` unless you have a reason to hold the card yourself. - For a manual card, `info.taxcard` is `manual` and the card has a `forYear` and validity matching the salary dates. - You post percentages as percentages (10, not 0.1). - Ended employments are set to `archived`, so the yearly update treats them as ended. **Next:** [Dimensions (cost centres)](https://code.salaxy.com/integration/dimensions.md) --- Source: https://code.salaxy.com/integration/dimensions.md # Dimensions (cost centres) A **dimension** is a cost-accounting tag such as a cost centre, project or department. Push your own dimensions into Salaxy, tag salary calculations with them, and the accounting data you read back carries your coding. Examples use the **test** environment; see [Environments](https://code.salaxy.com/get-started/environments.md) for demo and production. The endpoints are account-scoped: the company is the one you act as, see [Impersonation](https://code.salaxy.com/security/impersonation.md). *Diagram: Dimensions have two layers. A definition is the catalogue, for example Project with its options; you push it to Salaxy through the settings endpoints. A value is the usage: a salary calculation or one of its rows is tagged with a dimension id and an option. The accounting data that Salaxy produces carries the values on each ledger entry. (You push the catalogue once; every calculation then carries values from it into the accounting data.)* ## Two layers | Layer | What it is | Where it goes | |---|---|---| | **Definition** (`CostAccountingDimensionDefinition`) | The catalogue: `id`, `label`, `options[]`, `allowCostSharing`, `scope` | The settings endpoints below | | **Value** (`CostAccountingDimension`) | The usage: `{ id, value, percent }` | On the calculation, **not** through the settings endpoints | An option in `options[]` has a `value`, a `text` and, for hierarchies, a `path` (the path to the option, not including the value itself). `scope` says where the dimension is offered: `none`, `calculation`, `row` or `hidden`. A value goes in `accounting.dimensions` on a whole calculation, or in `accounting.dimensions` on a single row. `percent` splits one cost between several values. It needs `allowCostSharing: true` on the definition. ## Which fits you? ### You master the catalogue Fits when your system is the only place where dimensions are edited. Post the whole list every time. **You master the catalogue: how it works:** Use `POST /v03/api/settings/dimensions/all`. It **replaces** all definitions with the ones you post. A definition you leave out is **deleted**. If a customer can also edit dimensions in the Salaxy user interface, a periodic `/all` push silently discards their edits. Use this option only when you are sure they cannot. ### Salaxy and the customer share the catalogue Fits when dimensions are also edited in Salaxy, or you push only changes. **Shared catalogue: how it works:** Save or remove **one** definition at a time with `POST /v03/api/settings/dimensions` and `DELETE /v03/api/settings/dimensions/{id}`. Definitions you do not touch stay as they are. ## Endpoints | Method | Path | Purpose | |---|---|---| | `GET` | `/v03/api/settings/dimensions` | All definitions of the account | | `GET` | `/v03/api/settings/dimensions/{id}` | One definition | | `POST` | `/v03/api/settings/dimensions` | Save **one** definition | | `DELETE` | `/v03/api/settings/dimensions/{id}` | Remove one definition | | `POST` | `/v03/api/settings/dimensions/all` | **Replace all** definitions with the posted array | A definition: ```json { "id": "project", "label": "Project", "allowCostSharing": true, "scope": "calculation", "options": [ { "value": "P100", "text": "Website renewal" }, { "value": "P200", "text": "Mobile app" } ] } ``` A calculation tagged with a value (only the relevant part is shown). A row uses the same shape in its own `accounting.dimensions`. The `percent` field of a value is for cost sharing; check its scale in the [REST reference](https://code.salaxy.com/reference/rest-api.md) before you use it. ```json { "accounting": { "dimensions": [ { "id": "project", "value": "P100" } ] } } ``` ## Where definitions live | Container | Effect | |---|---| | Account settings (`costAccounting.dimensions`) | The company's own catalogue. This is what the endpoints above read and write | | Service model (`costAccounting.dimensions`) | Defaults handed from your technical account down to every customer company. Provisioned by Salaxy, so it is a project decision, not code you write. See [Service models](https://code.salaxy.com/integration/service-models.md) | The [company settings](https://code.salaxy.com/integration/company-settings.md) page covers the other parts of the settings object. ## Reading values back Accounting data carries a `dimension` field on each ledger entry. See [Accounting data](https://code.salaxy.com/integration/accounting-data.md). ## Test it 1. Post a definition with `POST /v03/api/settings/dimensions` and read it with `GET /v03/api/settings/dimensions`. 2. Create a calculation (see [Salary calculations](https://code.salaxy.com/integration/calculations.md)) and add the value to `accounting.dimensions`. 3. Read the accounting data for the calculation and check that the entries carry the `dimension` values. ## Checklist - You decided who masters the catalogue: you (`/all`) or shared (single save and delete). - You never post a partial list to `/all`. - Values go on the calculation or row, not through the settings endpoints. - `percent` is used only on dimensions with `allowCostSharing: true`. **Next:** [Worktime import](https://code.salaxy.com/integration/worktime-import.md) --- Source: https://code.salaxy.com/integration/worktime-import.md # Worktime import Worktime software already knows who worked how much. **Import** moves that data into Salaxy as rows on salary calculations in a draft payroll, so the payroll only has to be reviewed and paid. It is an optional REST part of an [embedded white label](https://code.salaxy.com/white-label/index.md) integration (build path 1), and works the same when you build your own UI (build path 2). Examples use the **test** environment; see [Environments](https://code.salaxy.com/get-started/environments.md) for demo and production. *Diagram: Four steps left to right. Your worktime system holds the hours. An import, through the REST API or the Data Agent, sends them to Salaxy. Salaxy puts them into a draft payroll as rows of salary calculations. The payroll is then reviewed and paid. (The import creates draft calculations. Calculation, payment and filing are the same as for any other payroll.)* ## Which fits you? ### Import through the REST API Fits when your system can call Salaxy directly. **Live.** **REST API: how it works:** Two steps: make sure the employees exist, then post the rows. | Method | Path | Purpose | |---|---|---| | `POST` | `/v03/api/import/workers-check` | Check that workers exist. The id can be a Salaxy worker id, an employment id or a Personal ID | | `POST` | `/v03/api/import/workers` | Create or assure employments in bulk | | `POST` | `/v03/api/import/calculations` | Add calculations with rows to a new or existing payroll | **The calculation import never creates workers or employments.** Create them first with [Employees and employments](https://code.salaxy.com/integration/employments.md) or `/import/workers`, or every calculation fails. Post an array. Each item is one calculation for one worker: ```http POST /v03/api/import/calculations?isMerge=true&rowMergeOption=removeImportedRows&sourceId=hours-2026-04 HTTP/1.1 Host: test-secure.salaxy.com Authorization: Bearer eyJhbGc... Content-Type: application/json [ { "officialId": "1234567-8", "parameters": { "payroll": { "input": { "title": "Hours April 2026" } } }, "item": { "worker": { "paymentData": { "socialSecurityNumber": "190372-942M" } }, "workflow": { "salaryDate": "2026-05-05" }, "info": { "workStartDate": "2026-04-01", "workEndDate": "2026-04-30" }, "rows": [ { "rowType": "hourlySalary", "message": "Hours in April", "count": 152, "price": 18, "unit": "hours" } ] } } ] ``` | Field | Meaning | |---|---| | `officialId` | The employer's business ID. Optional: it defaults to the company you act as. If you act for several companies, always send it, or the calculation is booked on the account you act as | | `item.worker.paymentData.socialSecurityNumber` | The worker's Personal ID. Required | | `item.worker.employmentId` | The employment. Optional. Without it Salaxy picks the best match | | `item.workflow.salaryDate` | The salary date. Empty or invalid: Salaxy computes one | | `item.info.workStartDate`, `workEndDate` | The work period | | `parameters.payroll.input.title` | The payroll title. Empty: `Palkkalaskelmat yyyy-MM-dd` | | `item.rows[]` | The rows. `rowType` and `price` are what a row needs; `count` defaults to 1 | The response is the same array with `validation` and `result` on each item. `result.status` is `success`, `warning`, `error` or `ignored`. Query options of `/v03/api/import/calculations`. **Send `isMerge=true`:** `rowMergeOption` and the `sourceId` stamping below apply only in merge mode. | Option | Effect on an existing calculation | |---|---| | `isMerge=true` | Merge the posted rows into the worker's existing calculation in the payroll, as the options below say | | `rowMergeOption=removeAllRows` | Replace all rows with the posted ones | | `rowMergeOption=removeImportedRows` | Replace only rows from the same dataset (same `sourceId`). `sourceId` is required with this option | | *(not set)* | Append the posted rows | | `sourceId` | Dataset id, stamped on every row without its own `sourceId` | | `applyEmploymentDefaultRows` | Also add the salary default rows of the employment | The importer used by the Salaxy user interface sends `isMerge: true`, `rowMergeOption: "removeAllRows"` and `applyEmploymentDefaultRows: false`. ### Import through the Data Agent (MCP) Fits when an AI agent maps and loads the data instead of code you write. [Coming] **Data Agent: how it works:** The Data Agent is the MCP server for Finnish payroll that brings payroll data in from other systems: import plans, source datasets, transformations and import runs. Its endpoints are published when it opens. Until then use the REST API. See [MCP servers](https://code.salaxy.com/reference/mcp.md) and [MCP or REST?](https://code.salaxy.com/about/mcp-or-rest.md). ## How the REST import behaves - **The payroll is found by company, salary date and title**, among **draft** payrolls only. If none matches, a new payroll is created. Re-importing after the payroll has left draft creates a **second** payroll with the same title and salary date. - **A worker has one calculation per payroll.** Inside the payroll, an existing calculation for the same Personal ID is updated, not duplicated. - **Each Personal ID may appear once in one request.** The check ignores the company, so the same person employed by two customers must go in separate requests. - **Employments are found through the search index.** An employment created moments before the import may not be found yet, and the calculation then fails with a missing-worker error. Retry after a short wait. - **Validation per calculation:** the Personal ID is present and valid; `officialId` is valid, the company exists and you have access to it; the employment exists. Failures come back in `validation`, one calculation at a time. - **Several employments for one person:** without `item.worker.employmentId`, Salaxy ranks them: not terminated, valid on the salary date, closest start date, closest end date, newest. Send the employment id when a worker can have more than one. - **`info.paymentChannel` on a calculation overwrites the payroll's channel.** Mixed values in one payroll: the last wins. - **Row source ids:** with `isMerge=true`, a row without `sourceId` gets the request's `sourceId`, or the calculation id. Per-row source ids can be set only through the API. - **Re-runs:** post the same `sourceId` with `removeImportedRows` to replace what a previous run imported, without touching rows added by hand. See [Idempotency](https://code.salaxy.com/reference/idempotency.md). ## Working-time rows Pay for working time is a row like any other. Three row types hold the time-based additions: | `rowType` | Use | |---|---| | `workingTimeCompensation` | One compensation, reported under the code of its `data.kind` (for example `eveningWorkCompensation`, `saturdayPay`, `sundayWorkCompensation`, `overtimeCompensation`, `nightWorkAllowance`) | | `hourlySalaryWithWorkingTimeCompensation` | An hourly salary and its compensation on one row; the compensation is priced as a percentage of the hourly rate | | `tesWorktimeShortening` | The construction-sector separate salary component | ```json { "rowType": "workingTimeCompensation", "message": "Evening work compensation", "count": 12, "price": 2.10, "data": { "kind": "eveningWorkCompensation" } } ``` - **Salaxy sets no rates.** No Salaxy dataset holds the amounts of these additions: they come from the applicable collective agreement. Your system sends the price; Salaxy does not know which agreement applies and does not check the amount. - **Send `data.kind`.** A `workingTimeCompensation` row without a kind is not reported to the Incomes Register. - **One kind per `hourlySalaryWithWorkingTimeCompensation` row.** For several kinds on one payslip, send one row per kind. - The plain rows `overtime`, `eveningAddition`, `nightimeAddition`, `saturdayAddition` and `sundayWork` report the same codes as lump sums. Prefer them for an amount typed by a person, and the compensation row when the code comes from an integration. All row types are in the [REST reference](https://code.salaxy.com/reference/rest/import.md). ## Test it 1. Create a test employment ([Employees and employments](https://code.salaxy.com/integration/employments.md)). 2. Post the sample above with `isMerge=true`, `rowMergeOption=removeImportedRows` and a `sourceId`, using your test company's business ID. 3. Check `result.status`, then find the draft payroll by its title and salary date: it should hold one calculation with your row. 4. Post the same request again. The payroll and the calculation are reused; the row is replaced, not doubled. ## Checklist - Employments exist before the import. The import never creates them. - Each request has each Personal ID once. - `officialId` is always sent when you act for more than one company. - You use `isMerge=true`, a stable `sourceId` per dataset and `removeImportedRows`, so a re-run replaces rows. - You read `result.status` and `validation` for every item. - Working-time rows carry `data.kind` and a price from the collective agreement. **Next:** [Payroll lifecycle and statuses](https://code.salaxy.com/integration/payroll-lifecycle.md) --- Source: https://code.salaxy.com/integration/payroll-lifecycle.md # Payroll lifecycle and statuses How a payroll, the salary calculations inside it and the invoices they produce move through their statuses, from creation to payment to closure. The same lifecycle applies whether your integration uses the [REST API](https://code.salaxy.com/get-started/rest/index.md) or an agent on the [MCP server](https://code.salaxy.com/get-started/agentic/index.md). ## The three entities - **Payroll** (*palkkalista*) — a pay event that groups one or more salary calculations under one pay date. - **Salary calculation** (*palkkalaskelma*) — the calculation for one worker: gross salary, deductions, taxes, net salary. - **Invoice** (*lasku*) — a **payment instruction** sent to a payment channel: a bank, an accounting system or a partner integration. A calculation produces a `net` invoice for the worker's salary, plus invoices for the authorities. ## How they relate - A salary calculation can exist on its own (a single payment) or belong to a payroll. - **The payroll's status is derived from its calculations.** The payroll succeeds only when *every* calculation succeeds, and reverts only when *every* calculation reverts; partial states leave it unchanged. - **Invoices are generated automatically** when the payment is committed — you never create them. - **The `net` invoice is the central event.** When the channel reports it paid, the calculation closes. On a customer funds account channel the `gross` invoice takes this role instead: see [Customer funds account](#customer-funds-account-channels) below. ## The default flow *Diagram: Six steps: the employer creates the payroll, commits the payment, the channel reads and then pays the net invoice, tax and union invoices are released in the day-6 monthly run and paid, and the payroll closes. Before the net invoice is paid, the payment can be cancelled and the payroll returns to draft. (Green: paid and closed. Orange, dashed: cancelling before the net invoice is paid.)* In six lines: 1. The employer creates a payroll → payroll `draft`, calculations `payrollDraft`. 2. The employer commits the payment → invoices are generated; payroll and calculations become `paymentStarted`; the `net` invoice goes `unread`, the `tax` and `union` invoices `preview`. 3. The channel reads the net invoice → `net: read`. 4. The channel pays the net invoice → `net: paid`, calculation `paymentSucceeded`. 5. The `tax` and `union` invoices are finalised in the monthly run on day 6 of the following month, released as `unread`, and paid → `tax: paid`, `union: paid`. 6. Once every calculation has succeeded → payroll `paymentSucceeded`. The invoice statuses you actually handle are `unread`, `read`, `paid` and `canceled` — plus `preview` for the periodic `tax` and `union` invoices until the monthly run finalises them. ### Customer funds account channels When Salaxy pays from a customer funds account, the employer pays Salaxy first: - **A `gross` invoice is added.** It is the employer's payment of the whole payroll to Salaxy, created at commit in addition to the other invoices. - **The `gross` invoice drives the calculation.** When it is paid, the calculations become `paymentSucceeded`. A `paid` report on the `net` invoice does not change the calculation on these channels. - **`paymentSucceeded` here means Salaxy has received the employer's funds**, not that the worker is paid. Salaxy pays the worker, the tax and the other recipients after that. See [Payment channels](https://code.salaxy.com/integration/payment-channels.md#salaxy-pays-from-a-customer-funds-account). ## Statuses These tables list the **main** statuses an integration meets. Values are shown as the API serialises them, in lowerCamelCase. Match them exactly when filtering, querying or comparing. The full enums are the `PayrollStatus`, `CalculationStatus` and `InvoiceStatus` schemas in the [REST API reference](https://code.salaxy.com/reference/rest-api.md). ### Payroll | Status | What it means | |---|---| | `draft` | Created, not yet submitted for payment. Editable. | | `waitingPartnerApproval` | Waiting for the other party, for example the accounting firm, to process it. Used by the [Pro API](https://code.salaxy.com/integration/pro-api.md). | | `paymentAllowed` | Approved for payment by the company or the accounting firm. Used by the [Pro API](https://code.salaxy.com/integration/pro-api.md). | | `paymentStarted` | Payment is in progress; calculations and invoices have been created. | | `paymentSucceeded` | All calculations have been paid or otherwise handled. **Final** — cannot be edited. | | `paymentCanceled` | All calculations have been cancelled or refunded. | ### Salary calculation | Status | What it means | |---|---| | `draft` | A standalone calculation, not yet submitted for payment. | | `payrollDraft` | A draft that is already part of a payroll. | | `proDraft` | A draft made by the accounting firm, hidden from the company until it is released. | | `waitingApproval` | Waiting for approval, and possibly input, from the company. | | `sharedApproved` | A calculation a worker shared with the employer, which the employer has approved. | | `paymentStarted` | Payment is in progress. | | `paymentSucceeded` | The channel has confirmed the payment. The normal end state. On a customer funds account channel it means Salaxy has received the employer's funds (see [above](#customer-funds-account-channels)). | | `paymentCanceled` | Cancelled by Salaxy after the payment started. An employer's cancel before payment returns the calculation to `payrollDraft` instead (see [Cancelling a payment](#cancelling-a-payment)). | | `paymentRefunded` | Cancelled by Salaxy and refunded to the employer. | | `paymentError` | The payment failed and needs manual attention. | A payment can be committed from `draft`, `payrollDraft`, `proDraft`, `waitingApproval` and `sharedApproved`; see [Set for payment](https://code.salaxy.com/get-started/rest/set-for-payment.md). ### Invoice | Status | What it means | |---|---| | `preview` | A real but not yet final invoice. The periodic `tax` and `union` invoices stay here until the day-6 monthly run finalises them and releases them as `unread`. A `preview` invoice may still be regenerated — **do not pay against it**. | | `forecast` | An informational estimate, **never released to a payment channel**. Used by the forecast-only types `pension` and `unemployment`; the amount is reported and paid outside Salaxy. | | `unread` | Released to the payment channel, not yet picked up. | | `read` | The payment channel has fetched the invoice. | | `paid` | The channel has reported the invoice paid. | | `canceled` | The invoice was cancelled. | ## Invoice types A calculation produces two groups of invoices: **payable** invoices, which move through a payment channel and drive the flow above, and **forecast-only** invoices, which Salaxy never sends to a channel. ### Payable | Type | What it is | |---|---| | `net` | The worker's take-home salary. The trigger of the flow — paying it closes the calculation. | | `gross` | Only on customer funds account channels: the employer's payment of the payroll to Salaxy. On those channels it replaces `net` as the trigger. | | `tax` | The employer's combined payment to the Tax Administration (see sub-types below). | | `foreclosure` | Wage garnishment (*ulosmittaus*) to the enforcement authority. | | `union` | Trade union membership fee (*AY-jäsenmaksu*). Periodic like `tax`: created as `preview`, released in the day-6 monthly run. Not the Employment Fund contribution — that is `unemployment` below. | **Tax sub-types are rows inside the `tax` invoice, not separate invoices:** `taxWithholding` (*ennakonpidätys*), `taxSocialSecurity` (employer's health insurance contribution, *sava-maksu*) and `taxAtSource` (*lähdevero*). ### Forecast-only Always `forecast`: informational estimates, never released to a channel. The responsible party reports and pays the amount directly. | Type | What it is | |---|---| | `pension` | Earnings-related pension insurance contribution (TyEL, *työeläkemaksu*). The employer reports and pays it with their pension company. | | `unemployment` | Unemployment insurance contribution to the Employment Fund (*Työllisyysrahasto*). The Fund bills the employer separately. | **There is no insurance invoice.** The two mandatory insurance contributions Salaxy calculates are the forecast-only types above. Accident insurance (*tapaturmavakuutus*) and group life insurance produce no invoice at all: Salaxy stores the contract, but the insurance company bills the employer directly. ## When an invoice becomes `unread` `unread` means *released to the payment channel and waiting to be picked up* — the status your integration polls for. Invoices do not all reach it at the same time, and some never do. | Type | Becomes `unread` | Status before that | |---|---|---| | `net` | Immediately, when the payment is committed | Does not exist yet | | `foreclosure` | Immediately, when the payment is committed | Does not exist yet | | `tax` | Day 6 of the month *after* the salary month, in the monthly run | `preview` from commit until then | | `union` | Day 6 of the month after the salary month, in the same run | `preview` from commit until then | | `pension` | Never | `forecast`, permanently | | `unemployment` | Never | `forecast`, permanently | This is the timing on most payment channels. A few channels release the `tax` and `union` invoices as soon as all their salaries are paid, and customer funds account channels work differently: see [Monthly cycle](https://code.salaxy.com/integration/monthly-cycle.md#what-the-invoices-do). So one commit gives you the `net` invoice at once, and the `tax` and `union` invoices up to five weeks later. **Pay the `net` invoice as soon as it appears** — do not wait for a complete set. ## Three reasons an expected invoice never appears A calculation does *not* produce one invoice of every type. None of these is an error: 1. **Nothing to pay.** When a type's amount is zero, or the type does not apply, the invoice is created as `canceled`. A worker with no union deduction produces no `union` invoice. 2. **Zero total, already settled.** A zero-total invoice may be set straight to `paid` without being released. Whether this happens depends on the payment channel. 3. **Retroactive salary.** When a calculation carries `workflow.salaryDateKind: inPast` ([retroactive salary](https://code.salaxy.com/integration/calculations.md#salary-date-and-retroactive-salary)), the worker was already paid outside Salaxy, so no money moves. On many channels the `net` and `foreclosure` invoices are created as `paid` and never released — also channel-specific. Cases 2 and 3 are **fixed for a given payment channel**, not decided per invoice. Confirm with Salaxy which applies to yours; building for both is safe. ## What this means for polling - **Poll for `unread`, then act on what is there.** Do not compute an expected invoice set and treat a shortfall as a failure. - **Never assume a fixed number of invoices per calculation.** It varies by employer, period and channel. - **Keep polling after the salary month closes.** The `tax` and `union` invoices for a January salary appear on 6 February. - **A quiet invoice is not a stuck invoice.** Salaxy never times an invoice out. ## Cancelling a payment - **Before the `net` invoice is paid, the whole payroll reverts.** While the payroll is `paymentStarted` and no invoice is `paid`, the employer can cancel: each invoice is cancelled through its channel, every calculation returns to `payrollDraft`, and the payroll returns to `draft` with its pay date cleared. It can then be edited and submitted again. - **Cancelling after payment.** On most payment channels, reporting a paid `net` invoice `canceled` moves its calculation to `paymentCanceled`, and the earnings payment report is withdrawn. On customer funds account channels only Salaxy can cancel a paid `gross` invoice. Refunds (`paymentRefunded`) are handled by Salaxy. ## In the agentic path The same lifecycle holds for an agent. The [`payroll-process` skill](https://code.salaxy.com/reference/skills.md#payroll-process) explains it to the agent — what a status means and what happens next — and the tools for payrolls and invoices are listed with their status in [Availability](https://code.salaxy.com/about/availability.md#by-skill-area). Committing a payment always needs a person's approval ([Permissions and human approval](https://code.salaxy.com/security/permissions.md)). ## Related - [Core concepts](https://code.salaxy.com/about/concepts.md) — account, worker, employment, calculation, payroll - [Monthly cycle](https://code.salaxy.com/integration/monthly-cycle.md) · [Invoices and payments](https://code.salaxy.com/integration/invoices-and-payments.md) · [Set for payment](https://code.salaxy.com/get-started/rest/set-for-payment.md) · [Track the payment status](https://code.salaxy.com/get-started/rest/track-status.md) **Next:** [Salary calculations](https://code.salaxy.com/integration/calculations.md) --- Source: https://code.salaxy.com/integration/calculations.md # Salary calculations A **salary calculation** (*palkkalaskelma*) is the payslip as a data object: you send **rows** (hours, amounts, expenses), Salaxy applies the Finnish pay rules and returns the **result** — gross, taxes, net pay and the employer's cost. You never calculate tax or side costs yourself. Examples use the **test** environment (`test-secure.salaxy.com`); see [Environments](https://code.salaxy.com/get-started/environments.md) for demo and production. *Diagram: You send a salary calculation with rows such as hours and amounts. The Salaxy engine applies the pay rules, tax and side costs. You read back the result: the worker's net pay, the employer's total cost, and the validation outcome. (Grey: what you send. Purple: what Salaxy does and returns.)* The calculation is the unit of payment. Creating a [payroll](https://code.salaxy.com/get-started/rest/create-payroll.md) groups calculations under one pay date; the [statuses](https://code.salaxy.com/integration/payroll-lifecycle.md#salary-calculation) and the payment flow are in [Payroll lifecycle and statuses](https://code.salaxy.com/integration/payroll-lifecycle.md). This page covers the calculation itself. ## How a calculation looks | Part | What it holds | |---|---| | `workflow` | `status`, and the salary dates: `salaryDate`, `requestedSalaryDate`, `salaryDateKind` | | `employer` | The paying company. `isSelf: true` means the account you act as | | `worker` | The employee. `employmentId` links the [employment](https://code.salaxy.com/integration/employments.md); `accountId` is the worker's account | | `info` | Work period (`workStartDate`, `workEndDate`), `paymentChannel`, `payrollId`, `workerSourceId` and `sourceId` for your own ids | | `rows` | **The input**: one row per pay item | | `result` | **The output**: `totals`, `workerCalc`, `employerCalc`, `validation`, and the Incomes Register rows. Read-only | You write `rows` (and the parts above them); Salaxy fills `result` every time the calculation is saved or recalculated. ## Rows A row says *what* is paid (`rowType`), *how much* (`count` × `price`) and, optionally, a `message` for the payslip. `rowType` is a camelCase string on the wire, never a number. ```json { "workflow": { "status": "payrollDraft" }, "employer": { "isSelf": true }, "worker": { "employmentId": "", "accountId": "" }, "info": { "workStartDate": "2026-08-01", "workEndDate": "2026-08-31" }, "rows": [ { "rowType": "hourlySalary", "count": 35, "price": 65 }, { "rowType": "remuneration", "count": 1, "price": 2500, "message": "Bonus 2026", "data": { "kind": "bonusPay" } } ] } ``` - **Every wage type is a `rowType`**: salary, bonus, overtime, benefits, holiday pay, expense compensations, deductions. Each has a default unit, a default price and the Incomes Register income types it is reported as. The full list is in [Wage types (row types)](https://code.salaxy.com/reference/wage-types.md). - **`data.kind`** picks a variant of a row type, for example `bonusPay` on `remuneration`. Rows with extra detail carry it in `data`: an overtime row, `hourlySalaryWithWorkingTimeCompensation` with `data.kind` `overtimeCompensation`, lists its extra pay in `data.compensationRows` (`unit`, `count`, `price`). - **Units** are `count`, `percent`, `days`, `kilometers`, `hours`, `weeks` or `months`. A row type has a default; set `unit` only to override it. - **Negative prices** are accepted only on `monthlySalary`, `hourlySalary`, `salary`, `timeRatePay`, `compensation`, `expenses` and `irIncomeType`. On other row types a negative price is a validation error. - **Yearly numbers.** Some default prices change every year: daily allowance, partial daily allowance, meal compensation and mileage with the worker's own car. See [Yearly numbers](https://code.salaxy.com/reference/yearly-numbers.md). ## Two ways to build rows ### From the employment For monthly paid employees, the standard rows (monthly salary, recurring benefits) are saved on the [employment](https://code.salaxy.com/integration/employments.md). Salaxy copies them into the calculation; you add only what changes this month. | Method | Path | Purpose | |---|---|---| | `POST` | `/v03/api/calculations/update-from-employment?save=false&updateRows=true` | Replaces the calculation's rows with the employment's rows, and sets the tax card and pension. With `save=false` nothing is stored | Then push the month's rows (overtime, bonus, expenses) into `rows` and save. The same call is used in [Create a payroll](https://code.salaxy.com/get-started/rest/create-payroll.md). ### Your own rows For hourly pay, worktime from your own system or one-off payments, build `rows` yourself from your data. Importing worktime in bulk is in [Worktime import](https://code.salaxy.com/integration/worktime-import.md). ## Endpoints | Method | Path | Purpose | |---|---|---| | `GET` | `/v03/api/calculations/new` | A blank calculation object to fill in | | `POST` | `/v03/api/calculator/recalculate` | Calculates the calculation you post and **stores nothing**. The safe way to try rows | | `POST` | `/v03/api/calculations` | Saves the calculation (create or update) and returns it with `id` and `result` | | `GET` | `/v03/api/calculations/{id}` | Reads one calculation | | `GET` | `/v03/api/calculations?$filter=status eq 'draft'` | Lists calculations; query syntax in [Queries](https://code.salaxy.com/reference/queries.md) | | `DELETE` | `/v03/api/calculations/{id}` | Deletes a calculation | | `POST` | `/v03/api/payroll/validate` | Validates a payroll before it is committed | Saving does not require a valid calculation. See [Validation](#validation) below. ## Reading the result After a save or a recalculation, `result` holds everything the payslip shows. The main parts: | Part | Fields to read | Meaning | |---|---|---| | `result.totals` | `totalGrossSalary`, `totalBaseSalary`, `totalExpenses`, `totalPayable`, `totalTaxable` | The sums of the rows, common to worker and employer | | `result.workerCalc` | `salaryPayment`, `tax`, `pension`, `unemploymentInsurance`, `socialSecurity`, `unionPayment`, `foreclosure`, `totalWorkerPayment` | The worker's side: deductions and what the worker receives | | `result.employerCalc` | `totalSalaryCost`, `mandatorySideCosts`, `pension`, `unemployment`, `socialSecurity`, `palkkaus`, `service`, `finalCost` | The employer's side: side costs and the total cost | - **`workerCalc.salaryPayment` is the net pay.** It is gross minus the worker's deductions. - **`employerCalc.totalSalaryCost` includes the Salaxy fee**, as does `totalPayment`. The cost without the fee is `mandatorySideCosts`, or `totalSalaryCost` minus `palkkaus` and `service`. Compare costs on the same basis, or you will see a difference that is only the fee. - **Deductions come off in a fixed order**, each from what is left: withholding tax, tax at source, foreclosure, salary advance, the worker's pension, unemployment insurance and health insurance contributions, then the union fee, then other deductions. The advance and the three contributions are **capped** at what is left. The union fee and other deductions are **all or nothing**: they are dropped entirely when the full amount does not fit. Do not recompute this in your own code; read `result`. - **A tax card with an income limit** switches to its additional percentage when the year's earlier income passes the limit. The income log is on the tax card, not in the calculation; see [Tax cards](https://code.salaxy.com/integration/tax-cards.md). The invoices Salaxy creates from the result are in [Invoices and payments](https://code.salaxy.com/integration/invoices-and-payments.md). ## Validation **Validation is server-side, and the API returns HTTP 200.** A calculation that fails validation is still saved and returned. The failures are in `result.validation`: ```json { "result": { "validation": { "isValid": false, "hasAllRequiredFields": true, "errors": [ { "key": "result.rows[0]", "type": "invalid", "msg": "Auton päästöarvon tulee olla 0 vuodesta 2026 eteenpäin", "code": "Calc.InvalidCarBenefitEmissionValues" } ] } } } ``` - **`type`** is `general`, `required`, `invalid` or `warning`. `msg` is currently in Finnish. - **Payment is the gate.** Committing a calculation for payment fails when it has any error that is not a `warning`. The failure message is generic ("the calculation is not valid") and does not name the field, so read `result.validation.errors` yourself. - **Check before you commit.** Read `result.validation.isValid` after every save, and call `POST /v03/api/payroll/validate` before [setting a payroll for payment](https://code.salaxy.com/get-started/rest/set-for-payment.md). - **`code` is for your own mapping.** Show your users your own text for the codes you meet; `msg` and `key` are not stable identifiers. HTTP-level failures follow [Errors](https://code.salaxy.com/reference/errors.md). ## Salary date and retroactive salary `workflow.salaryDate` is the day the net salary reaches the worker. You can ask for a date with `requestedSalaryDate`; the server sets the real `salaryDate` from it by the banking-day rules. A date in the past is not accepted as a normal salary: both `recalculate` and a save reset it to today. **Retroactive salary** (*takautuva palkka*) is for a salary that was **already paid** outside Salaxy and only needs to be registered, so it is reported to the Incomes Register on the past pay date. Set `workflow.salaryDateKind` to `inPast` (on a payroll, `input.salaryDateKind`; it is copied to every calculation in it). ```json { "workflow": { "status": "payrollDraft", "salaryDateKind": "inPast", "requestedSalaryDate": "2026-05-29" } } ``` What `inPast` changes: | Area | Behaviour | |---|---| | Salary date | Frozen to the date you give. It is not moved by the banking-day rules | | `net` invoice | Marked `paymentType: "salaryInPast"`. On many payment channels it is created already `paid`, because no money moves. On channels with their own payment workflow it is released as `unread` as usual. This is fixed per channel; confirm yours with Salaxy | | Tax and union invoices | Still generated, unless the salary month is already closed: then they are created as `canceled` | | Pension invoice | Not generated; the pension company bills the employer from the Incomes Register report | | Incomes Register | Reporting still starts when the `net` invoice is `paid`, on your past date. Late filing can bring penalties from the authorities | | Statuses | The calculation still goes `payrollDraft` → `paymentStarted` → `paymentSucceeded` | **Check the value after saving.** `inPast` is honoured only on payment channels that allow retroactive salary. On any other channel it is **silently reset to `default`** on save, with no error, and the calculation is paid as a normal salary. Always read `workflow.salaryDateKind` back from the saved calculation. ## Test it 1. Get a test account and token: [Get a test account](https://code.salaxy.com/get-started/test-account.md). 2. Take an employment from [Create employees](https://code.salaxy.com/get-started/rest/create-employees.md). Test data is in [Test endpoints and test data](https://code.salaxy.com/reference/test-endpoints.md). 3. `GET /v03/api/calculations/new`, fill `worker.employmentId` and one `hourlySalary` row (`count` 35, `price` 65), then `POST` it to `/v03/api/calculator/recalculate`. Expect `result.totals`, `result.workerCalc` and `result.employerCalc` filled in. 4. Add a row with a negative `price` on a type that does not allow it, and expect an error in `result.validation`, not an HTTP error. 5. Save with `POST /v03/api/calculations` and read the calculation back with `GET /v03/api/calculations/{id}`. ## Checklist - Rows are built with `rowType` strings from the [wage types list](https://code.salaxy.com/reference/wage-types.md); you do not calculate tax, pension or side costs yourself. - You read net pay from `workerCalc.salaryPayment` and employer cost from `employerCalc`, and know that `totalSalaryCost` includes the Salaxy fee. - You check `result.validation` after every save, and call `payroll/validate` before committing. - Retroactive salary is checked after saving: `workflow.salaryDateKind` is still `inPast`. - You use `POST /v03/api/calculator/recalculate` for previews and tests, so nothing is stored. **Next:** [Invoices and payments](https://code.salaxy.com/integration/invoices-and-payments.md) --- Source: https://code.salaxy.com/integration/payroll-logic.md # Custom payroll logic **Beta:** Custom payroll logic is in beta. In the test environment, scripts run for every customer. In production, they run only for customers that Salaxy has turned the feature on for. Ask Salaxy before you plan a production customer on it. Salaxy applies the Finnish pay rules for you. Some customers also need their own rules: a collective agreement with a special overtime price, a default row that must always be there, a company's own way of accruing holidays. For these, you write **scripts**: small pieces of JavaScript that Salaxy runs on its servers as part of the calculation. - **Simple rules are one line.** For example, `sxy.prices.employment("hourlySalary") * 0.5` sets the price of an overtime row to half the hourly salary. - **Hard rules are full JavaScript.** You can write classes, functions and helper methods. - **The types are TypeScript.** The interfaces and helpers come from the `@salaxy/expressions` library, so an editor or a coding agent can check a script before it runs. Accounting firms usually edit row type formulas in Salaxy Pro, on the customer's **row types** page, and test them there against a real employment. You can also write all scripts over the REST API, because they are part of the [company settings](https://code.salaxy.com/integration/company-settings.md). ## When the scripts run *Diagram: Four steps. One: before-calculation scripts can change the rows. Two: row type scripts set the values of each row. Three: Salaxy calculates the salary with the Finnish pay rules. Four: after the calculation, scripts can set holiday accruals, holiday pay and pay statistics. (Your scripts run in the light boxes; Salaxy's own calculation runs in the middle.)* Salaxy recalculates a draft calculation each time you save or recalculate it, and sometimes when you load it and its values are out of date. A recalculation usually takes less than a second. | Script | What it changes | Page | |---|---|---| | Before calculation | The whole list of rows: add, remove or change rows | [Before-calculation scripts](https://code.salaxy.com/integration/before-calc-scripts.md) | | Row type | One value of each row of a row type: price, count, message, data and more | [Row type scripts](https://code.salaxy.com/integration/row-type-scripts.md) | | Holiday accruals, holiday pay, pay statistics | Results that are calculated from many calculations | [After-calculation scripts](https://code.salaxy.com/integration/after-calc-scripts.md) | Most rules are row type scripts. Use a before-calculation script only when you must change the list of rows itself. ## Where the scripts are stored Before-calculation and row type scripts are stored in the company settings, in `calc.bleConfigs`. Each entry is one set of scripts with the rules for when it applies: ```json { "calc": { "bleConfigs": [ { "description": "Overtime rules of our collective agreement", "disabled": false, "cbaCode": null, "employeeGroup": null, "startDate": null, "endDate": null, "scripts": { "code": "class Overtime { price(row, ctx, sxy) { return sxy.prices.employment(\"hourlySalary\") * 0.5; } }", "metadata": [ { "interface": "rowTypeScripts", "class": "Overtime", "methods": ["price"] } ] } } ] } } ``` - **`code`** is the JavaScript source of all the classes. - **`metadata`** tells Salaxy which class implements which script interface, and which of its methods to call. Salaxy calls only the methods you list here. - **When it applies.** For each calculation, Salaxy uses the **first** entry that is not disabled and matches the employment's collective agreement (`cbaCode`), its employee group (`employeeGroup`) and the payment date (`startDate`, `endDate`). An empty rule matches everything. Put the most specific entries first. The after-calculation scripts are stored in the holiday and pay statistics settings. See [After-calculation scripts](https://code.salaxy.com/integration/after-calc-scripts.md). To write the settings, use the read, change and post round trip of [company settings](https://code.salaxy.com/integration/company-settings.md): post the whole settings object back, not only `calc`. ## What a script gets Each script method gets three arguments: - **`row`** or the current value: the thing the method may change. - **`ctx`**: the context. For a calculation it holds `ctx.calculation`, `ctx.employment`, `ctx.settings` (the company settings) and `ctx.validation`. - **`sxy`**: helper functions. | Helper | What it does | |---|---| | `sxy.prices.employment(rowType)` | The price of a row type in the employment. If the employment has none, the company's price. | | `sxy.prices.company(rowType)` | The price of a row type in the company settings. | | `sxy.prices.standardHourlySalary(factor)` | The employment's hourly salary that is valid on the work date, times `factor`. | | `sxy.prices.averageHourlyPay(factor, period)` | The average hourly pay of the last quarter or month, or the standard hourly salary if it is higher, times `factor`. | | `sxy.prices.round(value, decimals)` | Rounds a number; two decimals by default. | | `sxy.rows.get(rowType)`, `first`, `last` | The calculation's rows of a row type. | | `sxy.rows.sum(rowType)`, `count` | The total (price × count) or the number of rows of a row type. | | `sxy.dates` | Date helpers. | A row type argument is a row type name such as `"hourlySalary"`, or a function that selects rows: `(r) => r.rowType === "hourlySalary"`. ## Errors and limits - **A script error stops the save.** If a script throws an error, Salaxy does not save the calculation and returns the error message. Test new scripts on a test customer first. - **Scripts run in a sandbox.** Salaxy limits the memory, the number of statements, the recursion depth and the run time of each script. A script cannot call the API or read other customers' data. - **Return `undefined` to keep a value.** A method that returns `undefined` leaves the value as Salaxy calculated it. --- Source: https://code.salaxy.com/integration/row-type-scripts.md # Row type scripts A row type script is a formula for one row type. Each time Salaxy recalculates a calculation, it runs the formula for each row of that type and puts the result in the row. This is the most common way to add a customer's own pay rules. For the big picture, see [Custom payroll logic](https://code.salaxy.com/integration/payroll-logic.md). **Beta:** In production, scripts run only for customers that Salaxy has turned the feature on for. See [Custom payroll logic](https://code.salaxy.com/integration/payroll-logic.md). ## How Salaxy finds the formula 1. Salaxy goes through the rows of the calculation. 2. For each row, it takes the row type name: - a **built-in** row type is the `rowType` of the row, for example `hourlySalary` (the list is on [Wage types](https://code.salaxy.com/reference/wage-types.md)); - a **custom** row type is the last part of the row's `type`: for `/custom/eveningBonus` it is `eveningBonus`. 3. It looks for a class with the same name in the scripts, ignoring case: `HourlySalary` for `hourlySalary`. The class must be listed in the metadata with the interface `rowTypeScripts`. 4. It calls each method that the metadata lists, and writes the result to the row property of the same name. For example, `price()` sets the row's `price`. A method that returns `undefined` keeps the value that the row already has. ## The methods All methods are optional. Each gets `(row, ctx, sxy)`: the row, the [context](https://code.salaxy.com/integration/payroll-logic.md#what-a-script-gets) and the helpers. | Method | Sets | |---|---| | `price` | The unit price. | | `count` | The count, for example hours. | | `message` | The row text on the salary slip. | | `unit` | The unit, for example hours or days. | | `data` | The row type's own data object. | | `kind` | `data.kind`, the sub-type of the row type. | | `period`, `periodStart`, `periodEnd`, `periodDaysCount`, `periodDays` | The row's own period, when it differs from the calculation's period. | | `accounting`, `dimensions` | Accounting data and cost accounting dimensions, such as the cost centre. | | `vatPercent`, `vatEntries` | VAT for expense rows. | | `sourceId` | Your own identifier for the row; Salaxy passes it on. | | `isDeleted` | `true` removes the row from the result. | ## Examples A one-line formula: the price of an overtime row is half the hourly salary of the employment. ```js class Overtime { price(row, ctx, sxy) { return sxy.prices.employment("hourlySalary") * 0.5; } } ``` A longer rule: the overtime price uses the average hourly pay of the last quarter, or the hourly salary if it is higher, and writes it into the row's data so that the user interface can show it. ```js class Overtime { data(row, ctx, sxy) { const price = sxy.prices.averageHourlyPay(0.5, "lastQuartal"); if (row.data?.compensationRows?.length) { row.data.compensationRows[0].price = price; } return row.data; } } ``` The metadata for both classes is `{ "interface": "rowTypeScripts", "class": "Overtime", "methods": ["price"] }` (or `["data"]`). See [Where the scripts are stored](https://code.salaxy.com/integration/payroll-logic.md#where-the-scripts-are-stored). ## Validation A script can add errors or warnings to `ctx.validation`. Use this when the business rule finds something wrong, for example a missing price in the employment. The user sees the message with the calculation. --- Source: https://code.salaxy.com/integration/before-calc-scripts.md # Before-calculation scripts A before-calculation script runs first in each recalculation, before the [row type scripts](https://code.salaxy.com/integration/row-type-scripts.md) and before Salaxy's own calculation. It gets the whole list of rows and returns a new list. For the big picture, see [Custom payroll logic](https://code.salaxy.com/integration/payroll-logic.md). **Beta:** In production, scripts run only for customers that Salaxy has turned the feature on for. See [Custom payroll logic](https://code.salaxy.com/integration/payroll-logic.md). Use it when you must change the list itself: - **Add a default row** when it is missing, for example a fixed monthly allowance. - **Remove rows** that a rule does not allow. - **Split or combine rows.** To set a value of each row of one type, use a [row type script](https://code.salaxy.com/integration/row-type-scripts.md) instead. It is simpler. ## The method Salaxy supports one method today: `getRows(current, ctx, sxy)`. - **`current`** is the list of rows of the calculation. - **`ctx`** is the [context](https://code.salaxy.com/integration/payroll-logic.md#what-a-script-gets): the calculation, the employment and the company settings. - **Return** the new list of rows, or `undefined` to keep the rows as they are. At this step, Salaxy has not yet copied the employment data into the calculation, so the employment snapshot in `ctx.calculation` can be old. Read the employment from `ctx.employment` instead. ## Example Add a monthly salary row with the employment's monthly salary if the calculation has none. ```js class MyRules { getRows(current, ctx, sxy) { if (current.some((r) => r.rowType === "monthlySalary")) { return undefined; } const price = sxy.prices.employment("monthlySalary"); return [...current, { rowType: "monthlySalary", count: 1, price }]; } } ``` The metadata for this class is `{ "interface": "beforeCalcScripts", "class": "MyRules", "methods": ["getRows"] }`. See [Where the scripts are stored](https://code.salaxy.com/integration/payroll-logic.md#where-the-scripts-are-stored). A row that this script adds also gets its row type script, because the row type scripts run after it. ## What a script cannot change - **Employer and worker data.** Salaxy writes these snapshots again before it calculates. - **The result.** Salaxy calculates the totals, the worker and employer sides and the Incomes Register rows; a script cannot write them. A script can add messages to `ctx.validation`. --- Source: https://code.salaxy.com/integration/after-calc-scripts.md # After-calculation scripts Some results need more than one calculation: holiday accruals, holiday pay and pay statistics such as the average hourly pay. Salaxy calculates them with the Finnish rules by default. When a customer has its own rules, you can replace a calculation with a script. For the big picture, see [Custom payroll logic](https://code.salaxy.com/integration/payroll-logic.md). **Beta:** In production, scripts run only for customers that Salaxy has turned the feature on for. See [Custom payroll logic](https://code.salaxy.com/integration/payroll-logic.md). These scripts are not in `calc.bleConfigs`. Each one is stored in its own place in the company settings, next to the rule it replaces. | Method | What it returns | Where the script is stored | When Salaxy uses it | |---|---|---|---| | `getAccruals(calculation, calculations, holidayYear, ctx, sxy)` | The holiday accruals of a calculation, by month | `holiday.holidayAccrualSettings[].script` | The holiday year's holiday code is `script`. | | `getHolidayPay(calculations, holidayYear, ctx, sxy)` | The holiday pay of a holiday year | `holiday.holidayPaySettings[].script` | The holiday pay calculation is `scriptPay`. | | `getPayStatsResult(calculations, ctx, sxy)` | Pay statistics, such as the average hourly pay | `payStats.types[].script` | The pay statistics type's kind is `script`. Only for employments that are paid by the hour. | - **`calculations`** are the calculations of the same employment and period. - **`holidayYear`** is the employment's holiday year. - **`ctx`** holds the employment and the company settings. - **Return `undefined`** to make no change. ## Which setting applies Like the calculation scripts, each setting can be limited to a collective agreement (`cbaCode`) and an employee group (`employeeGroup`). Holiday settings can also be limited to holiday years (`startYear`, `endYear`). A setting with `disabled: true` is skipped. ## Example Pay statistics feed the price helpers: `sxy.prices.averageHourlyPay()` in a [row type script](https://code.salaxy.com/integration/row-type-scripts.md) reads the average hourly pay that the pay statistics store in the employment. ```js class AverageHourlyPay { getPayStatsResult(calculations, ctx, sxy) { // Read the hours and the pay from the rows of the calculations, // and return the result object of the pay statistics type. } } ``` Each script is the source code of one class. Salaxy finds the class with the method it needs, so you do not write metadata for these scripts. --- Source: https://code.salaxy.com/integration/invoices-and-payments.md # Invoices and payments When a payroll is committed, Salaxy generates **invoices**: payment instructions for the net salary, the taxes and the other payables. Your system fetches them, pays them in your bank or accounting system, and **reports the result back**. That loop is what moves a salary calculation to `paymentSucceeded`. It applies when you run a payment channel for your customers, or when you use per-customer tokens to pay on their behalf. Examples use the **test** environment (`test-secure.salaxy.com`); see [Environments](https://code.salaxy.com/get-started/environments.md) for demo and production. *Diagram: Salaxy creates an invoice with the status unread. Your system fetches the unread invoices, marks them read, pays them in your bank, and reports them paid with the salary date. The salary calculation then closes. If you cannot pay in time, you report the invoice as cancelled: the salary returns to draft, and after a correction a new invoice appears. (Purple: Salaxy. Grey: your system. Green: done. Orange, dashed: cancelling.)* **Invoice and payment are the same API object.** There is no separate payment object: you fetch the payment instruction as an invoice, and you report its progress against the invoice `id`. Statuses and the whole flow (net, tax and union invoices, timings, cancelling a payroll) are in [Payroll lifecycle and statuses](https://code.salaxy.com/integration/payroll-lifecycle.md); reading the outcome from the calculation side is in [Track the payment status](https://code.salaxy.com/get-started/rest/track-status.md). Committing is in [Set for payment](https://code.salaxy.com/get-started/rest/set-for-payment.md). ## Which fits you? ### One channel for all your customers You run a payment channel and use **one token** (the technical account's) to serve every customer company whose invoices flow through it. This is the usual partner setup; the channel is set up as described in [Payment channels and SEPA payment files](https://code.salaxy.com/integration/payment-channels.md). **One channel: how it works:** Use the `payment-channel` endpoints. `{channel}` is the channel code provisioned for you. | Method | Path | Purpose | |---|---|---| | `GET` | `/v03/api/payment-channel/{channel}/status/{status}` | Invoices in a status, for example `unread`. Optional `dateKind`, `start`, `end` | | `POST` | `/v03/api/payment-channel/{channel}/update-status` | Reports status changes in a batch | | `GET` | `/v03/api/payment-channel/{channel}/{id}/content` | One invoice as PDF. Optional `inline` | | `GET` | `/v03/api/payment-channel/{channel}/content?ids=` | Several invoices as PDF | | `GET` | `/v03/api/payment-channel/{channel}/{id}/accounting` | Accounting entries of an invoice, see [Accounting data](https://code.salaxy.com/integration/accounting-data.md) | SEPA payment files for the same invoices are fetched from `/v03/api/payment-channel/{channel}/sepa`; see [Payment channels and SEPA payment files](https://code.salaxy.com/integration/payment-channels.md). ### One token per customer company You hold a token for each customer company, or you integrate your own company only. You use the `invoices` endpoints, which return the invoices of the account the token acts as. **One token per customer: how it works:** | Method | Path | Purpose | |---|---|---| | `GET` | `/v03/api/invoices?$filter=status eq 'unread'` | Unread invoices of this account; query syntax in [Queries](https://code.salaxy.com/reference/queries.md) | | `GET` | `/v03/api/invoices/{id}` | One invoice | | `POST` | `/v03/api/invoices/{id}/status/{status}` | Requests a status change, for example `read` or `paid`. Takes only the id and the status | | `GET` | `/v03/api/invoices/{id}/content` | The invoice as PDF | | `GET` | `/v03/api/invoices/{id}/finvoice` | The invoice as Finvoice XML | | `GET` | `/v03/api/invoices/sepa?ids=` | A SEPA payment file for the invoices | Everything below about statuses and dates applies to both options. The same paths are also available under `/v04/api/`; see [API v04](https://code.salaxy.com/reference/rest-api-v04.md). ## The invoice object ```json { "id": "", "header": { "type": "net", "status": "unread", "referenceNumber": "RF2680224521", "date": "2026-03-22", "dueDate": "2026-03-30", "logicalDate": "2026-03-31", "totalExVat": 4026.32, "total": 4026.32, "businessObjects": [""] }, "recipient": { "fullName": "Matti Meikäläinen", "iban": "FI2112345600000785", "bic": "NDEAFIHH" }, "payer": { "officialId": "1234567-8", "avatar": { "displayName": "Acme Oy" } }, "rows": [ { "articleName": "Salary 03/2026", "count": 1, "total": 4026.32 } ] } ``` - **`header.type`** tells what is paid: `net` (the worker's salary), `tax`, `union`, `foreclosure`, and others. The types and the statuses are in [Payroll lifecycle and statuses](https://code.salaxy.com/integration/payroll-lifecycle.md#invoice-types). - **`header.logicalDate` is the salary date.** `header.businessObjects` lists the salary calculations the invoice is based on. `header.externalId` holds your own key, if you stamped one. - **A `tax` invoice is one payment**, however many rows it has. Its parts (withholding, social security contribution, tax at source) are rows inside it, not separate invoices. In a SEPA file it is one transaction. - **Due dates follow the type.** The `net` and `foreclosure` invoices fall due on the working day before the salary date, never earlier than today. The `tax` invoice falls due on the 12th of the month after the salary month, the `union` invoice on the 15th, each moved to the next working day. - **`logicalDate` is the salary date only on `net` and `foreclosure` invoices.** On a `tax` or `union` invoice it is the first day of the salary month. ## The core loop 1. **Fetch.** `GET /v03/api/payment-channel/{channel}/status/unread`. Store what you get. 2. **Mark read.** Report `read` for each invoice you have stored, so it is not handled twice. 3. **Pay.** Pay in your bank or accounting system. 4. **Report paid.** Report `paid` with the salary date. Report in one batch: ```http POST /v03/api/payment-channel/{channel}/update-status HTTP/1.1 Host: test-secure.salaxy.com Authorization: Bearer Content-Type: application/json [ { "id": "", "status": "read" }, { "id": "", "status": "paid", "date": "2026-03-31" } ] ``` Each item is an `InvoiceStatusNotification`. It names the invoice by `id` **or** by your own `externalId`: | Field | Required? | Notes | |---|---|---| | `id` / `externalId` | One of them | The Salaxy invoice id, or your own key, see below | | `status` | Always | `read`, `paid` or `canceled` | | `date` | For `paid` | Must equal `header.logicalDate`. If omitted, Salaxy books **today**. Always send it | | `paymentType` | Optional | `default`, `salary` or `salaryInPast`. If your channel cannot use the requested type, report the one it used | | `referenceNumber`, `receiverFullName`, `receiverIban`, `receiverBic` | Optional | Overrides. Send them only if your process can change them. Changing the reference number usually needs a manual correction by Salaxy | The schema's field descriptions call `date` and `amount` required, but the schema does not enforce either. What the server uses: `date` only when the status is `paid` (as the payment date of the calculation), and `amount` never: a `paid` invoice is booked as paid in full. You can leave `amount` out. ### Rules that save you a day - **Poll, then act.** There is no webhook to subscribe to. A channel can be built to call an outbound trigger, but that is a property of the channel, set up when it is created. Ask Salaxy whether yours has one. - **The status query looks back 14 days by default.** An older invoice is simply not returned: the response is `200` with `[]`, which looks like "nothing to pay". Routine polling can rely on the default. **A catch-up after an outage, a reconciliation or a "why is this invoice missing" check must pass an explicit range**: `?start=2026-01-01&end=2026-12-31`. `dateKind` chooses which date the range filters on: `invoiceDate`, `dueDate` or `logicalDate`. - **Retries are safe.** Re-sending an invoice's current status is accepted as a no-op. - **Stamp your own key.** Send `externalId` with `id` on the first update; it is stored and indexed, and later updates can name the invoice by `externalId` alone. An `externalId` that matches no invoice, or more than one, fails the **whole batch**, so keep it unique per invoice. - **Which event means `paid` is your decision.** The API does not fix it. Common choices, weakest confirmation first: the payment is instructed to your bank, the bank acknowledges it, or it is matched on an account statement. A weaker choice closes the salary sooner but risks reporting `paid` for a payment that later fails. Choose one and apply it consistently. - **`paid.date` is the salary date**, that is `header.logicalDate`, the day the net salary reaches the worker. It is not the date the bank posted the payment. - **Salaxy never times an invoice out.** It stays in its status until you report a change. A payment that your bank rejects, or that is never matched, is yours to withdraw with `canceled`, or to fix and settle. - **Only `net` and `gross` changes reach the calculation.** Reporting `paid` on the `net` invoice closes the calculation; reporting `canceled` on it returns the calculation to `payrollDraft`, or to `draft` if it is not in a payroll. A change on any other invoice type changes only that invoice: cancelling a `foreclosure` or `tax` invoice does not change the calculation, so the salary carries on while that payment simply does not happen. To undo a salary, cancel the `net` invoice. ### Cannot pay by the salary date? Do not report `paid` with a later date. Instead: 1. Cancel the payment in your system. 2. Report `canceled` for the invoice. The calculation returns to `payrollDraft` (or `draft`). 3. A user in the Company or Pro site corrects the salary date and commits the calculation again. 4. A new invoice appears as `unread` with the new `logicalDate`. After the `net` invoice is `paid`, undoing a salary is a Salaxy support action; do not build it into your integration. ## Invoices that do not appear Poll for `unread` and act on what is there. Do not compute an expected set of invoices. Some are created already settled or never released: a zero-amount invoice may be set straight to `paid` on some channels, a retroactive salary may have its `net` invoice created `paid`, and the `tax` and `union` invoices appear only in the monthly run. The reasons are in [Payroll lifecycle and statuses](https://code.salaxy.com/integration/payroll-lifecycle.md#three-reasons-an-expected-invoice-never-appears); the monthly timing is in [Monthly cycle](https://code.salaxy.com/integration/monthly-cycle.md). Invoices of type `payroll`, `fee` or `service` are Salaxy's own service fees. They exist only on a few payment channels. Ask Salaxy whether yours uses them; otherwise you will not see them. ## Optional: PDF, Finvoice and SEPA - **PDF:** the `content` endpoints above, if you want to archive or show Salaxy's rendering of an invoice. - **Finvoice:** `GET /v03/api/invoices/{id}/finvoice`, for e-invoicing and bookkeeping systems. - **SEPA credit transfer** (ISO 20022 `pain.001`): Salaxy can render the payment file for your invoices instead of you building payments from the JSON. Fetching a file is read-only: it does not change any status, so you still report `read`, `paid` or `canceled`. The endpoints, grouping, the `SALA` salary flag and the one-payer rule are in [Payment channels and SEPA payment files](https://code.salaxy.com/integration/payment-channels.md). ## Test it 1. Create a payroll and commit it with the `palkkausManual` channel as in [Set for payment](https://code.salaxy.com/get-started/rest/set-for-payment.md). The `net` invoice appears as `unread`. 2. Fetch it: `GET /v03/api/invoices?$filter=status eq 'unread'`, or, with a channel provisioned for you, `GET /v03/api/payment-channel/{channel}/status/unread`. 3. Report `read`, then `paid` with `date` equal to `header.logicalDate`. 4. Read the calculation with `GET /v03/api/calculations/{id}`. Its `workflow.status` should be `paymentSucceeded`. 5. Repeat with a second payroll and report `canceled` on the `net` invoice instead. The calculation should be back at `payrollDraft`. 6. Fetch with an old `start` date to see the 14-day window at work. ## Checklist - You fetch `unread` invoices on a fixed interval and store them before you report `read`. - Every `paid` carries `date` equal to `header.logicalDate`. - You decided which event stands for `paid`, and a failed or late payment is reported `canceled`. - Catch-up and reconciliation queries pass an explicit `start` and `end`. - Retries re-send the same notification: they are safe. Your own `externalId` is unique per invoice. - You do not expect a fixed set of invoices per calculation. **Next:** [Accounting data](https://code.salaxy.com/integration/accounting-data.md) --- Source: https://code.salaxy.com/integration/accounting-data.md # Accounting data After a salary is paid, the customer's bookkeeping needs the entries: which accounts, which amounts, debit or credit. Salaxy returns them as one **AccountingData** object, posted through an **accounting target** (a chart of accounts and its posting rules). Your accounting software imports it. Examples use the **test** environment; see [Environments](https://code.salaxy.com/get-started/environments.md) for demo and production. *Diagram: Four boxes from left to right. A paid salary calculation in Salaxy. The accounting target, whose chart of accounts and posting rules map each salary component to an account. The AccountingData object with ledger accounts and entries. Your accounting system, which pulls the object with a GET request. Salaxy applies the accounting target when you read the data, not when the salary is paid. (Purple: Salaxy. You pull the same AccountingData object whichever way you select the salaries.)* ## Which fits you? All four options return the same object. They differ in what they select and in how stable the figures are. ### Monthly pull (recommended) Fits an accounting system that imports once per period. **Monthly pull: how it works:** Fetch the period once a month. A good day is the 5th of the next month: the Incomes Register report is due then, so most problems are already resolved. ```http GET /v03/api/reports/accounting/2026-05-01?target=default&periodType=month HTTP/1.1 Host: test-secure.salaxy.com Authorization: Bearer ``` All query parameters are optional: | Parameter | Default | Meaning | |---|---|---| | `target` | your default target | Accounting target id. `default` or no value uses the default target of the account. | | `periodType` | `month` | `month`, `quarter`, `year` or `custom`. Any date inside the period returns the whole period. | | `endDate` | none | End of the period. Required for `custom`, ignored otherwise. | | `periodDateKind` | the account's setting, normally `paidAtDate` | The date that decides whether a calculation is in the period: `paidAtDate`, `salaryDate`, `workDate`, `workDateStart` or `workDateEnd`. The same calculation can fall in different months under `paidAtDate` and `salaryDate`, so choose deliberately. | | `minStatus` | `paymentSucceeded` | Lowest calculation status to include. The default reports paid calculations only. | | `createdFrom` | none | Only calculations created on or after this date. Useful for picking up late additions to a period you have already fetched. | Each call recomputes the period. A salary paid late therefore changes the figures of a month you have already imported. ### Saved monthly report Fits an import that must reconcile: the same month returns the same figures until the report is written again. **Saved monthly report: how it works:** Salaxy writes one accounting report per customer company per month, on the 4th business day (see [Monthly cycle](https://code.salaxy.com/integration/monthly-cycle.md)). List the saved reports as files, then fetch one by its id. ```http GET /v03/api/files?$filter=entityType eq 'MonthlyReport.MonthlyAccounting'&$orderby=logicalDate desc&$top=1 HTTP/1.1 Host: test-secure.salaxy.com Authorization: Bearer ``` ```json { "items": [ { "id": "b7c4e3f1-2a9d-4e58-9f0b-6c1d8a2e5f34", "entityType": "MonthlyReport.MonthlyAccounting", "logicalDate": "2026-05-01", "createdAt": "2026-06-04T02:14:33Z", "updatedAt": "2026-06-04T02:14:33Z", "grossSalary": 12400.00, "payment": 15380.42, "data": { "calculationCount": 8, "workerCount": 3, "officialId": "1234567-8" } } ] } ``` Then fetch the report with the `id`: ```http GET /v03/api/reports/accounting/b7c4e3f1-2a9d-4e58-9f0b-6c1d8a2e5f34?target=default HTTP/1.1 Host: test-secure.salaxy.com Authorization: Bearer ``` - **Filter on `entityType`.** The monthly-report files also hold the PDF and spreadsheet renderings of other reports. - **Order by `logicalDate`.** It is the month the report covers. The default order, `updatedAt desc`, puts a regenerated older month first. - **Name the month** with `and logicalDate eq 2026-05-01` instead of `$top=1`. A `$top` suppresses `nextPageLink`. - **Regenerate** a month's saved report on demand with `POST /v03/api/reports/accounting/{refDate}/close`. It writes the report and returns its id as a string. Two things surprise people: - **Closing does not lock the period.** It rewrites the stored report and re-renders the PDF and spreadsheet. Calculations paid later still change what a period fetch returns. It is a write, so never call it to read. - **The saved data is the calculations, not the postings.** The account numbers are applied when you read, with the `target` you pass. Pass the same target every time, or the same id returns the same figures on different accounts. The saved report uses the account's own `periodDateKind` setting. When that setting is anything other than `paidAtDate`, a salary paid after the 4th business day of the next month is missing from the saved report of its month. A period fetch for that month returns it. Regenerate with `close` if you rely on saved reports. ### By calculation Fits a system that must book every payment on the day it is paid. **By calculation: how it works:** ```http GET /v03/api/reports/accounting?calculationIds=ceabf85e-6d1e-49b4-a738-a7edf1208d82,efe73c17-c00f-4937-b9c5-72b6ce6bae6e&target=default HTTP/1.1 Host: test-secure.salaxy.com Authorization: Bearer ``` The endpoint takes `calculationIds` and `target` only. Poll for newly paid calculations, or react to a payment channel trigger, then fetch their ids. Per-calculation posting is hard to get right. The [holiday pay debt](https://code.salaxy.com/integration/holiday-pay-debt.md) is a monthly balance, not a per-payment figure, so you still need a monthly pull for it. You also need to know whether the calculation is the only one for that worker in the period. Talk to Salaxy support before you choose this method in production. ### By invoice (payment channel owners) Fits a partner that owns a payment channel and tracks invoices instead of calculations. It also fits single late corrections after the monthly pull. **By invoice: how it works:** These routes use the access token of your **technical account**, not a token for one customer. One token reaches every customer served by the channel. See [Invoices and payments](https://code.salaxy.com/integration/invoices-and-payments.md). ```http GET /v03/api/payment-channel/{channel}/{invoiceId}/accounting?target=default HTTP/1.1 Host: test-secure.salaxy.com Authorization: Bearer ``` Several invoices in one call: `GET /v03/api/payment-channel/{channel}/accounting?ids=,&target=default`. - **Net-salary invoices only.** Any other invoice type returns `404`, not an empty report. - **One employer per call.** Ids from more than one employer fail with `400`. Group the ids by employer. - **Optional attachments.** `GET /v03/api/payment-channel/{channel}/{id}/salarySlip?isSensitive=true` returns the salary slip PDF. `isSensitive=true` hides the worker's personal identity code. The invoice PDF is at `.../{id}/content`. ## The AccountingData object ```text AccountingData ledgerAccounts[] one per account number: accountNumber, accountName, accountGrouping, saldo entries[] id, entryDate, description, isDebit, amount, vatPercent, vatAmount, vatRate, accountNumber, accountName, accountGrouping, dimension target, employer, contact, period, summary, officialId, format ``` A shortened sample: ```json { "ledgerAccounts": [ { "accountNumber": "2921", "accountName": "Ennakonpidätysvelka", "accountGrouping": null, "saldo": -706.68, "entries": [ { "id": null, "entryDate": "2025-10-08", "description": "Ennakonpidätykset", "isDebit": false, "amount": 706.68, "vatPercent": null, "vatAmount": null, "vatRate": "undefined", "accountNumber": "2921", "accountName": "Ennakonpidätysvelka", "accountGrouping": null, "dimension": { "calculationId": "efe73c17-c00f-4937-b9c5-72b6ce6bae6e", "calculationTitle": "Test Worker 2025-10-09" } } ] } ], "period": { "start": "2025-10-01", "end": "2025-10-31" }, "summary": { "calculationCount": 2, "workerCount": 2 }, "officialId": "1234567-8" } ``` - **`accountGrouping`** names the entries that are posted together as one accounting row. - **`dimension`** carries the cost-accounting values of the row. See [Dimensions](https://code.salaxy.com/integration/dimensions.md). - **An entry has no income type code.** It identifies itself by account number, name and a Finnish `description`. Where two figures share an account pair, only `description` tells them apart. - **There is no CSV endpoint.** The CSV and Excel files of the embedded UI are built in the browser from this same object. Build your own file from the JSON. ## The accounting target A target defines how a salary result becomes entries. It holds a chart of accounts and a posting ruleset that decides, per income type and per kind of salary, the account, debit or credit, and the grouping. Built-in targets cover the common charts of accounts and accounting software. A custom target is made together with Salaxy support; creating one is not part of the integration. See [Accounting models](https://code.salaxy.com/integration/accounting-models.md) for how a target is assigned to a customer. | Method | Path | Purpose | |---|---|---| | GET | `/v03/api/accounting-target` | List the targets (OData). Identity and status only: **no ruleset**. | | GET | `/v03/api/accounting-target/{id}` | One target in full, with `ruleSet`. Use it to see how anything is posted. | In `ruleSet`, `rows` hold the posting logic and `accounts` the chart of accounts. A row matches by `entryCodeGroup` and `entryCode`, and `isIncluded` says whether it posts. A row has no account number: its `debitId` and `creditId` point into `ruleSet.accounts`. - **An unknown `target` id does not fail.** The request falls back to the built-in default target and returns `200` with entries on other accounts than you asked for. If the accounts look wrong, check the id first. - **A target edit is retroactive.** Postings are applied on read, so an old month returns the new accounts at the next fetch. No response proves what was booked at the time. Keep your own record at import. - **Archived documents are not retroactive.** The PDF and spreadsheet of the monthly cycle are rendered with the default target and keep their account numbers until you call `close` again. ## Holiday pay debt is not in here `summary.holidayCalc` is always `null` in every response on this page, with no error. Holiday pay debt has its own endpoints: see [Holiday pay debt](https://code.salaxy.com/integration/holiday-pay-debt.md). ## Endpoints | Method | Path | Purpose | |---|---|---| | GET | `/v03/api/reports/accounting/{refDate}` | Period report | | GET | `/v03/api/reports/accounting/{id}` | Saved report by id | | GET | `/v03/api/reports/accounting?calculationIds=` | By calculation ids | | POST | `/v03/api/reports/accounting/{refDate}/close` | Regenerate the saved report | | GET | `/v03/api/files` | List saved monthly reports | | GET | `/v03/api/payment-channel/{channel}/{id}/accounting` | One invoice (channel owner) | | GET | `/v03/api/payment-channel/{channel}/accounting?ids=` | Several invoices (channel owner) | The accounting data endpoints are **v03 only**. In the REST reference, see [Reports](https://code.salaxy.com/reference/rest/reports.md), [Accounting target](https://code.salaxy.com/reference/rest/accountingtarget.md) and [Payment channel](https://code.salaxy.com/reference/rest/paymentchannel.md). In `@salaxy/core`: `Reports.getAccountingDataForPeriod()` and `Reports.getAccountingDataForCalculationIds()`. ## Test it 1. Pay a test salary as in [Set for payment](https://code.salaxy.com/get-started/rest/set-for-payment.md). Test data is described in [Test endpoints and test data](https://code.salaxy.com/reference/test-endpoints.md). 2. Call the period report for that month with `target=default`. Expect `200` and your calculation in `summary.calculationCount`. 3. Fetch the target with `GET /v03/api/accounting-target/{id}` and check the accounts against your own chart. 4. In test, a saved report is written on the 4th business day of the next month. To get one sooner, call `close` for the month and fetch the report with the id it returns. See [Monthly cycle](https://code.salaxy.com/integration/monthly-cycle.md). ## Checklist - Choose one pull option per customer and keep the `periodDateKind` the same for every import. - Pass the same `target` every time, and treat a `200` with unexpected accounts as a wrong target id. - Never read holiday pay debt from `summary.holidayCalc`. - Keep your own record of what you booked. Edits to a target change past months. - For channel owner routes, use the technical account token and group invoices by employer. **Next:** [Holiday pay debt](https://code.salaxy.com/integration/holiday-pay-debt.md) --- Source: https://code.salaxy.com/integration/holiday-pay-debt.md # Holiday pay debt Holiday pay debt (*lomapalkkavelka*) is what an employer owes for holiday days earned but not yet taken, plus holiday bonus (*lomaraha*), plus the employer contributions on both. Finnish employers normally book it monthly. If your integration feeds the customer's bookkeeping, you need this pull in addition to [Accounting data](https://code.salaxy.com/integration/accounting-data.md). Examples use the **test** environment; see [Environments](https://code.salaxy.com/get-started/environments.md) for demo and production. *Diagram: Holiday years stored in Salaxy feed a calculation that runs on each request and is never stored. It has two outputs: a report shape with totals per holiday year, and a ledger-posted shape posted through an accounting target. Both go to your books. A warning box below says that every other accounting data response always has an empty holiday pay debt field. (The debt has its own two endpoints. Nothing pushes it and no salary or invoice carries it.)* ## Read this first - **It is computed on request and never stored.** There is no balance to read, no history and no id. Every call recomputes the figure from the stored holiday years. - **It is never pushed.** No webhook or status change announces it. Your system decides when to ask, usually once a month with the [period accounting report](https://code.salaxy.com/integration/accounting-data.md). - **No other response includes it.** The monthly report, a fetch by calculation, a saved report and the payment channel pulls all have `summary.holidayCalc` set to `null`. The call succeeds and reports no debt at all, every month. If a company with employees shows no debt in your bookkeeping, check this first. ## What the figure contains Both endpoints return the same seven figures. Five are employer contributions, so the debt is larger than the accrued gross holiday pay. | Field | Meaning | |---|---| | `totalAccruedHolidayPay` | Accrued holiday pay and holiday compensation | | `totalAccruedHolidayBonus` | Accrued holiday bonus (*lomaraha*) | | `totalAccruedHolidaySocialSecurity` | Health insurance contribution on the above | | `totalAccruedHolidayPension` | Employee pension (TyEL) contribution | | `totalAccruedHolidayUnemployment` | Unemployment insurance contribution | | `totalAccruedHolidayAccidentInsurance` | Accident and occupational disease insurance | | `totalAccruedHolidayGroupLifeInsurance` | Group life insurance | The contributions come from the same calculation engine and rates as an actual salary. ## Which fits you? The endpoints differ in shape and in parameters. Choose by what you do with the result. ### Report shape Fits a system that displays or stores the figure, needs it per holiday year, or posts to its own chart of accounts. **Report shape: how it works:** ```http GET /v03/api/reports/holiday-pay-debt/2026-05-01 HTTP/1.1 Host: test-secure.salaxy.com Authorization: Bearer ``` The only query parameter is `employmentIds`. The route is also available in v04 (`/v04/api/reports/holiday-pay-debt/{refDate}`). ```json { "officialId": "1234567-8", "employer": { "displayName": "Test Company Oy", "initials": "TC" }, "period": { "start": "2025-06-01", "end": "2026-05-31" }, "holidayCalc": { "totalAccruedHolidayPay": 4820.50, "totalAccruedHolidayBonus": 2410.25, "totalAccruedHolidaySocialSecurity": 133.98, "totalAccruedHolidayPension": 1266.53, "totalAccruedHolidayUnemployment": 39.77, "totalAccruedHolidayAccidentInsurance": 51.30, "totalAccruedHolidayGroupLifeInsurance": 4.61 }, "holidayYears": [ { "holidayYear": { "year": 2025, "employmentId": "EMP123" }, "holidayCalc": { "totalAccruedHolidayPay": 3110.00 } }, { "holidayYear": { "year": 2026, "employmentId": "EMP123" }, "holidayCalc": { "totalAccruedHolidayPay": 1710.50 } } ] } ``` The top-level `holidayCalc` is the company total. Each entry in `holidayYears` repeats the seven fields for one holiday year of one employment, so a company with unheld holidays from several years appears several times. The sample shows one field per year for brevity. ### Ledger-posted shape Fits an import straight into bookkeeping, where Salaxy applies the chart of accounts. **Ledger-posted shape: how it works:** ```http GET /v03/api/reports/accounting/2026-05-01/holiday-pay-debt?target=default HTTP/1.1 Host: test-secure.salaxy.com Authorization: Bearer ``` Query parameters: `target` (the [accounting target](https://code.salaxy.com/integration/accounting-data.md#the-accounting-target)), `employmentIds`, and `fromHolidayYear` (count debt only from that holiday year on). **Only this endpoint takes `target` and `fromHolidayYear`.** It is **v03 only**; on v04 use the report shape. The response is an ordinary `AccountingData` object, split by cost-accounting dimension, with zero rows omitted. A shortened sample: ```json { "ledgerAccounts": [ { "accountNumber": "5330", "accountName": "Lomapalkkojen jaksotus", "saldo": 7230.75, "entries": [ { "entryDate": "2026-05-31", "description": "Kertyneet lomapalkat ja lomakorvaukset", "isDebit": true, "amount": 4820.50 }, { "entryDate": "2026-05-31", "description": "Kertyneet lomarahat", "isDebit": true, "amount": 2410.25 } ] }, { "accountNumber": "2962", "accountName": "Lomapalkkamenot (siirtovelat)", "saldo": -7230.75, "entries": [ { "description": "Kertyneet lomapalkat ja lomakorvaukset", "isDebit": false, "amount": 4820.50 }, { "description": "Kertyneet lomarahat", "isDebit": false, "amount": 2410.25 } ] } ], "officialId": "1234567-8", "summary": { "holidayCalc": { "totalAccruedHolidayPay": 4820.50, "totalAccruedHolidayBonus": 2410.25 } } } ``` - **Entries have no code.** Holiday pay and holiday bonus post to the same account pair under the default chart, so only the Finnish `description` tells them apart. - **The entries are an accrual pair**, not a payable: debit to an accrual account (*jaksotus*), credit to a transfer debt account (*siirtovelat*). The contributions post the same way to a second account pair. - **`summary.holidayCalc` always has all seven figures**, even when the posted rows do not. Compare the two before you import. ### Check what the target posts Which rows appear depends on the ruleset of the accounting target, and a row the target does not post comes back with no account and no amount, not as an error. - **Several standard targets ship with holiday accruals switched off.** Under them the ledger shape returns no accrual rows. Accruals can be switched on in a copy of the target. - **Accident insurance and group life never post under any standard target.** The ledger shape therefore totals less than the report shape. Treat the report shape as the authority for the total. Prefer it if you post to your own chart of accounts. To check a target, fetch it by id (`GET /v03/api/accounting-target/{id}`; the list endpoint has no ruleset). In `ruleSet.rows`, filter `entryCodeGroup` to `totalType` and read `isIncluded` on these five codes: `totalAccruedHolidayPay`, `totalAccruedHolidayBonus`, `totalAccruedHolidaySocialSecurity`, `totalAccruedHolidayPension`, `totalAccruedHolidayUnemployment`. A missing row behaves like `isIncluded: false`. Do not look for the other two by name: their codes are spelled without `Holiday` (`totalAccruedAccidentInsurance`, `totalAccruedGroupLifeInsurance`) and do not post under any standard target whatever `isIncluded` says. Get those two figures from the report shape. ## Posting the debt each period **Every call returns a balance, not a movement.** The figure is the whole liability as at `refDate`. Salaxy keeps no record of what you posted before, has no "changes since" parameter and never returns reversals. Importing month after month as is accumulates: 10 000 EUR in May and 10 500 EUR in June leave 20 500 EUR credited against a true liability of 10 500 EUR. Pick one pattern. | Pattern | How | Notes | |---|---|---| | **Reversing entry** (*jaksotuksen purku*) | Post the full accrual at period end. Reverse the identical entry on the first day of the next period, then post the new full accrual. | The usual Finnish practice for accrual accounts. Each import is independent, so a re-run is harmless. **Recommended.** | | **Delta posting** | Leave the accrual standing and post only the difference from the last posted figure. | Fewer entries, but you must store the last posted amount per company. A missed or duplicated run corrupts the balance silently. | ## Reference date and rounding - **`refDate` is the last month included.** The period runs to the end of that month whatever day you pass: `2026-05-01`, `2026-05-15` and `2026-05-31` all return the debt at 31 May 2026. - **Remaining holiday is rounded up to whole days**, so the debt is slightly conservative. - **An over-drawn holiday year counts as zero**, never negative. ## Where the numbers come from The debt is derived from **holiday years**, stored objects you can read and write. | Method | Path | Purpose | |---|---|---| | GET, POST | `/v03/api/holidays` | Read or save holiday years | | POST | `/v03/api/holidays/employment/{employmentId}` | Create holiday years for an employment from a specification | | GET | `/v03/api/holidays/employment/{employmentId}/available-holiday-accruals` | Remaining holiday days | | POST | `/v03/api/holidays/year/{year}/{employmentId}/holiday-pay/recalculate` | Recalculate after changing salary data | - A holiday year (*lomanmääräytymisvuosi*) runs from 1 April to 31 March. The matching leave period is 2 May to 30 April of the next year. - Accrual is kept in **days**: an opening balance plus days accrued per month. Euro amounts come from separately calculated daily rates. - The daily rate depends on the holiday pay method of the year: normal monthly pay, average daily pay, average hourly pay, percentage or holiday compensation. - **Missing or stale holiday years give a low figure, not an error.** When you onboard a company, check that holiday years exist for the current and the previous holiday year before you trust the first report. - **Migrating balances from another system:** new holiday years arrive with estimated days in every past month. Overwrite each month's `daysAccrued` with the real figure and `source: manual`, and put only days carried over from earlier years in `startSaldo`, or the days count twice. For the monthly pay method the employment also needs a monthly salary default row, or the daily rate and the debt are zero. ## When a figure looks wrong The endpoints are read only. Most inputs are company settings that the customer or its accounting firm keeps in the Salaxy UI. The screens are in Finnish. | Field | Driven by | Customer checks | |---|---|---| | `totalAccruedHolidayPay` | daily rate times remaining days | holiday year of the employment | | `totalAccruedHolidayBonus` | the *lomaraha* multiplier of the holiday year | holiday year of the employment | | `totalAccruedHolidaySocialSecurity` | statutory rate | nothing, not configurable | | `totalAccruedHolidayPension` | the company's pension (TyEL) contract | Asetukset, **Vakuutukset** | | `totalAccruedHolidayUnemployment` | statutory rate and payroll size band | nothing in normal use | | `totalAccruedHolidayAccidentInsurance` | the company's accident insurance percentage | Asetukset, **Vakuutukset** | | `totalAccruedHolidayGroupLifeInsurance` | the company's group life percentage | Asetukset, **Vakuutukset** | Holiday pay calculation rules sit under Asetukset, **Kirjanpitokohteet**, in the *Loma-asetukset* card. **Accident insurance and group life are often zero.** The other contributions fall back on statutory rates. These two are per-policy percentages that exist only on the company's own insurance contract. With no contract on file both are zero, with no error or warning. The percentage fields are hidden until an insurance company is selected on the *Tapaturmavakuutus* card. Correcting a percentage fixes past holiday years, because the debt is recomputed on every call. It does not change payroll already run: those calculations keep their old rates, so the debt report and old payslips then differ. ## Test it 1. Create a test employee and employment ([Employees and employments](https://code.salaxy.com/integration/employments.md)) and check that holiday years exist: `GET /v03/api/holidays`. 2. Call the report shape with a date in the current month. Expect `200` and the seven fields. 3. Call the ledger shape with `target=default`. Compare the sum of the rows with `summary.holidayCalc`. A gap of the accident and group life figures is expected. 4. For more on test data, see [Test endpoints and test data](https://code.salaxy.com/reference/test-endpoints.md). ## Checklist - Call a debt endpoint once per period. Never read the debt from other accounting responses. - Choose reversing entries or delta posting and apply it to every company. - Reconcile the ledger shape with the report shape against the target you will really use. - Verify that holiday years exist for new companies before you trust the first figure. - Treat zero accident and group life figures as a missing insurance contract before you suspect an error. **Next:** [Monthly cycle](https://code.salaxy.com/integration/monthly-cycle.md) --- Source: https://code.salaxy.com/integration/monthly-cycle.md # Monthly cycle Every month, Salaxy runs a scheduled batch for every employer. It closes the **previous month**: accounting reports, the monthly summary to the Incomes Register and the tax invoices. You do not call it. You fetch its outputs through the normal API, so the day of the month is your contract. Salary slips are not part of it: each paid calculation has its own slip, see [Salary slips and e-payslips](https://code.salaxy.com/integration/salary-slips.md). Examples use the **test** environment; see [Environments](https://code.salaxy.com/get-started/environments.md) for demo and production. *Diagram: A timeline with four steps, all in Helsinki time and all for the previous month. On the 4th business day Salaxy creates the accounting reports and sends the monthly report emails. On day 5 it files the monthly summary to the Incomes Register. On day 6 it releases the tax invoice and the union invoice to the payment channel. On day 10 it creates the tax payments made from a customer funds account. (Helsinki time, previous month's salaries. The 4th business day skips weekends and Finnish public holidays.)* ## The outputs | # | When | Output | Where you see it | |---|---|---|---| | 1 | 4th business day | **Accounting reports**: accounting data of the previous month per employer, mapped to the employer's accounting target. A PDF summary and a spreadsheet are archived too. | The accounting endpoints: see [Accounting data](https://code.salaxy.com/integration/accounting-data.md) | | 2 | 4th business day | **Monthly report emails**: the reports of output 1, emailed to the employers and accounting firms on file. | Email only, not the API | | 3 | Day 5 | **PSR, the Payer Summary Report**: the monthly summary (*työnantajan erillisilmoitus*) to the Incomes Register. | Filed for you: see [Incomes Register filing](https://code.salaxy.com/integration/incomes-register.md) | | 4 | Day 6 | **TAS invoice**: tax and social security invoice (*vero- ja sotumaksulasku*), the monthly total of withheld tax and employer social security charges. | The normal invoice flow: see [Invoices and payments](https://code.salaxy.com/integration/invoices-and-payments.md) | | 5 | Day 6 | **Union invoice**: trade union membership fees withheld from workers, one per union. Only for employers who have a union deduction in the period. | Same as the TAS invoice | | 6 | Day 10, or the previous workday | **Tax payments** that Salaxy makes from a customer funds account. Only on customer funds account channels. | Nothing to fetch on other channels: their tax is paid through the TAS invoice (output 4) | - **Calendar day or business day.** Outputs 1 and 2 run on the 4th business day. Outputs 3 to 5 run on the calendar day shown. Output 6 falls back to the previous workday when day 10 is not a workday. - **Previous month.** Day 4 of March produces the February reports. ## What the invoices do This section describes most payment channels. Customer funds account channels work differently (see below), and a few channels release the invoice as soon as all its salaries are paid. The tax and union invoices are created as **preview** when a payment is committed. The day-6 run finalises them and releases them to the payment channel as `unread`. The TAS invoice is due on the next workday on or after the 12th. The union invoice is due on the next workday on or after the 15th. **On these channels, a salary that is not paid before the day-6 run is missing from that month's tax invoice.** The run takes the calculations that have reached `paymentSucceeded` by then, and it does not return to a past month. If a salary can be paid late, for example because of a bank approval, plan for it with your customer. ## Rules to build on - **Once a month, no automatic retry.** An output that misses its slot is not repeated. Ask Salaxy support to re-run it for the employer. - **Incomes Register: two flows.** The PSR is monthly, on day 5. The per-salary report (EPR) is a separate flow: it is created when a salary is paid and sent 4 days after its salary date, or at once if that day has passed. See [Incomes Register filing](https://code.salaxy.com/integration/incomes-register.md). - **Customer funds account channels differ.** Tax remittance follows another path, and some channels add a monthly pension payment record on day 25. If a customer is on such a channel, ask Salaxy for the addendum. ## Test and demo The monthly cycle **does not run end to end** in test or demo. Only a subset runs, on the same days as in production: | Output | In test and demo | |---|---| | Accounting data | Generated as data on the 4th business day. No PDF, spreadsheet or report email. | | TAS and union invoices | Generated by the same code as in production, on day 6. | | PSR | Generated on day 5, **not** sent to the Incomes Register. | | Report emails, tax payments | Skipped. | For a full rehearsal that shows where each output lands, ask Salaxy support to schedule a manual run. In your own tests you need not wait for the 4th business day: call the period report for a past month, or use `POST /v03/api/reports/accounting/{refDate}/close` to write the saved report on demand. See [Accounting data](https://code.salaxy.com/integration/accounting-data.md). ## Checklist - Pull the period report on or after the 5th of the next month. Read a saved report only after the 4th business day, which can fall after the 5th. - In test, pull the period report or call `close` instead of waiting for output 1. - Make sure salaries are paid before the day-6 run, so they are in the month's tax invoice. - Do not file anything to the Incomes Register yourself. - If an output is missing in production, ask Salaxy support to re-run it. It will not retry by itself. **Next:** [Incomes Register filing](https://code.salaxy.com/integration/incomes-register.md) --- Source: https://code.salaxy.com/integration/incomes-register.md # Incomes Register filing The Finnish Incomes Register (*Tulorekisteri*) is the national earnings database. Employers must report each salary payment to it. **Salaxy does this for every customer company, automatically. You build and call nothing.** Examples use the **test** environment; see [Environments](https://code.salaxy.com/get-started/environments.md) for demo and production. *Diagram: Two filing flows, both done by Salaxy. Top flow: a paid salary leads to an Earnings Payment Report, EPR, filed per salary. Bottom flow: the end of the month leads to a Payer Summary Report, PSR, filed once a month on day 5. Both reach the Incomes Register. A green box at the bottom says your integration has nothing to build or call. (Purple: filed by Salaxy. The two flows are independent of each other.)* ## What Salaxy files, and what you do not need to do | | EPR, Earnings Payment Report (*palkkatietoilmoitus*) | PSR, Payer Summary Report (*työnantajan erillisilmoitus*) | |---|---|---| | **Granularity** | One per paid salary calculation | One per employer per month | | **Content** | The earnings data of the salary | The employer's monthly health insurance contribution total. It is not a list of wages: the wages go in the EPR. | | **Trigger** | The calculation reaches `paymentSucceeded` | The [monthly cycle](https://code.salaxy.com/integration/monthly-cycle.md), day 5 | | **Changes** | One per calculation. A correction is a cancellation and a new report. | Replaceable. A changed month is re-filed as a replacement. | You **do not** call, trigger, schedule or poll anything. As a partner you do not need an Incomes Register certificate (an accounting firm may: see [below](#who-is-named-as-the-filer)), and you must not file the same data yourself. There is **no endpoint** to start a filing. ## When a report goes out - **EPR.** It is created when the salary calculation reaches `paymentSucceeded`. It is reported against the **salary date**, not the date the salary was approved or paid. Salaxy sends it 4 days after the salary date, one day before the deadline, or at once if that day has already passed. Salaxy then checks the Incomes Register until it has a final answer. - **PSR.** The day-5 run files the previous month. A salary belongs to a month by its salary date. A month with paid salaries gets a report even for one small salary. A company that paid a salary in the last 12 months and none in the month gets a zero report. A company that has never paid through Salaxy gets nothing filed until its first salary. ## Late filing: the customer carries the penalty The deadline is **5 calendar days after the payment date**. A report that is more than 8 days late is charged a daily fee, up to an annual cap. The fee falls on the **payer, the customer company**, not on Salaxy as the filer. Households that employ as private persons are exempt. Because the EPR uses the salary date, a salary approved or paid long after its salary date is filed at once but with an old date, and is late. If your flow can hold a salary past its salary date (a bank approval, an approval queue, a weekly batch), the customer pays the penalty. Plan for it: show the salary date clearly, and keep the gap between approval and payment short. ## Who is named as the filer | Role | Who | |---|---| | **Sender** | Salaxy by default. It is the filing identity and decides the certificate used to authenticate. | | **Payer** | The customer company. It carries the late-filing penalty. | An account can file under another sender, for example an accounting firm under its own business ID. The firm then needs its own Incomes Register certificate in place before any filing works. Its customer companies cannot accept the [click option](https://code.salaxy.com/integration/contract-options.md#the-company-accepts-the-terms-with-a-click) or commit a payment while that certificate is missing or expired. A setting that is not a valid Finnish company ID is ignored without an error, and Salaxy stays the filer. This is arranged with Salaxy, not through your integration. The sender is read when the day-5 run executes, so a customer that moves to another accounting firm before day 5 changes who files the **previous** month. Settle this before the move. ## Switching payroll systems in the middle of a month The Incomes Register accepts **one** monthly summary per employer and month. Two filings for the same month are not additive. For a customer that moves to or from Salaxy during a month, agree who files that month. Usually the previous provider files the whole month and Salaxy switches off its own monthly report for that month: ask Salaxy support to do it before day 5. EPRs are not affected, so salaries paid through Salaxy are still reported. ## Test it - In test and demo, EPR filing for a normal business ID returns **mocked** answers. The filing looks successful as in production, but nothing reaches the Incomes Register. A PSR is generated but not sent. - A successful EPR in test therefore proves your workflow, not a real filing. - To test against the Incomes Register's own test environment, ask Salaxy support to arrange a rehearsal under one of the reserved test business IDs. ## Checklist - Do not file to the Incomes Register yourself, and do not ask your customers to. - Make the salary date the real pay date, and avoid holding an approved salary past it. - Tell customers that the late-filing fee falls on them, not on you or Salaxy. - When a customer changes accounting firm or payroll system, plan who files the month before day 5. - Do not treat a mocked success in test as proof of a real filing. **Next:** [Salary slips and e-payslips](https://code.salaxy.com/integration/salary-slips.md) --- Source: https://code.salaxy.com/integration/salary-slips.md # Salary slips and e-payslips There are two ways a worker gets a salary slip. You can **fetch the PDF** of a paid calculation and show or send it yourself. Or Salaxy can **deliver an electronic payslip** to the worker's online bank, with no code from you. Examples use the **test** environment; see [Environments](https://code.salaxy.com/get-started/environments.md) for demo and production. *Diagram: A salary calculation is paid and reaches the status paymentSucceeded. From there, Salaxy delivers an electronic payslip to the worker's online bank automatically, if the delivery setting is on. Separately, your system can ask the Salaxy REST API for the salary slip PDF of the paid calculation. (Both start from a paid calculation. The e-payslip is automatic; the PDF is a call you make.)* ## Which fits you? ### Fetch the PDF Fits when you show the salary slip in your own UI, store it, or send it to the worker yourself. **Fetch the PDF: how it works:** Salaxy generates and saves a salary slip PDF for each paid calculation: one slip per worker and payment, available as soon as the calculation is paid. There is no monthly slip run to wait for; the [monthly cycle](https://code.salaxy.com/integration/monthly-cycle.md) produces reports and invoices, not slips. The printout can be adjusted to the visual style of the company; contact Salaxy for that. | Method | Path | Purpose | |---|---|---| | `GET` | `/v03/api/reports/assure-pdf/salarySlip?ids={calculationId}` | Make sure the salary slip PDF exists and return it | | `GET` | `/v03/api/calculations` | Find calculation ids ([queries](https://code.salaxy.com/reference/queries.md)) | Add `disposition` to choose how the PDF is returned: | `disposition` | Response | |---|---| | not given | The PDF as a Base64 string in a JSON response (`application/json`) | | `attachment` | A PDF file response with `Content-Disposition: attachment` | | `inline` | A PDF file response with `Content-Disposition: inline` | The `language` query parameter sets the language of the report. Other slip types exist in the same report type list: `salarySlipPaid`, `salarySlipCopy` and `eSalarySpecification`. ``` GET https://test-secure.salaxy.com/v03/api/reports/assure-pdf/salarySlip?ids=&disposition=attachment Authorization: Bearer ``` You need a token for the company that owns the calculation: see [REST authentication](https://code.salaxy.com/security/rest-authentication.md) and [impersonation](https://code.salaxy.com/security/impersonation.md). Find the calculation id with the calculations query, or from data you already read: an invoice header lists the calculations it covers ([invoices and payments](https://code.salaxy.com/integration/invoices-and-payments.md)), and [accounting data](https://code.salaxy.com/integration/accounting-data.md) entries carry the originating calculation id in their dimensions. ### Electronic payslip Fits when you want the worker to get the slip in their online bank without building anything. **Electronic payslip: how it works:** The electronic payslip is known as *verkkopalkka* in Finnish and shown as "Online salary" in the UI. Salaxy delivers it through an e-payslip operator. **There is no endpoint to call.** Delivery is automatic and driven by the calculation status: 1. A salary calculation reaches `paymentSucceeded`. 2. Salaxy checks that the salary slip delivery methods of the calculation include the electronic payslip. 3. If so, the payslip is posted to the operator in the background, within moments. On a customer funds account channel, `paymentSucceeded` means Salaxy has received the employer's funds, so the payslip is sent later, when Salaxy has paid the worker. See [Payroll lifecycle](https://code.salaxy.com/integration/payroll-lifecycle.md#customer-funds-account-channels). The delivery methods are listed in the `responsibilities.salarySlipDeliveryMethods` array of the calculation result. It is read-only, and its values are `default`, `payslip` and `omapalkka`; `payslip` is the electronic payslip. The value comes from the Salaxy settings, not from your code. If you use a [payment channel](https://code.salaxy.com/integration/payment-channels.md), the calculation reaches `paymentSucceeded` because you report the invoice `paid`. Delivery is a consequence of that, and it is not reported back through the payment channel API. See [Payroll lifecycle](https://code.salaxy.com/integration/payroll-lifecycle.md) for the statuses. ## Rules to know - **Reporting `paid` sends the payslip.** In a payment channel integration, reporting `paid` is what puts a document in the worker's bank. Keep that in mind when you choose which event stands for `paid` ([Invoices and payments](https://code.salaxy.com/integration/invoices-and-payments.md#rules-that-save-you-a-day)). - **There is no duplicate protection.** If a calculation leaves `paymentSucceeded` and enters it again, the worker gets a second payslip. Do not undo a `paid` report yourself; after payment, a correction is a Salaxy support action. - **Cancelling a payment removes the payslip.** Salaxy's cancel and refund flow asks the operator to delete it. - **A repaired calculation does not send a second payslip.** The original payslip stays as the record of the corrected payment. ## Test it - **PDF:** pay a test calculation (see [Create a payroll](https://code.salaxy.com/get-started/rest/create-payroll.md) and [Set for payment](https://code.salaxy.com/get-started/rest/set-for-payment.md)), then call `assure-pdf/salarySlip` as above and check the response for each `disposition` you use. - **E-payslip:** there is no test gate on this delivery: driving a calculation to `paymentSucceeded` in the test environment runs it. It goes to the operator's test service, so no real online bank receives it. Use fake data only. ## Checklist - You know how each customer gets the slip: PDF through your system, e-payslip from Salaxy, or both. - PDF fetch uses a token for the company that owns the calculation. - Your code handles each `disposition` response it uses. - You chose the event that stands for `paid` knowing that it also sends the e-payslip. - You never undo a `paid` report yourself, so a calculation never passes through `paymentSucceeded` twice. **Next:** [Messages and notifications](https://code.salaxy.com/integration/messages-and-notifications.md) --- Source: https://code.salaxy.com/integration/messages-and-notifications.md # Messages and notifications Salaxy keeps conversations as **message threads**: a title, a list of messages and attachments, and read marks for each side. The embedded white label UI has a Messages view, and you can read and write the same threads through the REST API. After a salary is paid, Salaxy can also notify the worker. Examples use the **test** environment; see [Environments](https://code.salaxy.com/get-started/environments.md) for demo and production. *Diagram: Top row: a company user and the other party, for example you as the partner or Salaxy, exchange messages in a message thread stored in Salaxy. The thread shows in the embedded UI or in your own UI through the REST API. Bottom row: when a salary is paid, Salaxy notifies the worker by email or with an electronic payslip. (Purple: Salaxy. Grey: people and your side. Green: a paid salary.)* ## Which fits you? ### Messaging in the embedded UI Fits when your customers use the embedded Salaxy UI, Salaxy Business or Salaxy Pro (build path 1): there is nothing to build. **Messaging in the embedded UI: how it works:** The embedded payroll UI has a Messages view at the route `#/messages` (see [Navigation](https://code.salaxy.com/white-label/navigation.md)). Users read and write threads there. If you use your own menu, link it to that route. ### Your own UI on the message-thread API Fits when you build your own UI (build path 2), or want to show or start threads from your product. **Your own UI: how it works:** Use the endpoints below. A thread belongs to an **owner** (typically the company or household, the party that can delete the thread) and has an **other party** (typically the partner or Salaxy). Each side has its own workflow block (`ownerWorkflow`, `otherPartyWorkflow`) with the last message text, a salary date and an unread count: the number of messages that side has posted and the other side has not read yet. The generated reference for the tag is [MessageThread](https://code.salaxy.com/reference/rest/messagethread.md). ### Worker notifications after payment Fits when you want to decide how the worker hears about a paid salary. See [Worker notifications](#worker-notifications). For the salary slip itself, see [Salary slips and e-payslips](https://code.salaxy.com/integration/salary-slips.md). ## Message-thread API All paths are in v03. | Method | Path | Purpose | |---|---|---| | `GET` | `/v03/api/messages` | List threads with an OData query ([queries](https://code.salaxy.com/reference/queries.md)) | | `GET` | `/v03/api/messages/new` | Get a new empty thread to fill in | | `POST` | `/v03/api/messages` | Create or update a thread | | `GET` | `/v03/api/messages/{id}` | Get one thread with its messages | | `DELETE` | `/v03/api/messages/{id}` | Delete the thread and its attachment files | | `POST` | `/v03/api/messages/{id}/messages` | Add or edit one message in the thread | | `POST` | `/v03/api/messages/{id}/files` | Add an attachment file as a message | | `POST` | `/v03/api/messages/{id}/messages/blobFileMessage` | The same action as `/files`, at a second address | | `POST` | `/v03/api/messages/{id}/read-by/{readBy}` | Mark all messages as read by `owner` or `otherParty` | | `POST` | `/v03/api/messages/{id}/notifications?subject=...` | Send an email notification to the owner of the thread | ### Rules - **Create.** `POST /v03/api/messages` creates a thread when `id` is empty. You may also set your own `id` for a new thread; it must not be in use already. - **Owner and other party.** The owner is the account that saves the thread; you cannot set it. Set `otherParty` (the account id of the other party) when you create the thread. Once the thread has another party, a later save does not change it. - **Attachments.** `POST /v03/api/messages/{id}/files` takes a multipart form upload. Each file becomes a message of type `blobFile`. An optional form field `from` sets `fromParty`; the default is `owner`. A file that cannot be saved becomes a message with an error in `validation`. - **Add a message.** `POST /v03/api/messages/{id}/messages` with a message that has no `id` appends it. With an `id` it replaces that message; an unknown `id` is an error. If `time` is before the thread was created or in the future, it is set to now. - **Message types.** `type` is one of `text`, `blobFile`, `calculation`, `payroll`, `workerAccount`, `email`, `salaxyEmail`, `sms`, `salaxySms`, `timer`, `timerEdited`, `hourlyReport`, `timeReport`, `absence`, `annualLeave`, `calcRow`, `travel`, `expense`. For `calculation` and `payroll`, put the id in `contentId`. On save, Salaxy fills the gross salary, payment, salary date and period into `contentData` and links the calculation or payroll to the thread. - **Sender.** `fromParty` is `owner`, `otherParty` or `system`. - **Thread status.** `status` is `draft`, `active`, `approved`, `rejected`, `archived` or `template`. - **Read marks.** `read-by` accepts only `owner` or `otherParty`; any other value is an error. Each message has `readByOwner` and `readByOtherParty` times. - **Email notification.** The request body is the plain-text message and `subject` is a query parameter. Salaxy emails the address of the thread owner's account and adds the email to the thread as a message of type `email` from `otherParty`. If sending fails, the call still returns the thread: check `validation` on the new message. - **Lists.** The thread list leaves out the threads that record emails Salaxy itself has sent. ### Sample Create a thread, then add a message. Replace `{id}` with the id in the first response. ```http POST https://test-secure.salaxy.com/v03/api/messages Authorization: Bearer Content-Type: application/json { "title": "Question about the March payroll", "status": "active", "messages": [ { "type": "text", "content": "Can the salary date move to the 28th?", "fromParty": "owner" } ] } ``` ```http POST https://test-secure.salaxy.com/v03/api/messages/{id}/messages Authorization: Bearer Content-Type: application/json { "type": "text", "content": "Yes, we updated the payroll.", "fromParty": "otherParty" } ``` ## Worker notifications The `messaging` part of the company settings controls what the worker gets after a salary payment. A service model can set the defaults; see [Company settings](https://code.salaxy.com/integration/company-settings.md) and [Service models](https://code.salaxy.com/integration/service-models.md). | Setting | Values | Meaning | |---|---|---| | `workerSalaryNotifications` | array of `always`, `silent` | Whether the worker gets an email after the salary payment | | `workerSalarySlipDeliveryMethods` | array of `default`, `payslip`, `omapalkka` | How the salary slip is delivered to the worker; `payslip` is the electronic payslip | | `partnerMessages` | `true`, `false` | Partner messages enabled | After the salary payment, Salaxy can email the worker that the salary slip is ready. For most payment channels this happens when the calculation reaches `paymentSucceeded`. Whether the email is sent follows `workerSalaryNotifications`: - **`silent`** in the list: no email. It wins over `always`. - **`always`** in the list: the email is sent. - **Empty list:** the default of the payment channel applies. The email is the same for every worker: it links to the worker site, where the worker signs in with strong authentication to see the slip. It is separate from the electronic payslip in the worker's online bank, which is sent only when `workerSalarySlipDeliveryMethods` includes `payslip`; see [Salary slips and e-payslips](https://code.salaxy.com/integration/salary-slips.md). ## Test it 1. Get a test token ([Get a test account](https://code.salaxy.com/get-started/test-account.md), [REST authentication](https://code.salaxy.com/security/rest-authentication.md)). 2. Call `GET /v03/api/messages/new`, fill in `title`, and `POST` it to `/v03/api/messages`. 3. Add a message, then call `POST /v03/api/messages/{id}/read-by/owner`. Each message now has a `readByOwner` time. 4. In the embedded UI, open `#/messages` and check that the thread is listed. The test and demo environments do not send real email. The email message is still saved and looks sent, so check the thread, not an inbox. See [Test endpoints and test data](https://code.salaxy.com/reference/test-endpoints.md). ## Checklist - You create threads as the company, so the company is the owner, and you use `owner` and `otherParty` consistently. - You do not rely on an email being delivered: a sent notification records only that Salaxy handed it on. - You mark messages as read only for the party that actually read them. - You choose the worker notification and salary slip delivery settings deliberately, per company. - You filter and page thread lists with [OData queries](https://code.salaxy.com/reference/queries.md). **Next:** [Go-live checklist](https://code.salaxy.com/integration/go-live.md) --- Source: https://code.salaxy.com/integration/go-live.md # Go-live checklist Production is a separate environment with live data. Most of what it needs is set up by Salaxy, and your code mainly switches hosts and uses a production certificate. Work through this list in order; each item links to the topic that explains it. Examples use the **test** environment; see [Environments](https://code.salaxy.com/get-started/environments.md) for demo and production. *Diagram: Five steps from left to right. Build and test your integration in test or demo. Salaxy provisions the production accounts, channel and models. You switch the hosts and the certificate to production. You run a smoke test. Then you are live, with a customer care and escalation path in place. (Production setup is mostly Salaxy's work; your part is the certificate, the host switch and the first run.)* ## Before production Tick each item. Items 1 to 5 are one-time setup; ask Salaxy for the production side early, because Salaxy does the provisioning. | # | What must be true | Who | Topic | |---|---|---|---| | 1 | **Production partner account and technical account** exist. They are separate from the test ones, with their own account ids | Salaxy, with you | [Partner and technical accounts](https://code.salaxy.com/integration/partner-account.md) | | 2 | **Production certificate** is created and its private key is in your backend secret store. A test certificate fails in production | You | [Partner and technical accounts](https://code.salaxy.com/integration/partner-account.md) | | 3 | **Payment channel** is provisioned in production and you have verified it | Salaxy, with you | [Payment channels](https://code.salaxy.com/integration/payment-channels.md) | | 4 | **Service models** are provisioned in production, and you have agreed which customers get which model | Salaxy, with you | [Service models](https://code.salaxy.com/integration/service-models.md) | | 5 | **Accounting models** are provisioned in production and linked from the service models | Salaxy | [Accounting models](https://code.salaxy.com/integration/accounting-models.md) | | 6 | **Hosts are switched** from test to production, see below | You | [Environments](https://code.salaxy.com/get-started/environments.md) | | 7 | **Customer and accounting firm account creation** works in production | You | [Customer accounts](https://code.salaxy.com/integration/customer-accounts.md), [Accounting firm accounts](https://code.salaxy.com/integration/accounting-firm-accounts.md) | | 8 | **Smoke test** passed, see below | You, with Salaxy | the topic pages you use | | 9 | **Customer care and escalation path** is named, see below | You, with Salaxy | [Developer FAQ](https://code.salaxy.com/get-started/faq.md) | The order of the topics you build is in [Integration overview](https://code.salaxy.com/integration/index.md) and [Integration in a day with a coding agent](https://code.salaxy.com/integration/with-a-coding-agent.md). Items 1 to 5 are the same topics, with the production values: the test values are not reused. ## Switch from test to production Production is its own environment with its own data. Change these together, and keep the host settings in configuration, not in code. | What | Test | Production | |---|---|---| | REST API base | `https://test-secure.salaxy.com` | `https://secure.salaxy.com` | | Token endpoint | `https://test-secure.salaxy.com/oauth2/token` | `https://secure.salaxy.com/oauth2/token` | | Embed host | `https://test-embed.palkkaus.fi/` | `https://embed.palkkaus.fi/` | | Certificate | Test certificate | Production certificate, signed by the production root | | Account ids (including the channel's owner account), service and accounting model ids | Test values | Production values from Salaxy | - **Do not reuse a test certificate or a test id** in production. Production certificates are verified against a different root, and ids are different. - **The payment channel key does not change.** It is fixed in code and is the same in test and production; only its owner account differs. See [Payment channels](https://code.salaxy.com/integration/payment-channels.md#what-a-channel-is). - **Demo does not exercise the production certificate path.** Demo shares test data and uses the test root; only production proves the production certificate. - **Switch API and embed hosts together** if you use the [embedded white label](https://code.salaxy.com/white-label/how-it-works.md). - **Authentication is unchanged**: the same signed JWT flow, only the host, the certificate and the account ids differ. See [REST authentication](https://code.salaxy.com/security/rest-authentication.md). ## Smoke test A suggested checklist, not a fixed Salaxy procedure. Run one complete case in production before real customers use it. Production sends real payments and real payslips, so use a case that is meant to be paid. - Sign in with the production certificate and read something small. - Create a customer account and an employee ([Customer accounts](https://code.salaxy.com/integration/customer-accounts.md), [Employees and employments](https://code.salaxy.com/integration/employments.md)). - Run the loop your integration uses: a payroll ([Salary calculations](https://code.salaxy.com/integration/calculations.md)), or the invoice and payment loop ([Invoices and payments](https://code.salaxy.com/integration/invoices-and-payments.md)), through to the paid status ([Payroll lifecycle](https://code.salaxy.com/integration/payroll-lifecycle.md)). - Read the result your system needs, for example [accounting data](https://code.salaxy.com/integration/accounting-data.md) or the [salary slip](https://code.salaxy.com/integration/salary-slips.md). - If you use the embedded white label, open it with the production embed host and check that sign-in works ([URL parameters](https://code.salaxy.com/white-label/url-parameters.md)). - Check that you log request ids and can quote them to Salaxy ([Limits, logging and correlation](https://code.salaxy.com/reference/limits.md)). ## Customer care and escalation Two flows are easy to confuse. Name a person for each before go-live. | Flow | Who asks | Who answers | |---|---|---| | **End-customer care** — a payroll question from a customer company or an accounting firm | The end customer | Usually you first, and you escalate to Salaxy what you cannot resolve. **Your partner contract sets the actual split**, and Salaxy publishes no standard response-time commitment | | **Escalation to Salaxy** — a developer or operator needs something from Salaxy | You | Salaxy support | Reasons to escalate to Salaxy, during development and after go-live: - Missing test data or test accounts ([Test endpoints and test data](https://code.salaxy.com/reference/test-endpoints.md)). - Provisioning: technical account, payment channel, service and accounting models. - Whether your payment channel has an outbound status trigger. - A manual monthly-cycle run in test, where the cycle does not run end to end ([Monthly cycle](https://code.salaxy.com/integration/monthly-cycle.md)). - A server-side log lookup: send the request id and an approximate time ([Limits, logging and correlation](https://code.salaxy.com/reference/limits.md)). Decide early whether Salaxy may be named to your end customers. In an embedded white label integration the customer sees your brand, so first-line staff need to know what they can say. Help channels are on [Support](https://code.salaxy.com/get-started/support.md). ## Checklist - Items 1 to 9 above are ticked, with production values and no test certificate or test id left. - Hosts, certificate and ids come from configuration, one set per environment. - A smoke test, for example the one suggested above, has run through the whole loop your integration uses, in production. - You have a named person for end-customer care and a named Salaxy contact for escalation. - You log request ids and know how to quote them to Salaxy. --- Source: https://code.salaxy.com/reference/errors.md # Errors The contract is the same on every `/v03` endpoint, and on most of `/v04`: **one JSON error shape, a few HTTP statuses, and no stable machine-readable error codes.** Handle a failure by its HTTP status — never by parsing the message text. Examples use the **test** environment; see [Environments](https://code.salaxy.com/get-started/environments.md) for demo and production. ## The error body A business or validation failure returns **HTTP 400** with two fields: ```json { "error": "Y-tunnus on virheellinen", "messageHtml": "Y-tunnus 1234567-9 on virheellinen." } ``` - `error` — a short title. Currently in Finnish and **not a stable identifier**: do not branch your code on its text. - `messageHtml` — a longer message you can show to a back-office user (also currently in Finnish). Not for parsing. - **Validation failures** prefix `error` with `VALIDATION` and add a `validation` object with field-level details. Its presence is the signal that the request failed validation. ## Statuses you will hit | Status | When | What to do | |---|---|---| | `400` | Any business or validation failure | Read `error` / `validation`, fix the request. Retrying the same request does not change the result | | `401` | Missing, invalid or expired token. The body is empty: the reason is in the `WWW-Authenticate` header, for example `Bearer error="invalid_token"` | Get a new token and retry **once** — see [Tokens](https://code.salaxy.com/security/rest-authentication.md#tokens) | | `404` | The resource does not exist. Used sparingly: most "not allowed" or "not valid" cases are `400` | Check the id and the account you act as | | `5xx` | An unexpected server error, or a failure caught before the normal handling — **without** a JSON body | Retry transient errors with exponential backoff. Do not assume a body is present | **A missing role fails as a bare `5xx`.** In production, calling an endpoint your account lacks the role for — for example [partner-initiated account creation](https://code.salaxy.com/security/account-creation.md) without the trusted partner role — fails as a server error, not a structured 400. ## Problem details on new v04 endpoints [v04 beta] New endpoints in [API v04](https://code.salaxy.com/reference/rest-api-v04.md) return errors as **problem details** ([RFC 9457](https://www.rfc-editor.org/rfc/rfc9457), content type `application/problem+json`). The first are the payment channel configuration endpoints (`/v04/api/settings/payment-channels/…/config`, one path per channel). ```json { "type": "https://code.salaxy.com/problems/validation-failed", "status": 422, "title": "The payment channel config is not valid.", "errors": { "debitAccount.iban": ["…"] } } ``` - `type` — a stable URI. **Branch your code on `type`**, not on the text. The URI opens the page that explains the type: see [Problem types](https://code.salaxy.com/problems/index.md). - `title` and `detail` — in the language of `Accept-Language` (`fi` or `en`, Finnish by default). - `errors` — only for `validation-failed`: the messages per field, keyed by the field's path in the JSON. | `type` (after `https://code.salaxy.com/problems/`) | Status | |---|---| | [`not-found`](https://code.salaxy.com/problems/not-found.md) | 404 | | [`channel-not-available`](https://code.salaxy.com/problems/channel-not-available.md) | 409 | | [`concurrent-change`](https://code.salaxy.com/problems/concurrent-change.md) | 409 | | [`precondition-failed`](https://code.salaxy.com/problems/precondition-failed.md) | 412 | | [`unsupported-media-type`](https://code.salaxy.com/problems/unsupported-media-type.md) | 415 | | [`validation-failed`](https://code.salaxy.com/problems/validation-failed.md) | 422 | | [`internal-error`](https://code.salaxy.com/problems/internal-error.md) | 500 | These endpoints document their error responses in the OpenAPI document. ## What generated clients see For `/v03`, the [OpenAPI document](https://code.salaxy.com/reference/rest-api.md) describes only the **success** response of each endpoint. Error responses are not in it, so a generated client has no typed error model: read the status and the JSON body directly. ## Retries - `5xx` — safe to retry with backoff. - `400` and other `4xx` — fix the request first. - `401` — tokens last 48 hours and there are no refresh tokens: repeat the grant and retry once. - **Rate limits:** there is no documented rate limit or `Retry-After` today, so no `429` handling to implement. - Making a retried *create* safe: see [Retries and idempotency](https://code.salaxy.com/reference/idempotency.md). ## Errors of a single endpoint The reason for a `400` is in the `error` title, which is not stable. So the most useful documentation for an endpoint is a table of its failures and their causes. [Partner-initiated account creation](https://code.salaxy.com/security/account-creation.md) has one; use it as the pattern for the endpoints you integrate. ## Checklist - Your code branches on the HTTP status, never on the `error` text. - A `401` triggers one new token and one retry — not a loop. - A `5xx` without a body is handled. - `messageHtml` is shown to a person when a `400` needs fixing by hand. --- Source: https://code.salaxy.com/reference/queries.md # Queries and paging List endpoints accept an [OData](https://www.odata.org/)-style subset: **`$filter`, `$search`, `$orderby`**, and paging with **`$skip`** and **`$count`**. Queries run against a search index of list items (`ApiListItem`); each type — `CalculationListItem`, `EmploymentListItem` — customises its `data` and `status`. Examples use the **test** environment; see [Environments](https://code.salaxy.com/get-started/environments.md) for demo and production. ## The result ```json { "items": [ { "id": "f2b9…", "status": "paymentStarted", "updatedAt": "2026-10-15T08:12:00Z" } ], "nextPageLink": "https://test-secure.salaxy.com/v03/api/calculations?%24skip=50", "count": 123 } ``` - `items` — at most **50** list items per page. - `nextPageLink` — present when there are more. **Follow it until it is missing.** - `count` — the total for the filters, only when you ask with `$count=true` (slower — use it only when needed). **A list item is not the whole object.** When you need the full record — an employment's `info`, `work` and `contacts` — fetch it by id. ## Query options | Option | Example | |---|---| | `$filter` | `$filter=status eq 'paymentStarted'` · `$filter=otherPartyInfo/officialId eq '190372-942M'` | | `$search` | `$search='Palkkanen'` — searches the fields marked searchable. Salaxy extension: `$search=owner:…` and `$search=other:…`, which recognise a personal identity code or an id and filter on the right field | | `$orderby` | `$orderby=otherPartyInfo/avatar/sortableName asc, updatedAt desc` — default is usually `updatedAt desc` | | `$skip` | Paging, in steps of the page size (50; 1000 on the [Pro API](https://code.salaxy.com/integration/pro-api.md)) | | `$count` | `$count=true` adds `count` | ## Filter operators | Operator | Meaning | Example | |---|---|---| | `eq` | Equal | `$filter=status eq 'paymentSucceeded'` | | `ne` | Not equal | `$filter=status ne 'paymentSucceeded'` | | `gt`, `ge` | Greater than, or equal | `$filter=grossSalary ge 2000` | | `lt`, `le` | Less than, or equal | `$filter=grossSalary le 5000` | | `and` | Both | `$filter=salaryDate ge 2026-01-01 and salaryDate le 2026-03-31` | | `or` | Either | `$filter=status eq 'paymentSucceeded' or status eq 'paymentStarted'` | | `not` | Negation | `$filter=not (status eq 'paymentSucceeded')` | The string functions `contains`, `startswith`, `endswith` and `in` are **not supported**. Use `$search` for text. Which fields you can filter, search and sort on: [Query field reference](https://code.salaxy.com/reference/query-fields.md). ## Examples Replace `calculations` with the list you query. Money is in euros; dates are ISO 8601. ```http GET https://test-secure.salaxy.com/v03/api/calculations?$filter=externalId eq 'PARTNER-INV-00042' GET https://test-secure.salaxy.com/v03/api/calculations?$filter=salaryDate ge 2026-01-01 and salaryDate le 2026-03-31 GET https://test-secure.salaxy.com/v03/api/calculations?$orderby=salaryDate desc, grossSalary desc ``` To read every page, omit `$top` and follow `nextPageLink`. It advances `$skip`: ```http GET https://test-secure.salaxy.com/v03/api/calculations?$filter=status eq 'paymentSucceeded' GET https://test-secure.salaxy.com/v03/api/calculations?$filter=status eq 'paymentSucceeded'&$skip=50 ``` ## Avoid `$top` **`$top` suppresses `nextPageLink`**, so anything beyond that page is silently cut off. A `$top` above the page size returns `400`. To read everything, omit `$top` and follow `nextPageLink`. `$select` is accepted but discouraged (it returns a partial object, with no field-name check); `$expand` and `$value` are not supported. ## Checklist - Every list read follows `nextPageLink` until it is gone. - No `$top` in a query that must return everything. - Full records are fetched by id when list-item fields are not enough. --- Source: https://code.salaxy.com/reference/query-fields.md # Query field reference Every list endpoint returns list items of the type `ApiListItem`. This page shows which fields you can use in `$filter`, `$search` and `$orderby`. How to write the query: [Queries and paging](https://code.salaxy.com/reference/queries.md). Each list type (for example `CalculationListItem` or `EmploymentListItem`) adds its own fields in `data` and its own values in `status`. See the type in the [REST API reference](https://code.salaxy.com/reference/rest-api.md). ## ApiListItem | Field | Type | Filter | Search | Sort | Description | |---|---|---|---|---|---| | `backOfficeStatus` | string | ✓ | ✓ | ✓ | The back office status, depending on the type of the object | | `businessObjects` | string[] | ✓ | | | Ids of related objects, for example the calculations and payrolls in a payment | | `createdAt` | datetime | ✓ | | ✓ | When the object was created | | `data` | dictionary | ✓ | ✓ | | Business data of the list type. Filterable and searchable, not sortable | | `endAt` | date | ✓ | | ✓ | End date of the event. Usually the last user update; for a calculation, the payment date | | `entityType` | string | ✓ | ✓ | ✓ | Sub-category of the object | | `externalId` | string | ✓ | ✓ | ✓ | Your id for the object in your own system | | `fee` | number | ✓ | | ✓ | Estimated fee of the transaction | | `flags` | string[] | ✓ | ✓ | | Workflow flags | | `grossSalary` | number | ✓ | | ✓ | Gross salary, where relevant | | `id` | string | ✓ | ✓ | ✓ | Id of the object | | `isReadOnly` | boolean | | | | The object is read-only for the signed-in account | | `listType` | string | | | | The list item type | | `logicalDate` | datetime | ✓ | | ✓ | The date of the period the object is for | | `messages` | string[] | ✓ | ✓ | | Workflow messages, as `[MessageType]:[Message] ([User] at [UTC time])` | | `otherId` | string | ✓ | | ✓ | Id of the other party, today always the person id | | `otherPartyInfo` | AccountInIndex | see below | | | The other party, usually a person (for example the worker of a salary payment) | | `owner` | string | ✓ | | ✓ | Owner of the data. Always your own: you cannot query across owners | | `ownerId` | string | ✓ | | ✓ | Id of the owner. Nearly always the same as `owner` | | `ownerInfo` | AccountInIndex | see below | | | The owner | | `partner` | string | ✓ | ✓ | ✓ | The primary partner. Set automatically | | `payment` | number | ✓ | | ✓ | The payment from the owner's view: total payment for an employer, net salary for a worker | | `reference` | string | ✓ | ✓ | ✓ | A reference, for example a payment reference number | | `salaryDate` | date | ✓ | | ✓ | Calculations only: the expected salary date | | `shortText` | string | ✓ | ✓ | ✓ | A short description, for example "Paid salary" | | `startAt` | date | ✓ | | ✓ | Start date of the event. Usually the creation date | | `status` | string | ✓ | ✓ | ✓ | The main status. Values depend on the list type | | `timestamp` | datetime | ✓ | | ✓ | Last change by a user or by the system | | `type` | string | | | | The object type | | `updatedAt` | datetime | ✓ | | ✓ | Last update by a user | | `uri` | string | | | | Salaxy URI of the object | | `versionNumber` | number | | | | Version number | ## AccountInIndex `ownerInfo` and `otherPartyInfo` are of this type. Use a path in the query, for example `$filter=otherPartyInfo/officialId eq '190372-942M'` or `$orderby=otherPartyInfo/avatar/sortableName asc`. | Field | Type | Filter | Search | Sort | Description | |---|---|---|---|---|---| | `avatar/displayName` | string | ✓ | ✓ | ✓ | For a person, "FirstName LastName" | | `avatar/sortableName` | string | ✓ | ✓ | ✓ | For a person, "LastName, FirstName". Can be lower case | | `avatar/firstName` | string | ✓ | ✓ | ✓ | First name, or the company name | | `avatar/lastName` | string | ✓ | ✓ | ✓ | Last name. Empty for a company | | `avatar/entityType` | string | ✓ | ✓ | ✓ | `person`, `company`, `personCreatedByEmployer` or `partner` | | `avatar/description` | string | ✓ | ✓ | ✓ | Short description | | `avatar/initials` | string | ✓ | ✓ | ✓ | Initials | | `email` | string | ✓ | ✓ | ✓ | Email address | | `ibanNumber` | string | ✓ | ✓ | ✓ | Bank account number (IBAN) | | `officialId` | string | ✓ | ✓ | ✓ | Personal identity code or business ID | | `telephone` | string | ✓ | ✓ | ✓ | Telephone number | The other fields of `AccountInIndex` (`id`, `owner`, `partner`, `createdAt`, `updatedAt`, `isReadOnly` and the avatar picture fields) are returned, but you cannot query them. --- Source: https://code.salaxy.com/reference/idempotency.md # Retries and idempotency A network failure can leave you unsure whether a request went through. Retrying a **create** blindly can make a duplicate. **The REST API has no general idempotency key** — no `Idempotency-Key` header. The one exception is creating a payment message (v04 beta), which accepts an `Idempotency-Key` header: see [Payment channels](https://code.salaxy.com/integration/payment-channels.md#payment-messages-v04-beta) and [Limits](https://code.salaxy.com/reference/limits.md). Otherwise idempotency is endpoint-specific; this page collects what makes a retry safe. ## Give your records your own id, and look before you create Set your system's id on what you create, then search for it before creating again. | Object | Your id goes in | Find it again with | |---|---|---| | Employment | `info.sourceId` | `GET /v03/api/employments?$filter=externalId eq 'ID98765432'` — `sourceId` is indexed as `externalId` | For employments this also prevents a **duplicate worker record**: store `info.workerAccountId` from the first response and send it on any later employment for the same person — see [Create employees](https://code.salaxy.com/get-started/rest/create-employees.md#after-the-call). ## Safe to repeat - **Re-reporting an invoice's current status** is a safe no-op — see [Invoices and payments](https://code.salaxy.com/integration/invoices-and-payments.md#rules-that-save-you-a-day). - **Reads** (`GET`) are always safe. ## Never repeat blindly - **Committing a payroll for payment.** A calculation that is already `paymentStarted` cannot be committed again, and a `paymentSucceeded` one is never paid twice — but check the status before you retry. See [Set for payment](https://code.salaxy.com/get-started/rest/set-for-payment.md). ## On the MCP server On the authenticated MCP server, calculation rows added with a `sourceId` **replace** rows added earlier with the same id — so repeating the same request does not double the rows. Employment default rows and rows added by hand are left alone. ## Checklist - Every object you create carries your own id where the API allows one. - A retry after a timeout searches before it creates. - Payment commits are checked by status before any retry. --- Source: https://code.salaxy.com/reference/polling.md # Events and polling **There are no webhooks or push notifications today.** Your integration learns about changes by **polling** the read endpoints. That is enough for payroll: status changes follow banking-day events, not seconds. Polling every few minutes is plenty. ## What to poll | You are waiting for | Poll | Details | |---|---|---| | A salary to be paid | `GET /v03/api/calculations?$filter=status eq 'paymentStarted'` | [Track the payment status](https://code.salaxy.com/get-started/rest/track-status.md) | | A payroll to close | `GET /v03/api/payroll/{id}` — `info.status` | [Payroll lifecycle and statuses](https://code.salaxy.com/integration/payroll-lifecycle.md) | | Invoices for your payment channel | invoices with status `unread` | [Payroll lifecycle → polling](https://code.salaxy.com/integration/payroll-lifecycle.md#what-this-means-for-polling) | ## Rules - **Batch with list queries** rather than one `GET` per object, and follow `nextPageLink` — see [Queries and paging](https://code.salaxy.com/reference/queries.md). - **Stop polling an object once its status is final.** - **A quiet object is not a stuck one** — Salaxy never times a payment or an invoice out. Alert on your own expected processing time. - **Keep polling after the salary month closes**: tax and union invoices appear on day 6 of the following month. ## Checklist - One list query per interval, not one call per calculation. - Final statuses stop the polling for that object. - An alert fires when a payment stays `paymentStarted` longer than your channel normally takes. --- Source: https://code.salaxy.com/reference/limits.md # Limits, logging and correlation Salaxy publishes few hard limits. This page lists the ones that are stated, says what to log in your integration, and says what to send Salaxy when you need a server-side log lookup. Examples use the **test** environment; see [Environments](https://code.salaxy.com/get-started/environments.md) for demo and production. *Diagram: Your system calls the Salaxy API and logs every request with its own reference, the Salaxy ids from the response and the time. Salaxy logs the request on its side. When something fails, you send Salaxy the request time and the account id, and Salaxy looks up the server-side log. (Log both sides of every call. For a failure, Salaxy needs the request time and the account id to find the server-side log.)* ## Limits that are stated | Area | Limit | See | |---|---|---| | **Rate** | No rate limit or `Retry-After` is published today, so there is no `429` handling to implement. Poll at a sensible interval | [Errors](https://code.salaxy.com/reference/errors.md#retries), [Polling](https://code.salaxy.com/reference/polling.md) | | **List page size** | At most 50 items per page (1000 on the [Pro API](https://code.salaxy.com/integration/pro-api.md)). Follow `nextPageLink` until it is missing. `$top` above the page size returns `400` | [Queries](https://code.salaxy.com/reference/queries.md) | | **Access token lifetime** | 48 hours, no refresh tokens. Repeat the grant | [REST authentication](https://code.salaxy.com/security/rest-authentication.md#tokens) | | **Field lengths and formats** | Per the API reference. Validation failures name the field | [REST API reference](https://code.salaxy.com/reference/rest-api.md), [Errors](https://code.salaxy.com/reference/errors.md#the-error-body) | | **Idempotency** | No general idempotency key. Endpoint-specific only | [Retries and idempotency](https://code.salaxy.com/reference/idempotency.md) | Two limits apply only to v04 beta endpoints, see [Versions](https://code.salaxy.com/reference/versions.md#new-in-v04) and [Payment channels](https://code.salaxy.com/integration/payment-channels.md#payment-messages-v04-beta): - A data funnel file upload is at most 10 MB, and only `csv`, `tsv`, `txt`, `jsonl`, `xlsx`, `xls`, `ods` and `pdf` files are accepted. - A payment message create accepts an `Idempotency-Key` header: the same key and body within 24 hours returns the original message, and the same key with another body is refused. No limit is published for request size or for requests per minute. ## Logging on your side The API documents no correlation header, so build your own trail: - **Your own reference.** Keep a reference for every operation and store it with the Salaxy id you get back. A retried create then does not need a guess; see [Retries and idempotency](https://code.salaxy.com/reference/idempotency.md). - **Salaxy ids.** Log the id of every object you create or read (calculation, payroll, invoice, employment) and the account id you acted as. - **Request and response.** Log the method, path, HTTP status and time. Log the `error` and `validation` parts of a `400` body. Never log tokens or private keys. - **Personal data.** Payroll responses and SEPA files carry names and bank accounts. Keep them out of general logs. ## Asking Salaxy for a server-side log lookup Send the **time of the request** (with time zone) and the **account id** you acted as, plus the Salaxy id of the object if you have one. Use the contact channel agreed in your project; see [Support](https://code.salaxy.com/get-started/support.md). ## Checklist - Your code does not assume a rate limit header and does not loop on `429`. - Every list read follows `nextPageLink` and does not use `$top`. - You log your own reference, the Salaxy id, the account id, the status and the time of every call. - Tokens, keys and personal data stay out of your logs. - You can give Salaxy the request time and account id for any failed call. --- Source: https://code.salaxy.com/reference/versions.md # Versions and changes The REST API has two versions in the same URL space: `/v03/` and `/v04/`. This page says which one to build on, what changes when you move, and what changed recently. One exception: the [Pro API](https://code.salaxy.com/integration/pro-api.md) for accounting firms is also served under `/v01/api/pro/...`, and the site's Pro guide uses that path. Examples use the **test** environment; see [Environments](https://code.salaxy.com/get-started/environments.md) for demo and production. **Start on v03.** Salaxy API v03 is the current version. Salaxy API v04 is in beta: it may change, and it is not used in production yet. Build on v03, the current version. [Reference for v04 (beta)](https://code.salaxy.com/reference/rest-api-v04.md). *Diagram: Your integration calls the Salaxy API host with one access token. The same host serves two versions side by side. The v03 path serves every area of the API. The v04 path serves mostly the same endpoints, with the payroll endpoints redesigned. You can move one area at a time. (v03 and v04 run on the same hosts and accept the same token. The note above says which version to build on; move area by area.)* ## Where to read each version | | Reference | OpenAPI document | |---|---|---| | v03 | [REST API reference](https://code.salaxy.com/reference/rest-api.md) | [`/openapi/salaxy-03.json`](https://code.salaxy.com/openapi/salaxy-03.json) | | v04 | [REST API reference v04](https://code.salaxy.com/reference/rest-api-v04.md) | [`/openapi/salaxy-04.json`](https://code.salaxy.com/openapi/salaxy-04.json) | The API serves its own OpenAPI documents at `/openapi/v03.json` and `/openapi/v04.json` on each API host, for example `https://test-secure.salaxy.com/openapi/v03.json`. The earlier addresses under `/docs/swagger/` no longer work. ## From v03 to v04 Apart from the changes below, a v04 endpoint has the same path, parameters and models as in v03. To move a call, change `/v03/` to `/v04/` in the URL. v03 and v04 accept the same access token, so one integration can call both. ### Payroll The payroll endpoints are redesigned. In v03, most payroll actions are separate commands that take the whole payroll object. In v04, the calculations and invoices of a payroll are sub-resources of that payroll, and each call sends only what changes. | v03 | v04 | Notes | |---|---|---| | `GET /v03/api/payroll/odata` | `GET /v04/api/payroll` | The same OData list. `GET /v03/api/payroll` already works the same way | | `POST /v03/api/payroll/add-employment` | `POST /v04/api/payroll/{id}/employments` | Body is an array of employment ids. The response is the added calculations as `CalculationListItem` objects, not the payroll | | `POST /v03/api/payroll/add-calc` | `POST /v04/api/payroll/{id}/calcs` | Send the calculation ids in `ids` | | `POST /v03/api/payroll/{id}/calcs` | `POST /v04/api/payroll/{id}/calcs` | **Same path, different contract.** See below | | `POST /v03/api/payroll/delete-calc` | `DELETE /v04/api/payroll/{id}/calcs/{calcId}?delete=true` | One calculation per call. The calculation is deleted | | `POST /v03/api/payroll/unlink-calc` | `DELETE /v04/api/payroll/{id}/calcs/{calcId}` | One calculation per call. Without `delete=true` it is only removed from the payroll | | `GET /v03/api/payroll/cancel/{id}` | `POST /v04/api/payroll/{id}/cancel-invoices` | Body is an array of the calculation ids to cancel | | `POST /v03/api/payroll/validate` | none | No v04 equivalent. Keep using v03 | | `GET /v03/api/payroll/{id}/absences` | none | No v04 equivalent. Keep using v03 | New in v04: | Endpoint | Purpose | |---|---| | `GET /v04/api/payroll/{id}/calcs` | Lists the calculations of the payroll. Supports [OData queries](https://code.salaxy.com/reference/queries.md) | | `POST /v04/api/payroll/{id}/preview-invoices` | Previews the invoices for the given calculations | | `POST /v04/api/payroll/{id}/create-invoices` | Creates the invoices for the given calculations | The invoice endpoints use the payment channel of the payroll (`input.paymentChannel`), so the URL has no channel. The body is an array of calculation ids. The v03 invoice endpoints, for example `POST /v04/api/invoices/create-for-payroll/{channel}/{payrollId}`, also work in v04 unchanged. ```http POST https://test-secure.salaxy.com/v04/api/payroll/{payrollId}/create-invoices Authorization: Bearer {token} Content-Type: application/json ["{calcId1}", "{calcId2}"] ``` ### Saving calculations `POST /payroll/{id}/calcs` has the same path in both versions, but the request and the response differ: | | v03 | v04 | |---|---|---| | Request body | One `Calculation` object | A `PayrollCalculationsCollection`: `ids` (existing calculations to add) and `objects` (calculations to add or update) | | Response | The saved `Calculation` | An array of `CalculationListItem` objects | ```http POST https://test-secure.salaxy.com/v04/api/payroll/{payrollId}/calcs Authorization: Bearer {token} Content-Type: application/json { "ids": ["{calcId1}", "{calcId2}"] } ``` ### Options Some v04 payroll endpoints take an optional `options` object. Send its fields as ordinary query parameters, for example `?excludePeriodicInvoices=true`. | Endpoint | Options model | Fields | |---|---|---| | `POST /v04/api/payroll` | `PayrollSaveOptions` | `applyEmploymentDefaultRows` | | `POST /v04/api/payroll/{id}/calcs` | `PayrollCalculationsSaveOptions` | `isMerge`, `rowMergeOption`, `sourceId`, `applyEmploymentDefaultRows`, `applyWorktime` | | `.../preview-invoices`, `.../create-invoices`, `.../cancel-invoices` | `PayrollInvoicesOptions` | `excludePeriodicInvoices` | ### Reports These report endpoints are not in v04. Keep using v03 for them. | v03 endpoint | Notes | |---|---| | `GET /v03/api/reports/accounting/{refDate}` | Monthly or yearly `AccountingData` for an accounting target | | `GET` and `POST /v03/api/reports/accounting` | `AccountingData` for a set of calculations | | `GET /v03/api/reports/accounting/{refDate}/holiday-pay-debt` | Holiday pay debt as ledger entries. The report shape, `GET /v04/api/reports/holiday-pay-debt/{refDate}`, is in v04 | | `GET /v03/api/reports/validate/pay-certificate/{id}` | Validates a pay certificate request | `GET /v04/api/reports/data/accounting/{tableType}` and `GET /v04/api/reports/data/accounting/{tableType}/{refDate}` are in both versions. They return an `AccountingReportTable`, a different model from `AccountingData`, and take no accounting target. They do not replace the endpoints above. See [Accounting data](https://code.salaxy.com/integration/accounting-data.md). ### New in v04 | Area | Endpoints | |---|---| | Calculation corrections | `/v04/api/calculations/correction/...` | | Company authorisation | `POST /v04/api/company-authorization/link` creates a start link that sends a company representative to the authorisation flow. For testing without credentials, see [Test endpoints and test data](https://code.salaxy.com/reference/test-endpoints.md#test-helpers-in-v04-beta) | | Data funnel | `/v04/api/data-funnel/...`: import data from files and rows through plans, runs and transformations. See [Limits](https://code.salaxy.com/reference/limits.md) for the file upload | | Overview | `GET /v04/api/overview/all`, `GET /v04/api/overview/welcome-worker` | | Payment channel config | `/v04/api/settings/payment-channels/{channel}/config`: see [Company settings](https://code.salaxy.com/integration/company-settings.md#payment-channel-config). Errors are [problem details](https://code.salaxy.com/reference/errors.md#problem-details-on-new-v04-endpoints) | | Pro | `/v04/api/pro/...`: the [Pro API](https://code.salaxy.com/integration/pro-api.md), in the v04 Pro tag. The same endpoints are served under `/v01/api/pro/...`, which the Pro guide uses | Endpoints for creating and changing test data are listed in [Test endpoints and test data](https://code.salaxy.com/reference/test-endpoints.md). ## Which versions does an endpoint serve - **Availability is per endpoint.** Two endpoints of one controller can serve different versions. Check the endpoint in the OpenAPI document of the version you call, not its neighbour. - **An unversioned request resolves to v03.** - **Test can be ahead of production.** An endpoint in the test OpenAPI document may not be in production yet. See [Environments](https://code.salaxy.com/get-started/environments.md). ## Changelog Newest first. **Changes in the API** may affect your integration. **Added to the reference** only grows the reference: a client generated from it keeps working. ### v03 changes | Change | What to do | |---|---| | The calculation row type `script` is renamed to `info`. An `info` row is for information only | Use `info` in `rowType` and accept `info` in responses. The reference still lists `script`, so code generated from an earlier file compiles | | `Employment.accruals` is no longer used. The API does not store accrued time on the employment | Do not read or write `accruals`. For the remaining accrued holidays of an employment use `GET /v03/api/holidays/employment/{employmentId}/available-holiday-accruals` | | The OpenAPI documents come from a new tool. The API is the same, but model names and types differ from the earlier documents: for example `PageResult_CalculationListItem_` is now `PageResultOfCalculationListItem`, and many fields are nullable | A client generated from an earlier document does not compile against a client generated from these documents. Regenerate and adjust | ### Added to the v03 reference Nothing is removed or renamed. You can regenerate a client without code changes, but make sure it accepts enum values it does not know yet. | Area | Added | |---|---| | Calculator | `POST /v03/api/calculator/addrow`, `deleterow`, `salary`, `setunionpayment`, `taxdeduction`, `work`, `workerset`, `recalculate-worktime/{type}` | | Tax cards | `POST /v03/api/taxcards/approve/{method}`, `POST taxcards/file`, `GET taxcards/file/{id}`, `GET taxcards/issued`, `GET taxcards/my`, `GET taxcards/preview/{id}`, `GET taxcards/shared-exists/{personalId}` | | Invoices | `POST /v03/api/invoices/create/{channel}/{id}`, `preview/{channel}`, `preview-by-id/{channel}`, `preview-for-payroll/{channel}/{payrollId}` | | Reports | `GET` and `POST /v03/api/reports/data/accounting/{tableType}`, `GET reports/data/accounting/{tableType}/{refDate}`, `GET reports/pay-stats/{employmentId}`, `POST reports/pdf/{type}` | | Employments | `GET /v03/api/employments/employing`, `GET employments/employing/{id}` | | Query parameters | `$top` and `$skip` on several list endpoints; `version` on the SEPA endpoints | | Enum values | `CalculationRowType`: `info`; `PayStatsPeriodLength`: `holidayYear` | | Fields | Several optional fields. Diff the OpenAPI document for the full list. Among them are the `taxPercent` fields on `CalcTax` and `TaxcardResult` | ## Checklist - You build on the current version, not on a beta version. - You move one area at a time and test each in the test environment. - You do not send a v03 payroll body to a v04 path that has a different contract. - Your client accepts enum values it does not know yet. - You regenerate your client from the OpenAPI document of the version you call. --- Source: https://code.salaxy.com/reference/test-endpoints.md # Test endpoints and test data The test environment is where you build and try an integration with test data, without touching real people or real money. It also has test endpoints that create or change test data. The production API reference lists them too, but they are meant for test. Examples use the **test** environment; see [Environments](https://code.salaxy.com/get-started/environments.md) for demo and production. *Diagram: Your integration builds against the test environment, which holds test data only and has extra test endpoints for creating accounts, setting tax card data and triggering a tax invoice. Test and demo share the same data. When the integration is ready you switch the hosts to production, which has the same API and real data. Your code does not call the test endpoints there. (Build against test. Test endpoints help you create data; in production your code does not call them.)* ## What the test environment is for - **Test and demo share the same data.** Data created in one is visible in the other. Use fake data only, never real people's data. See [Environments](https://code.salaxy.com/get-started/environments.md). - **Test runs the latest development code.** An endpoint may exist in test before production. The test endpoints below are marked **v04 beta**: they may change. - **Get a test account first.** See [Get a test account](https://code.salaxy.com/get-started/test-account.md) and [Create an account](https://code.salaxy.com/get-started/rest/create-account.md). A test company account works in both test and demo. - **Some jobs do not run on their own in test.** If your flow needs a scheduled job, for example the [monthly cycle](https://code.salaxy.com/integration/monthly-cycle.md), ask Salaxy to trigger it. See [Support](https://code.salaxy.com/get-started/support.md). ## Test endpoints in v03 These are in the [Test](https://code.salaxy.com/reference/rest/test.md) and [TestData](https://code.salaxy.com/reference/rest/testdata.md) tag pages. The ones that change data work in the test environment only. | Method | Path | Purpose | |---|---|---| | `POST` | `/v03/api/test/accounts` | Creates a test account from an `Onboarding` object and returns the account details. For a person, fill in names and personal ID. For a company, fill in the company id, type and name, and the contact person. Test environment only | | `DELETE` | `/v03/api/test/accounts/{id}` | Deletes a test account. Test environment only | | `POST` | `/v03/api/test-data/taxcard-api` | Sets the data that the tax card API returns for a personal ID, so you can test [tax cards](https://code.salaxy.com/integration/tax-cards.md) without a real card. Body: `TaxcardInput` | | `GET` | `/v03/api/test-data/taxcard-api/{personalId}` | Reads the tax card data set for a personal ID | | `GET` | `/v03/api/test/delay` | Waits for the given number of seconds and returns it. For testing a long request. Test environment only | | `GET` | `/v03/api/test/user-name` | The user name of the current user. Requires a token | | `GET` | `/v03/api/test/user-name-allow-anon` | The user name, or `Anonymous` without a token | | `GET` | `/v03/api/test/authorization` | A welcome message that requires a token. Use it to check that your authentication works | | `GET` | `/v03/api/test/hello/{message}` | Returns the message. A call that needs no token | | `GET` | `/v03/api/test/exceptions/{type}` | Throws an exception, for testing your error handling. See [Errors](https://code.salaxy.com/reference/errors.md) | The rest of the Test tag (`values`, `serialization`, `odata`, `text/{lang}/{key}`, `testList`, `metrics/{name}`, `federation`, `token`, `testNullableBoolean`) are helpers for serialisation and platform tests. See the [Test](https://code.salaxy.com/reference/rest/test.md) tag page. ```http POST https://test-secure.salaxy.com/v03/api/test-data/taxcard-api Content-Type: application/json { "personalId": "190372-942M", "forYear": 2026 } ``` ## Reset and seed There is no single "reset" endpoint. The stated ways to control test data are: - **Create what you need.** Create test accounts, employees and calculations through the normal endpoints; see [Create an account](https://code.salaxy.com/get-started/rest/create-account.md). - **Delete a test account** with `DELETE /v03/api/test/accounts/{id}` when you want to start again. - **Set tax card data** with `POST /v03/api/test-data/taxcard-api` before you test a tax card lookup. If you need other seed data, ask Salaxy; see [Support](https://code.salaxy.com/get-started/support.md). ## Test helpers in v04 beta These work in the test environment only. They may change. Read their request and response models in the [v04 reference](https://code.salaxy.com/reference/rest-api-v04.md). | Area | Paths | Purpose | |---|---|---| | Tax invoice | `POST /v04/api/test/invoices/tax` | Rebuilds the current company's Tax invoice for a month from the month's paid salaries and releases it to the payment channel at once, also for the current month. Lets you test the tax payment without waiting for the monthly run. A read or paid Tax invoice blocks the rebuild: cancel it first. Also at `POST /v03/api/test/invoices/tax` | | Company authorisation | `POST /v04/api/company-authorization/link/test` | Creates a start link without credentials, naming the partner in the request. The flow the link starts is identical to production, so what you test is what ships. In production, use `POST /v04/api/company-authorization/link` | Other new endpoints, such as payment messages, the data funnel, the Pro workbench and the report table, are not test endpoints: they work in test and production alike. See [Versions](https://code.salaxy.com/reference/versions.md) and [Payment channels](https://code.salaxy.com/integration/payment-channels.md#payment-messages-v04-beta). ## Checklist - You build and test against the test environment and use fake data only. - Production hosts are in configuration, not in code: you switch them when you go live. - Your code does not call a test endpoint in production. - You treat the v04 test helpers as beta. --- Source: https://code.salaxy.com/reference/wage-types.md # Wage types (row types) A row type is the wage type of one row in a salary calculation: it says *what* is paid, deducted or reimbursed. It decides how the row is taxed, which side costs apply and how it is reported to the Incomes Register. Pick the right one; Salaxy calculates the rest. ## Where it goes Each row of a calculation carries its row type in `rows[].rowType`. The field is the `CalculationRowType` enum in the [REST API reference](https://code.salaxy.com/reference/rest-api.md). The same codes come back on the result rows, `result.rows[].rowType`. ```json { "rows": [ { "rowType": "monthlySalary", "count": 1, "price": 3200 }, { "rowType": "remuneration", "count": 1, "price": 500, "message": "Bonus", "data": { "kind": "bonusPay" } } ] } ``` - **Send the string, never a number.** A row type is a camelCase string on the wire, for example `"tesWorktimeShortening"`. - **`data.kind` picks a variant** where a row type has several, and on some row types it decides the income type reported. The descriptions below say where a kind is required. - **Obsolete codes still parse**, so old calculations keep working. Send the replacement named in the description. - **Some codes are misspelt** — `accomodationBenefit`, `nightimeAddition`, `milageOwnCar`. Send them exactly as listed. How rows fit into a calculation, with a full example: [Salary calculations](https://code.salaxy.com/integration/calculations.md). The same table with the Finnish labels: [Finnish labels](https://code.salaxy.com/api/row-types). ## Base salary The rows a calculation starts with. Plain count × price rows: the amount comes from the collective agreement or the employment contract, which Salaxy does not validate. | Code | Name | Description | |---|---|---| | `salary` | Piece-work pay | Piece-work or contract pay as one figure. Not a generic salary: for time-based pay use monthlySalary, hourlySalary or timeRatePay. | | `hourlySalary` | Hourly salary | Hours × hourly rate. | | `monthlySalary` | Monthly salary | The monthly salary as one figure. | | `timeRatePay` | Time-rate pay | Time-based pay counted in hours, days, weeks or months; data.kind gives the variant. | ## Working-time compensations Compensations set by a collective agreement. Salaxy does not know the agreement and does not check the rates. | Code | Name | Description | |---|---|---| | `tesWorktimeShortening` | Separate salary component (construction) | The construction sector's separate salary component: a fraction of the pay sum, default 7.7 %. | | `workingTimeCompensation` | Working-time compensation | One row type for every working-time compensation. data.kind chooses the Incomes Register income type; without a kind, nothing is reported. | | `hourlySalaryWithWorkingTimeCompensation` | Hourly salary with compensation | An hourly salary and its compensation, a percentage of the hourly rate, on one row. Send one row per kind of compensation. | ## Shift and overtime additions The premium only, not the pay for the hours: pay the hours on a base salary row. Nothing is computed for you; you send both count and price. | Code | Name | Description | |---|---|---| | `overtime` | Overtime premium | The overtime premium as a fraction of the pay sum, default 50 %. | | `eveningAddition` | Evening work addition | Hours × addition per hour. | | `nightimeAddition` | Night work addition | Hours × addition per hour. The code is spelt nightimeAddition. | | `saturdayAddition` | Saturday work addition | The Saturday premium as a fraction of the pay sum, default 50 %. | | `sundayWork` | Sunday and public holiday work | The premium for work on a Sunday or public holiday. | ## Paid absence Pay for time away, such as sick leave or training. These are salary rows; the absence itself is recorded with absencePeriod. | Code | Name | Description | |---|---|---| | `paidSickLeave` | Paid sick leave | Salary for sick leave. data.kind is required and chooses piece-work, hourly or monthly pay; without it the calculation cannot be paid. | | `training` | Paid training | Salary for time in training. data.kind is required, as on paidSickLeave. | | `paidSickLeaveSalary` | Sick leave pay, piece-work (obsolete) | Obsolete. Send paidSickLeave with kind paidSickLeaveSalary. | | `paidSickLeaveHourlySalary` | Sick leave pay, hourly (obsolete) | Obsolete. Send paidSickLeave with kind paidSickLeaveHourlySalary. | | `paidSickLeaveMonthlySalary` | Sick leave pay, monthly (obsolete) | Obsolete. Send paidSickLeave with kind paidSickLeaveMonthlySalary. | | `trainingSalary` | Training pay, piece-work (obsolete) | Obsolete and not reported correctly to the Incomes Register. Send training with kind trainingSalary. | | `trainingHourlySalary` | Training pay, hourly (obsolete) | Obsolete and not reported correctly to the Incomes Register. Send training with kind trainingHourlySalary. | | `trainingMonthlySalary` | Training pay, monthly (obsolete) | Obsolete and not reported correctly to the Incomes Register. Send training with kind trainingMonthlySalary. | ## Absences Unpaid absence and the private day care subsidy. Paid absence is a salary row; see Paid absence. | Code | Name | Description | |---|---|---| | `absencePeriod` | Absence period | Records an absence over a period. Salaxy generates the deduction and any paid-absence rows from it: send one absencePeriod, not a deduction of your own. | | `childCareSubsidy` | Private day care subsidy | The private day care subsidy towards a household employee's salary. Moves no money. Household employers only. | ## Holiday pay The money side of annual leave: pay for leave taken, compensation for leave not taken, and the holiday bonus. | Code | Name | Description | |---|---|---| | `holidaySalary` | Holiday pay | Pay for annual leave taken. | | `holidayCompensation` | Holiday compensation | Compensation for annual leave not taken, as a fraction of pay, default 11.5 %. | | `holidayBonus` | Holiday bonus | The holiday bonus. It comes from a collective agreement or the employment contract, not from law, so Salaxy sets no default rate. | ## Benefits in kind Taxable non-cash benefits. Where no kind prices the row, you compute the taxable value and send it as price. | Code | Name | Description | |---|---|---| | `carBenefit` | Car benefit | Private use of an employer's car. Compute the taxable value with the Tax Administration's car benefit calculator and send it as price; Salaxy does not compute it. | | `accomodationBenefit` | Accommodation benefit | A dwelling the employer provides; you compute the value. The code is spelt accomodationBenefit. | | `mealBenefit` | Meal benefit | Meals the employer arranges or subsidises. data.kind sets both the price and the income type reported. | | `phoneBenefit` | Phone benefit | A phone the employer pays for, one row per phone. Defaults to 20 € a month. | | `bicycleBenefit` | Bicycle benefit | A company bicycle. You price it; Salaxy splits the tax-free and taxable parts. | | `subsidisedCommute` | Commuter ticket | A personal public transport ticket the employer buys. Salaxy splits the tax-free and taxable parts. | | `otherBenefit` | Other benefit | Any other benefit in kind, at its fair market value. | ## Travel expenses Tax-free reimbursements: no employer side costs and no tax withheld. | Code | Name | Description | |---|---|---| | `dailyAllowance` | Daily allowance | Per diem for a work trip, domestic or foreign. data.kind sets the type and the price. | | `dailyAllowanceHalf` | Partial daily allowance | The partial per diem rate, not half a per diem. Prefer dailyAllowance with a kind. | | `mealCompensation` | Meal compensation | Meal compensation on a work trip. | | `milageOwnCar` | Mileage, own vehicle | Kilometre allowance for a vehicle the worker owns, priced per kilometre. Over the API, the price you send is used. | | `milageDaily` | Mileage, daily | Kilometre allowance set by a collective agreement as a daily sum, priced per day. | | `milageOther` | Mileage, other basis | Any other kilometre allowance. | ## Other expenses Cost reimbursements that are not travel. Each behaves differently in withholding and in Incomes Register reporting. | Code | Name | Description | |---|---|---| | `expenses` | Expense reimbursement | Reimbursement of costs against receipts. Not reported to the Incomes Register. | | `toolCompensation` | Tool compensation | Flat compensation for the worker's own tools. Taxable income for the worker, but no tax is withheld. | | `nonProfitOrg` | Non-profit allowances | Daily allowance or kilometre allowance paid by a non-profit organisation; data.kind chooses which. Not for household employers. | | `chainsawReduction` | Chainsaw and forestry worker deduction | Deducts the worker's chainsaw or forestry work costs before tax is withheld, instead of reimbursing them. | ## Other additions and termination Additions the other families do not cover. On all but otherAdditions, data.kind is the row: it decides the income type, withholding and contributions. | Code | Name | Description | |---|---|---| | `otherAdditions` | Other addition | A time-based addition agreed in a collective agreement or the employment contract that has no row type of its own. | | `remuneration` | One-off remuneration | A one-off performance payment such as a bonus, commission or initiative fee. data.kind chooses the income type; without it the row is worth nothing. | | `otherCompensation` | Other fee or compensation | Fees such as meeting, lecture or position-of-trust fees. data.kind chooses the income type. Not for household employers. | | `employmentTermination` | Employment termination | Payments that fall due when employment ends, such as notice-period compensation. data.kind chooses the income type. | ## Special salaries Payments that are neither wages nor wage additions: what the payment is comes from the Incomes Register income type. Not for household employers. | Code | Name | Description | |---|---|---| | `compensation` | Compensation for work | A fee for work done outside an employment relationship. | | `board` | Board fee | A fee for sitting on a board or a comparable governing body. Not for meeting fees. | | `irIncomeType` | Other income type | For an Incomes Register income type that no other row type reports; data.kind sets the income type. Loses the pricing and validation of a named row type. | ## Voluntary deductions Deductions from net pay by agreement, not by law. Send positive amounts. | Code | Name | Description | |---|---|---| | `unionPayment` | Union fee | Union membership fee taken from pay. For a percentage fee, count is the fraction and price the taxable salary. Add the IBAN and reference number to have the fee paid to the union. | | `advance` | Salary advance | Recovers money paid to the worker before payday. Not reported to the Incomes Register. | | `prepaidExpenses` | Prepaid expenses | Nets out an expense reimbursement already paid in advance. Not reported to the Incomes Register. | | `otherDeductions` | Other deduction | Any other deduction the worker has agreed to. | | `deductibleOfExerciseAndCultureBenefit` | Exercise and culture benefit, own share | The worker's own share of an employer-provided exercise and culture benefit. | ## Tax and foreclosure Withholdings required by law. Normally Salaxy, not the caller, owns these numbers. | Code | Name | Description | |---|---|---| | `taxWithholding` | Tax withholding | Overrides the withholding from the tax card and turns the tax card lookup off. Normally you send no tax row. | | `taxAtSource` | Tax at source | Tax at source for a worker on a tax-at-source card. Salaxy creates it from the employment; you normally do not send it. | | `foreclosure` | Foreclosure, paid by the employer | Wage garnishment the employer pays to the enforcement officer itself. data.kind chooses a fixed or a computed amount. One per calculation. | | `foreclosureByPalkkaus` | Foreclosure, paid by Salaxy | Wage garnishment Salaxy pays to the enforcement officer out of the payment it collects. Not offered for selection. | ## Reverse calculation Input-only rows: send one instead of a gross salary row, and Salaxy solves the gross pay. They are never reported to the Incomes Register. | Code | Name | Description | |---|---|---| | `totalWorkerPayment` | Net salary | The target net pay. data.kind says what the target is, and data.rowType names the row type to produce. | | `totalEmployerPayment` | Total employer cost | The target total cost for the employer. Always produces a piece-work pay (salary) row. | ## Other rows Rows that are not pay. | Code | Name | Description | |---|---|---| | `info` | Information line | A payslip line that moves no money; the text goes in message. | | `service` | Service fee | A service fee charged to the employer within the payroll. Send the price excluding VAT. | | `serviceCharge` | Service charge (obsolete) | Obsolete. Send service. | | `payStats` | Calculated earnings | A computed statistic, such as average hourly earnings, that Salaxy writes onto the employment. You normally do not send it. | | `totals` | Totals | Marks a totals row in results. Not valid on a row you send. | Codes as of 2026-11-11, from the production OpenAPI document. --- Source: https://code.salaxy.com/reference/yearly-numbers.md # Yearly numbers Many payroll figures change every year: contribution percentages, income limits, and the tax-free allowances that the Finnish Tax Administration (*Verohallinto*) sets for travel expenses. One anonymous endpoint returns them for a given date, so your system does not need to keep its own copy. Examples use the **test** environment; see [Environments](https://code.salaxy.com/get-started/environments.md) for demo and production. *Diagram: Your system calls one anonymous endpoint with a date, with no token. The Salaxy API answers with the numbers of that date's year in three parts: side costs such as contribution percentages and domestic tax-free allowances, tax-free numbers such as mileage rates and international daily allowances, and the public holidays of the year. A year that is not published yet returns 404. (One anonymous call returns the year's numbers in three parts.)* ## The endpoint | Method | Path | Purpose | |---|---|---| | `GET` | `/v03/api/calculator/yearlyNumbers/{forDate}` | All yearly changing numbers for the year of `forDate` | | `GET` | `/v03/api/calculator/yearlyHolidays/{forDate}` | Only the holidays of the year | The same two endpoints exist in v04 under `/v04/`. See [Versions and changes](https://code.salaxy.com/reference/versions.md). ```http GET https://test-secure.salaxy.com/v03/api/calculator/yearlyNumbers/2026-09-28 ``` - **No authentication.** You can call it without an access token. - **`forDate` selects the year.** Give an ISO 8601 date, for example `2026-09-28`. The year of that date decides the numbers. - **A year that is not published yet returns `404`.** The numbers of the next year become available when they are set, usually in December. Branch on the status, not on the message; see [Errors](https://code.salaxy.com/reference/errors.md). - **Do not trust the API reference description of the window.** It says the endpoint supports two years. In practice it serves every year from 2014 up to the latest published year, and `404` for any other. ## The response | Property | Content | |---|---| | `year` | The year that the numbers apply to | | `sideCosts` | Contribution percentages, income limits, the domestic tax-free allowances, meal benefit and meal ticket values, household deduction rates and the protected portion of foreclosure | | `taxFreeNumbers` | Tax-free mileage allowances per vehicle type and international daily allowances per country | | `holidays` | The Finnish public holidays of the year | The names of the fields are in the `YearlyChangingNumbers` and `YearlySideCosts` models of the [OpenAPI document](https://code.salaxy.com/reference/rest-api.md). Read the figures from the response; do not copy them from a document, because they change every year. ### Units All amounts are in euros. | Where | Unit | |---|---| | `sideCosts.taxFreeKmAllowance` | Euros per kilometre | | `sideCosts.taxFreeDailyAllowance`, `taxFreeDailyHalfAllowance` | Euros per day, domestic full and partial day | | `taxFreeNumbers.mileage.*` | Euros per kilometre | | `taxFreeNumbers.countries.*` | Euros per day | `sideCosts.taxFreeKmAllowance` and `taxFreeNumbers.mileage.car` hold the same base car rate. ### Mileage allowances `taxFreeNumbers.mileage` holds the tax-free kilometre allowance (*kilometrikorvaus*) per vehicle type, with the surcharges allowed on top of the base rate. | Field | Meaning | |---|---| | `car` | Base rate for the employee's own car | | `carLimitedBenefit` | Rate for a car with a limited car benefit (*käyttöetuauto*) when the employee pays the fuel or electricity | | `passenger` | Surcharge for each extra person who travels in the car | | `carAdditions.trailer`, `caravan`, `canteen`, `largeMachinery`, `dogInTheCar`, `constructionSite` | Surcharges for a trailer, a caravan, a towed break hut, heavy or large machinery, a dog in the car, and forest roads or construction sites closed to other traffic | | `other.*` | Base rates for other vehicles: motorboats, snowmobile, quad bike, motorcycle, moped and other transport | - **Surcharges.** `carAdditions` applies to `car` only. `passenger` applies to `car` and to the vehicles in `other`, but not to `carLimitedBenefit`. Add each surcharge that applies to the trip to the base rate. - **Send the full price on a `milageOwnCar` row.** The server does not price this row: it keeps the `price` you send. Compute the base rate plus the surcharges yourself. - **The keys are identifiers.** A `milageOwnCar` row stores them: `data.vehicleType` holds a key of `other` (or `car`, `carLimitedBenefit`, `custom`) and `data.additions` holds keys of `carAdditions`. Write them exactly as the API returns them. - **Older rows may carry earlier spellings.** Rows saved before the keys were corrected can contain `docInTheCar` (now `dogInTheCar`), `contstructionSite` (now `constructionSite`) or `snowMobile` (now `snowmobile`). If your system reads saved rows, accept both spellings. ### International daily allowances `taxFreeNumbers.countries` holds the tax-free daily allowance (*ulkomaan päiväraha*) for work trips abroad. The key is the country or region in English with a capital letter, for example `Sweden` or `UnitedStates`. The value is the full daily allowance in euros. - **The key is an identifier.** A daily allowance row stores it in `data.country`. Write it exactly as the API returns it. - **Finland is not in the list.** The domestic allowances are `taxFreeDailyAllowance` and `taxFreeDailyHalfAllowance` in `sideCosts`. - **The key `Other` covers the countries that are not listed.** ## Years that are covered | Date in `forDate` | `sideCosts` | `taxFreeNumbers` | |---|---|---| | 2022 or later, up to the latest published year | That year's numbers | That year's numbers | | Before 2022 | That year's numbers | **The latest year's numbers.** Do not use them | | A year that is not published yet | `404` | `404` | Old years can hold `0` in fields that were not recorded. A `0` in an early year means "not recorded", not "zero". ## Test it Call the endpoint without a token for a date in the current year, then for a date a few years ahead and check that you get `404`. Then create a row that uses the numbers: see [Salary calculations](https://code.salaxy.com/integration/calculations.md). ## Checklist - You read the figures from the API (or cache them for the year) and do not copy them into your code. - You branch on `404` for a year that is not published. - Keys such as `Sweden` and `dogInTheCar` are written exactly as returned. - A `milageOwnCar` row carries the full price, base rate plus surcharges. - You do not use `taxFreeNumbers` for a date before 2022. --- Source: https://code.salaxy.com/problems/index.md # Problem types Some endpoints answer errors as **problem details** ([RFC 9457](https://www.rfc-editor.org/rfc/rfc9457)). Each error names its problem type in `type`. This is a stable URI under `https://code.salaxy.com/problems/` that opens the page describing it. Endpoints that use problem details say so on their own page. Today these are the [payment channel config](https://code.salaxy.com/integration/company-settings.md#payment-channel-config) endpoints (v04 beta). Other endpoints use the error shape in [Error handling](https://code.salaxy.com/reference/errors.md). ## The response A problem details response has `Content-Type: application/problem+json` and this body: ```json { "type": "https://code.salaxy.com/problems/validation-failed", "status": 422, "title": "The payment channel config is not valid.", "errors": { "debitAccount.iban": [ "The IBAN is not valid." ], "data.agreementId": [ "Required." ] } } ``` | Field | Notes | |---|---| | `type` | The problem type. **Branch on this URI**, or on the status — never on the text. | | `status` | The HTTP status code, the same as the response's. | | `title` | A short summary, the same for every occurrence of the type. | | `detail` | An explanation of this occurrence. Can be missing. | | `errors` | `validation-failed` only: the messages per field, keyed by the field's path in the request body, for example `data.agreementId`. | `title`, `detail` and the messages in `errors` follow the `Accept-Language` request header: `fi` or `en`. The language is Finnish when the header is missing or names neither. `Content-Language` names the language of the response. `401` and `403` are never problem details. They come from the authentication, as on every endpoint. See [Error handling](https://code.salaxy.com/reference/errors.md). ## Types | Type | Status | Meaning | |---|---|---| | [`not-found`](https://code.salaxy.com/problems/not-found.md) | 404 | The resource does not exist. | | [`channel-not-available`](https://code.salaxy.com/problems/channel-not-available.md) | 409 | The payment channel is not available to the company. | | [`concurrent-change`](https://code.salaxy.com/problems/concurrent-change.md) | 409 | Concurrent changes kept the write from saving. Nothing was saved. | | [`precondition-failed`](https://code.salaxy.com/problems/precondition-failed.md) | 412 | `If-Match` or `If-None-Match` does not hold. | | [`unsupported-media-type`](https://code.salaxy.com/problems/unsupported-media-type.md) | 415 | The request body has the wrong content type. | | [`validation-failed`](https://code.salaxy.com/problems/validation-failed.md) | 422 | The request body is not valid; `errors` lists the messages per field. | | [`internal-error`](https://code.salaxy.com/problems/internal-error.md) | 500 | An unexpected error in Salaxy. | --- Source: https://code.salaxy.com/problems/not-found.md # Problem type: not-found **404 Not Found.** The resource does not exist. `type`: `https://code.salaxy.com/problems/not-found` ## When On the [payment channel config](https://code.salaxy.com/integration/company-settings.md#payment-channel-config) endpoints (v04 beta): - The channel key in the path is unknown, or the channel has no config to set. - The channel is neither available to the company nor configured. - `GET`, `PATCH` or `DELETE` when the company has no config. This includes a `DELETE` when a concurrent `DELETE` removed the config first. The `detail` text is the same in each case. ## What to do Check the channel key in the path. To create a config, use `PUT`. `PATCH` changes only an existing one. Sending the same request again does not help. See all [problem types](https://code.salaxy.com/problems/index.md). --- Source: https://code.salaxy.com/problems/channel-not-available.md # Problem type: channel-not-available **409 Conflict.** The payment channel is not available to the company. `type`: `https://code.salaxy.com/problems/channel-not-available` ## When On the [payment channel config](https://code.salaxy.com/integration/company-settings.md#payment-channel-config) endpoints (v04 beta): a `PUT` or `PATCH` when the channel is no longer available to the company but a config is still stored. Such a config can only be read or deleted. ## What to do Salaxy manages which payment channels a company can use, not this endpoint. Check with Salaxy that the channel is enabled for the company. To remove the stored config, use `DELETE`. Sending the same request again does not help. See all [problem types](https://code.salaxy.com/problems/index.md). --- Source: https://code.salaxy.com/problems/concurrent-change.md # Problem type: concurrent-change **409 Conflict.** Concurrent changes kept the write from saving. Nothing was saved. `type`: `https://code.salaxy.com/problems/concurrent-change` ## When On the [payment channel config](https://code.salaxy.com/integration/company-settings.md#payment-channel-config) endpoints (v04 beta): a `PUT`, `PATCH` or `DELETE` while the company settings kept changing. Salaxy tries the save three times, then gives up. ## What to do Read the config again with `GET`, and retry your change. This is different from [`precondition-failed`](https://code.salaxy.com/problems/precondition-failed.md): here the config itself may be unchanged. See all [problem types](https://code.salaxy.com/problems/index.md). --- Source: https://code.salaxy.com/problems/precondition-failed.md # Problem type: precondition-failed **412 Precondition Failed.** The `If-Match` or `If-None-Match` header of the request does not hold. `type`: `https://code.salaxy.com/problems/precondition-failed` ## When On the [payment channel config](https://code.salaxy.com/integration/company-settings.md#payment-channel-config) endpoints (v04 beta): - `If-Match` does not match the stored version, or names a config that does not exist. This also applies when the config changed during a write with `If-Match`, a `DELETE` included. - `If-None-Match: *` on a `PUT` when a config already exists. ## What to do Someone changed the config after you read it. Read it again with `GET`, check that your change still applies, and send it with the new `ETag` as `If-Match`. See all [problem types](https://code.salaxy.com/problems/index.md). --- Source: https://code.salaxy.com/problems/unsupported-media-type.md # Problem type: unsupported-media-type **415 Unsupported Media Type.** The request body has the wrong content type. `type`: `https://code.salaxy.com/problems/unsupported-media-type` ## When On the [payment channel config](https://code.salaxy.com/integration/company-settings.md#payment-channel-config) endpoints (v04 beta): - A `PATCH` with any content type other than `application/merge-patch+json`. This includes `application/json`. - A `PUT` with a body that is not `application/json`. ## What to do Send a `PATCH` as a JSON Merge Patch ([RFC 7396](https://www.rfc-editor.org/rfc/rfc7396)) with `Content-Type: application/merge-patch+json`. Send a `PUT` with `Content-Type: application/json`. Every `PATCH` response carries `Accept-Patch: application/merge-patch+json`. See all [problem types](https://code.salaxy.com/problems/index.md). --- Source: https://code.salaxy.com/problems/validation-failed.md # Problem type: validation-failed **422 Unprocessable Entity.** The request body is not valid. `errors` lists the messages per field. `type`: `https://code.salaxy.com/problems/validation-failed` ## When On the [payment channel config](https://code.salaxy.com/integration/company-settings.md#payment-channel-config) endpoints (v04 beta), a `PUT` or a `PATCH` when, for example: - A required value is missing or invalid, such as `data.agreementId` or `debitAccount.iban`. - The body has a field, or a `data` key, that the config does not have. - A `channel` in the body differs from the path. A `PATCH` is checked on the result: clearing a required value with `null` fails too. Nothing is saved. ```json { "type": "https://code.salaxy.com/problems/validation-failed", "status": 422, "title": "The payment channel config is not valid.", "errors": { "debitAccount.iban": [ "The IBAN is not valid." ], "data.agreementId": [ "Required." ] } } ``` `errors` is keyed by the field's path in the request body. The messages follow `Accept-Language` (`fi` or `en`, Finnish by default). ## What to do Fix the fields that `errors` names. Sending the same request again does not help. See all [problem types](https://code.salaxy.com/problems/index.md). --- Source: https://code.salaxy.com/problems/internal-error.md # Problem type: internal-error **500 Internal Server Error.** An unexpected error in Salaxy. `type`: `https://code.salaxy.com/problems/internal-error` ## When Any endpoint that answers with problem details can return it. The response tells nothing about the cause. ## What to do Retry later with backoff. If the error repeats, contact Salaxy customer service. See all [problem types](https://code.salaxy.com/problems/index.md). --- Source: https://code.salaxy.com/countries/index.md # Countries Salaxy is built as **one platform with a payroll engine per country**. What is shared and what is local: | Shared across countries | Local to each country | |---|---| | Core concepts — account, worker, employment, calculation, payroll | Wage types, tax, social insurance and pension rules | | How you connect an MCP client | Its **own MCP endpoint** | | How skills work — root router, areas, references, evals | Its **own skill set**, in the domain language | | This documentation | Authority reporting and payment specifics | | Country | MCP and skills | REST API | Embedded white label | |---|---|---|---| | Finland | Live | Live | Live | | Sweden | Coming Q3 2027 | Finland only | To be decided | | Denmark | Planned Q4 2027 – Q1 2028 | Finland only | To be decided | | Norway | Planned Q4 2027 – Q1 2028 | Finland only | To be decided | Status as of September 2026. Timelines are targets, not commitments. ## How new countries launch New countries launch on **MCP and skills** only. The REST API stays Finland only. For an integrator this means: build your agent against the Finnish endpoint now, **name servers by country** (`salaxy-payroll-fi`, later `salaxy-payroll-se`), and let your agent choose the server by the employer's country. Do not route one country's payroll through another country's tools — Finnish tools apply Finnish law only. - [Finland](https://code.salaxy.com/countries/finland.md) — live - [Sweden](https://code.salaxy.com/countries/sweden.md) — coming Q3 2027 - [Denmark](https://code.salaxy.com/countries/denmark.md) — planned Q4 2027 – Q1 2028 - [Norway](https://code.salaxy.com/countries/norway.md) — planned Q4 2027 – Q1 2028 --- Source: https://code.salaxy.com/countries/finland.md # Finland **Status (September 2026):** MCP and skills: Live · REST API: Live · Embedded white label: Live. Finland is Salaxy's home market and the only country where **all three surfaces** are live. ## MCP | Endpoint | Status | Use | |---|---|---| | `https://payroll.salaxy.com/mcp` | [Live] | Payroll Agent: your companies' payroll, with your Salaxy account | | `https://reporting.salaxy.com/mcp` | [Live] | Report Agent: salary slips, reports and Incomes Register | | `https://demo-payroll.salaxy.com/mcp` · `https://demo-reporting.salaxy.com/mcp` | [Live] | The same agents on sample data, with a free demo account | | Configuration Agent · Data Agent | [Coming soon] | Payroll settings · importing data from other systems | [Connect a client →](https://code.salaxy.com/get-started/agentic/index.md) · [MCP reference](https://code.salaxy.com/reference/mcp.md) ## Skills The Finnish skill set covers the whole payroll process, with a catalogue of Finnish wage types, Incomes Register income types, TyEL, YEL and MYEL pension insurance, yearly-changing rates and limits, and out-of-scope situations. Content is in Finnish for now, moving to English. [Skills reference →](https://code.salaxy.com/reference/skills.md) · [Verified coverage](https://code.salaxy.com/reference/verified.md) **Scope.** The Finnish skills cover private-sector employers paying employees in Finland. International situations and public-sector employers are out of scope, and the agent says so rather than calculating. ## REST API The full API. [Get started →](https://code.salaxy.com/get-started/rest/index.md) · [Reference](https://code.salaxy.com/reference/rest-api.md) · [Environments](https://code.salaxy.com/get-started/environments.md) **Start on v03.** Salaxy API v03 is the current version. Salaxy API v04 is in beta: it may change, and it is not used in production yet. Build on v03, the current version. [Reference for v04 (beta)](https://code.salaxy.com/reference/rest-api-v04.md). ## Embedded white label Salaxy's payroll UI embedded in your product, in two products: **Salaxy Business** for one company's payroll, and **Salaxy Pro** for accounting firms and payroll outsourcing. [Overview →](https://code.salaxy.com/white-label/index.md) --- Source: https://code.salaxy.com/countries/sweden.md # Sweden **Status (September 2026):** MCP and skills: Coming Q3 2027 · REST API: Finland only · Embedded white label: To be decided. **Not available yet.** Sweden payroll cannot be calculated with the current tools. Support is targeted for Q3 2027. Timelines are targets, not commitments. Sweden is the **next country** on the Salaxy platform. Support is targeted for **Q3 2027**. ## What is coming - **An MCP server for Sweden** — a separate endpoint, published at launch. - **A skill set for Sweden** — wage types, tax, social insurance and employer reporting under Sweden's rules, with its own eval suite. ## What is not - **No REST API.** The REST API stays Finland only. - **Embedded white label** is not yet decided for Sweden. ## What stays the same If you build on the Finnish MCP server today, most of your work carries over: - the [core concepts](https://code.salaxy.com/about/concepts.md) — account, worker, employment, calculation, payroll; - how you [connect an MCP client](https://code.salaxy.com/get-started/agentic/index.md) — only the endpoint changes; - how [skills](https://code.salaxy.com/get-started/agentic/skills.md) are structured and loaded, and how [evals](https://code.salaxy.com/reference/verified.md) verify them. Name your servers by country (`salaxy-payroll-fi`, later `salaxy-payroll-se`) so your agent can route by the employer's country. **For agents reading this page:** Sweden payroll is **not available**. Do not use the Finnish tools or skills for Sweden — they apply Finnish law only. Tell the user that support for Sweden is targeted for Q3 2027. ## Talk to us Planning a product for Sweden? [Get in touch with Salaxy](https://www.salaxy.com) — early partners help decide what launches first. --- Source: https://code.salaxy.com/countries/denmark.md # Denmark **Status (September 2026):** MCP and skills: Planned Q4 2027 – Q1 2028 · REST API: Finland only · Embedded white label: To be decided. **Not available yet.** Denmark payroll cannot be calculated with the current tools. Support is targeted for Q4 2027 – Q1 2028. Timelines are targets, not commitments. Denmark is **planned** after Sweden. Support is targeted for **Q4 2027 – Q1 2028**. ## What is coming - **An MCP server for Denmark** — a separate endpoint, published at launch. - **A skill set for Denmark** — wage types, tax, social insurance and employer reporting under Denmark's rules, with its own eval suite. ## What is not - **No REST API.** The REST API stays Finland only. - **Embedded white label** is not yet decided for Denmark. ## What stays the same If you build on the Finnish MCP server today, most of your work carries over: - the [core concepts](https://code.salaxy.com/about/concepts.md) — account, worker, employment, calculation, payroll; - how you [connect an MCP client](https://code.salaxy.com/get-started/agentic/index.md) — only the endpoint changes; - how [skills](https://code.salaxy.com/get-started/agentic/skills.md) are structured and loaded, and how [evals](https://code.salaxy.com/reference/verified.md) verify them. Name your servers by country (`salaxy-payroll-fi`, later `salaxy-payroll-dk`) so your agent can route by the employer's country. **For agents reading this page:** Denmark payroll is **not available**. Do not use the Finnish tools or skills for Denmark — they apply Finnish law only. Tell the user that support for Denmark is targeted for Q4 2027 – Q1 2028. ## Talk to us Planning a product for Denmark? [Get in touch with Salaxy](https://www.salaxy.com) — early partners help decide what launches first. --- Source: https://code.salaxy.com/countries/norway.md # Norway **Status (September 2026):** MCP and skills: Planned Q4 2027 – Q1 2028 · REST API: Finland only · Embedded white label: To be decided. **Not available yet.** Norway payroll cannot be calculated with the current tools. Support is targeted for Q4 2027 – Q1 2028. Timelines are targets, not commitments. Norway is **planned** after Sweden. Support is targeted for **Q4 2027 – Q1 2028**. ## What is coming - **An MCP server for Norway** — a separate endpoint, published at launch. - **A skill set for Norway** — wage types, tax, social insurance and employer reporting under Norway's rules, with its own eval suite. ## What is not - **No REST API.** The REST API stays Finland only. - **Embedded white label** is not yet decided for Norway. ## What stays the same If you build on the Finnish MCP server today, most of your work carries over: - the [core concepts](https://code.salaxy.com/about/concepts.md) — account, worker, employment, calculation, payroll; - how you [connect an MCP client](https://code.salaxy.com/get-started/agentic/index.md) — only the endpoint changes; - how [skills](https://code.salaxy.com/get-started/agentic/skills.md) are structured and loaded, and how [evals](https://code.salaxy.com/reference/verified.md) verify them. Name your servers by country (`salaxy-payroll-fi`, later `salaxy-payroll-no`) so your agent can route by the employer's country. **For agents reading this page:** Norway payroll is **not available**. Do not use the Finnish tools or skills for Norway — they apply Finnish law only. Tell the user that support for Norway is targeted for Q4 2027 – Q1 2028. ## Talk to us Planning a product for Norway? [Get in touch with Salaxy](https://www.salaxy.com) — early partners help decide what launches first. --- Source: https://code.salaxy.com/reference/mcp.md # MCP reference Generated on 2026-11-16. Where the build could read a server, the descriptions below are **the exact text the model receives** — nothing is rewritten for this page. Every public server needs an OAuth sign-in; a server the build could not sign in to is listed with its tools and their summaries. Salaxy runs **one MCP server per Salaxy AI agent and country**, each in two environments: **demo** (a free demo account and sample data) and **production** (your own Salaxy account). Only Finland is live today; see [Availability](https://code.salaxy.com/about/availability.md) and [MCP authentication](https://code.salaxy.com/security/mcp-authentication.md). ## Finland — Payroll Agent, demo | | | |---|---| | Endpoint | `https://demo-payroll.salaxy.com/mcp` | | Transport | Streamable HTTP | | Authentication | OAuth sign-in with a free demo account | | Status | [Live] | Try the Payroll Agent on sample data: employments, calculations, payrolls, absences, holidays and invoices. Nothing real is paid or reported. | Tool | Summary | |---|---| | `employer_list` | List the employers the user may act for: their own account and the accounts that have authorised them — e.g. an accounting firm's customers. | | `employer_select` | Select the employer the other tools work in when no employer id is given — only after the user has chosen; never chosen for the user. | | `calculation_preview` | Preview a salary calculation. | | `calculation_create` | Create a salary calculation. | | `calculation_set_rows` | Set salary rows of a calculation. | | `calculation_update` | Update a salary calculation. | | `calculation_get_summary` | Get a calculation summary. | | `calculation_show_slip` | Show the salary slip of a calculation. | | `calculation_copy` | Copy a salary calculation. | | `calculation_search` | Search salary calculations. | | `row_type_list` | List custom wage types. | | `employment_search` | Search employments. | | `employment_get_summary` | Get an employment summary. | | `employment_create` | Create an employment. | | `employment_update` | Update an employment. | | `employment_set_rows` | Set the default rows of an employment. | | `invoice_search` | Search invoices. | | `invoice_get_summary` | Get an invoice summary. | | `invoice_preview` | Preview the payment of a payroll or a calculation. | | `invoice_confirm` | Confirm the payment of a payroll or a calculation. | | `payroll_create` | Create a payroll. | | `payroll_copy` | Copy a payroll. | | `payroll_set_employments` | Set the employees of a payroll. | | `payroll_set_rows` | Set salary rows of employees in a payroll. | | `payroll_update` | Update a payroll. | | `payroll_remove_calculation` | Remove a calculation from a payroll. | | `payroll_get_summary` | Get a payroll summary. | | `payroll_show_slips` | Show the salary slips of a payroll. | | `payroll_search` | Search payrolls. | | `absence_search` | Search the absence periods of all employees, e.g. who is absent in a given month. | | `absence_get_summary` | Get the absence calendar of one employee: periods with cause, paid or unpaid, and holiday accrual. | | `absence_set_periods` | Add, change or remove absence periods of an employee: sick leave, annual leave, unpaid leave, lay-off. | | `holiday_spec_get_summary` | Get the holiday specification of an employee: how holidays accrue and how holiday pay and bonus are calculated. | | `holiday_spec_update` | Change the holiday specification of an employee, and by default the accruing holiday year with it. | | `holiday_year_create` | Create the missing holiday years of an employee from the holiday specification. | | `holiday_year_search` | Search the remaining holiday days and bonus days of the employees over all holiday years. | | `holiday_year_get_summary` | Get one holiday year: accrual by month, planned leaves, paid holiday salaries, balance and holiday pay. | | `holiday_year_set_accruals` | Set the holiday days accrued in given months, and the days carried over from the previous year. | | `holiday_year_set_leaves` | Add, change or remove planned annual leaves and holiday payments made outside Salaxy. | | `holiday_year_update` | Set manual holiday pay values that override the calculated ones. | | `holiday_year_recalculate` | Recalculate the holiday pay of a holiday year from the paid salary calculations. | ## Finland — Report Agent, demo | | | |---|---| | Endpoint | `https://demo-reporting.salaxy.com/mcp` | | Transport | Streamable HTTP | | Authentication | OAuth sign-in with a free demo account | | Status | [Live] | Try the Report Agent on sample data: salary slips, summary and accounting reports, holiday pay debt and Incomes Register reports. | Tool | Summary | |---|---| | `employer_list` | List the employers the user may act for: their own account and the accounts that have authorised them — e.g. an accounting firm's customers. | | `employer_select` | Select the employer the other tools work in when no employer id is given — only after the user has chosen; never chosen for the user. | | `calculation_search` | Search salary calculations. | | `employment_search` | Search employments. | | `salary_slip` | Show the salary slips of calculations as rendered documents (widget). | | `salary_slip_pdf` | Get salary slips as PDF files for saving, archiving or attaching to an email. | | `summary_report` | Show the summary report of a period or of given calculations as a table (widget). | | `salary_summary` | Get the salary summary of a period: gross and net salaries, withholding, side costs and total cost. | | `accounting_report` | Get the accounting report of a period: totals per ledger account with a balance check. | | `holiday_pay_debt` | Get the holiday pay debt on a date as accounting data. | | `ir_reports` | List Incomes Register reports by period, status or text, e.g. the rejected reports of a month. | | `ir_report` | Get an Incomes Register report: status, delivery times, errors and the reported amounts. | ## Finland — Payroll Agent, production | | | |---|---| | Endpoint | `https://payroll.salaxy.com/mcp` | | Transport | Streamable HTTP | | Authentication | OAuth sign-in with your Salaxy account | | Status | [Live] | Your own companies' payroll: employments, calculations, payrolls, absences, holidays and invoices. A person always approves a payment. | Tool | Summary | |---|---| | `employer_list` | List the employers the user may act for: their own account and the accounts that have authorised them — e.g. an accounting firm's customers. | | `employer_select` | Select the employer the other tools work in when no employer id is given — only after the user has chosen; never chosen for the user. | | `calculation_preview` | Preview a salary calculation. | | `calculation_create` | Create a salary calculation. | | `calculation_set_rows` | Set salary rows of a calculation. | | `calculation_update` | Update a salary calculation. | | `calculation_get_summary` | Get a calculation summary. | | `calculation_show_slip` | Show the salary slip of a calculation. | | `calculation_copy` | Copy a salary calculation. | | `calculation_search` | Search salary calculations. | | `row_type_list` | List custom wage types. | | `employment_search` | Search employments. | | `employment_get_summary` | Get an employment summary. | | `employment_create` | Create an employment. | | `employment_update` | Update an employment. | | `employment_set_rows` | Set the default rows of an employment. | | `invoice_search` | Search invoices. | | `invoice_get_summary` | Get an invoice summary. | | `invoice_preview` | Preview the payment of a payroll or a calculation. | | `invoice_confirm` | Confirm the payment of a payroll or a calculation. | | `payroll_create` | Create a payroll. | | `payroll_copy` | Copy a payroll. | | `payroll_set_employments` | Set the employees of a payroll. | | `payroll_set_rows` | Set salary rows of employees in a payroll. | | `payroll_update` | Update a payroll. | | `payroll_remove_calculation` | Remove a calculation from a payroll. | | `payroll_get_summary` | Get a payroll summary. | | `payroll_show_slips` | Show the salary slips of a payroll. | | `payroll_search` | Search payrolls. | | `absence_search` | Search the absence periods of all employees, e.g. who is absent in a given month. | | `absence_get_summary` | Get the absence calendar of one employee: periods with cause, paid or unpaid, and holiday accrual. | | `absence_set_periods` | Add, change or remove absence periods of an employee: sick leave, annual leave, unpaid leave, lay-off. | | `holiday_spec_get_summary` | Get the holiday specification of an employee: how holidays accrue and how holiday pay and bonus are calculated. | | `holiday_spec_update` | Change the holiday specification of an employee, and by default the accruing holiday year with it. | | `holiday_year_create` | Create the missing holiday years of an employee from the holiday specification. | | `holiday_year_search` | Search the remaining holiday days and bonus days of the employees over all holiday years. | | `holiday_year_get_summary` | Get one holiday year: accrual by month, planned leaves, paid holiday salaries, balance and holiday pay. | | `holiday_year_set_accruals` | Set the holiday days accrued in given months, and the days carried over from the previous year. | | `holiday_year_set_leaves` | Add, change or remove planned annual leaves and holiday payments made outside Salaxy. | | `holiday_year_update` | Set manual holiday pay values that override the calculated ones. | | `holiday_year_recalculate` | Recalculate the holiday pay of a holiday year from the paid salary calculations. | ## Finland — Report Agent, production | | | |---|---| | Endpoint | `https://reporting.salaxy.com/mcp` | | Transport | Streamable HTTP | | Authentication | OAuth sign-in with your Salaxy account | | Status | [Live] | Reports on your own companies' payroll: salary slips, summary and accounting reports, holiday pay debt and Incomes Register reports. | Tool | Summary | |---|---| | `employer_list` | List the employers the user may act for: their own account and the accounts that have authorised them — e.g. an accounting firm's customers. | | `employer_select` | Select the employer the other tools work in when no employer id is given — only after the user has chosen; never chosen for the user. | | `calculation_search` | Search salary calculations. | | `employment_search` | Search employments. | | `salary_slip` | Show the salary slips of calculations as rendered documents (widget). | | `salary_slip_pdf` | Get salary slips as PDF files for saving, archiving or attaching to an email. | | `summary_report` | Show the summary report of a period or of given calculations as a table (widget). | | `salary_summary` | Get the salary summary of a period: gross and net salaries, withholding, side costs and total cost. | | `accounting_report` | Get the accounting report of a period: totals per ledger account with a balance check. | | `holiday_pay_debt` | Get the holiday pay debt on a date as accounting data. | | `ir_reports` | List Incomes Register reports by period, status or text, e.g. the rejected reports of a month. | | `ir_report` | Get an Incomes Register report: status, delivery times, errors and the reported amounts. | ## Finland — Configuration Agent | | | |---|---| | Endpoint | _published when the endpoint opens_ | | Transport | Streamable HTTP | | Authentication | _published when it opens_ | | Status | [Coming soon] | Payroll settings: wage types, templates, holiday and pay rules, cost-centre dimensions and reporting settings. Demo and production endpoints are published when it opens. ## Finland — Data Agent (import) | | | |---|---| | Endpoint | _published when the endpoint opens_ | | Transport | Streamable HTTP | | Authentication | _published when it opens_ | | Status | [Coming soon] | Bring payroll data in from other systems: import plans, source datasets, transformations and import runs. Demo and production endpoints are published when it opens. ## Sweden | | | |---|---| | Endpoint | _published when the endpoint opens_ | | Transport | Streamable HTTP | | Authentication | _published when it opens_ | | Status | [Coming soon] | Separate endpoints for Swedish payroll. Published at launch. ## Areas without a tool yet These skill areas are written, and their tools are being built. On a server without the tool an agent using the skills **says it cannot do that here**, names what should happen instead, and does not substitute another tool. It does not claim the action is impossible: the limit may be the environment's, not Salaxy's. - [Company settings](https://code.salaxy.com/reference/skills.md#settings) — The tools come with the Configuration Agent server. --- Source: https://code.salaxy.com/reference/skills.md # Skills reference Skills are Markdown instructions an agent loads **before** calling the tools: when to call which tool, how to build its input, and when **not** to calculate at all. The tools say *what* can be done; the skills say *how to do it correctly*. - Source: [github.com/salaxy-payroll/salaxy-ai-for-payroll](https://github.com/salaxy-payroll/salaxy-ai-for-payroll) · root router `skills/SKILL.md` — **the repository opens publicly soon**; until then the links below need access - Content language: **Finnish for now, moving to English**. Identifiers, field names and enum values are already English, as in the API. - Country: **Finland**. Each country gets its own skill set — Finnish wage types and law do not carry over. | Area | Status | Tools | Evals | |---|---|---|---| | [Payroll process](#payroll-process) | [Knowledge only] | — | 2 / 2 pass | | [Calculations](#calculations) | [Live] | `calculation_preview`, `calculation_create`, `calculation_set_rows`, `calculation_update`, `calculation_get_summary`, `calculation_show_slip`, `calculation_copy`, `calculation_search`, `row_type_list` | 35 / 37 pass | | [Employments](#employments) | [Live] | `employment_search`, `employment_get_summary`, `employment_create`, `employment_update`, `employment_set_rows` | 3 / 3 pass | | [Payrolls](#payrolls) | [Live] | `payroll_create`, `payroll_copy`, `payroll_set_employments`, `payroll_set_rows`, `payroll_update`, `payroll_remove_calculation`, `payroll_get_summary`, `payroll_show_slips`, `payroll_search` | 1 / 1 pass | | [Invoices](#invoices) | [Live] | `invoice_search`, `invoice_get_summary`, `invoice_preview`, `invoice_confirm` | 1 / 1 pass | | [Reports](#reports) | [Live] | `salary_slip`, `salary_slip_pdf`, `summary_report`, `salary_summary`, `accounting_report`, `holiday_pay_debt`, `ir_reports`, `ir_report` | 0 / 2 pass | | [Company settings](#settings) | [Coming soon] | — | 0 / 1 pass | | [Absences](#absences) | [Live] | `absence_search`, `absence_get_summary`, `absence_set_periods` | 1 / 1 pass | | [Holidays](#holidays) | [Live] | `holiday_spec_get_summary`, `holiday_spec_update`, `holiday_year_create`, `holiday_year_search`, `holiday_year_get_summary`, `holiday_year_set_accruals`, `holiday_year_set_leaves`, `holiday_year_update`, `holiday_year_recalculate` | 1 / 1 pass | ## Payroll process [Knowledge only] The whole flow: how payrolls, calculations and invoices relate and in what order they proceed, which skill handles which step, how settings are inherited, where accounting data and reports come from, and what Salaxy's terms mean. Builds nothing. - Skill: [`skills/fi/payroll-process/SKILL.md`](https://github.com/salaxy-payroll/salaxy-ai-for-payroll/blob/feature/multi-country/skills/fi/payroll-process/SKILL.md) - Tools: none - Reference files: 4 - Eval cases: [2](https://code.salaxy.com/reference/verified.md#payroll-process) **Skill description as the agent sees it (Finnish)** > Palkanmaksun kokonaisprosessi Salaxyssä: miten palkkalista, palkkalaskelma ja laskut liittyvät toisiinsa, missä järjestyksessä ne etenevät ja mikä skilli mitäkin vaihetta hoitaa. Käytä tätä, kun kysymys koskee prosessia tai kokonaisuutta eikä yhden laskelman rakentamista. Triggeröi sanoista: palkanmaksuprosessi, mitä tapahtuu seuraavaksi, missä tilassa, miksi laskelmaa ei voi muuttaa, miten palkka päätyy maksuun, asetusten periytyminen, mistä laskelman tiedot tulevat, työntekijä vs. työsuhde, missä järjestyksessä asiat perustetaan, kirjanpitoaineisto ja raportit, Salaxyn termien merkitykset. ## Calculations [Live] Create or change a salary calculation: employment, pay period, salary date and wage-type rows, with a catalogue of Finnish wage types and Incomes Register income types. - Skill: [`skills/fi/calculations/SKILL.md`](https://github.com/salaxy-payroll/salaxy-ai-for-payroll/blob/feature/multi-country/skills/fi/calculations/SKILL.md) - Tools: [`calculation_preview`](https://code.salaxy.com/reference/mcp.md#calculation_preview) [Live], [`calculation_create`](https://code.salaxy.com/reference/mcp.md#calculation_create) [Live], [`calculation_set_rows`](https://code.salaxy.com/reference/mcp.md#calculation_set_rows) [Live], [`calculation_update`](https://code.salaxy.com/reference/mcp.md#calculation_update) [Live], [`calculation_get_summary`](https://code.salaxy.com/reference/mcp.md#calculation_get_summary) [Live], [`calculation_show_slip`](https://code.salaxy.com/reference/mcp.md#calculation_show_slip) [Live], [`calculation_copy`](https://code.salaxy.com/reference/mcp.md#calculation_copy) [Live], [`calculation_search`](https://code.salaxy.com/reference/mcp.md#calculation_search) [Live], [`row_type_list`](https://code.salaxy.com/reference/mcp.md#row_type_list) [Live] - Reference files: 72 - Eval cases: [37](https://code.salaxy.com/reference/verified.md#calculations) **Skill description as the agent sees it (Finnish)** > Palkkalaskelman luonti tai muuttaminen: työsuhde, palkkakausi, palkkapäivä ja palkkalajirivit. Käytä tätä skilliä, kun haluat luoda palkkalaskelman tai muuttaa palkkalaskelmaa. Triggeröi sanoista: palkkalaskelman luonti, palkkalaskelman muuttaminen, palkkalaskelman rivit, palkkalajit, tulolajit, palkkakausi, palkkapäivä. ## Employments [Live] Create, find, change and end employments — the relation that carries the payroll terms: pay type, pension type, tax card type and default rows. There is no calculation without one. - Skill: [`skills/fi/employments/SKILL.md`](https://github.com/salaxy-payroll/salaxy-ai-for-payroll/blob/feature/multi-country/skills/fi/employments/SKILL.md) - Tools: [`employment_search`](https://code.salaxy.com/reference/mcp.md#employment_search) [Live], [`employment_get_summary`](https://code.salaxy.com/reference/mcp.md#employment_get_summary) [Live], [`employment_create`](https://code.salaxy.com/reference/mcp.md#employment_create) [Live], [`employment_update`](https://code.salaxy.com/reference/mcp.md#employment_update) [Live], [`employment_set_rows`](https://code.salaxy.com/reference/mcp.md#employment_set_rows) [Live] - Reference files: 4 - Eval cases: [3](https://code.salaxy.com/reference/verified.md#employments) **Skill description as the agent sees it (Finnish)** > Työsuhteen luonti, muuttaminen, hakeminen ja päättäminen Salaxyn rajapinnassa. Työsuhde on se, joka kantaa palkanlaskennan ehdot — palkkausmuodon, eläkelajin, verokortin tyypin ja oletuspalkkarivit — ja ilman sitä ei voi tehdä laskelmaa. Triggeröi sanoista: työsuhteen luonti, työntekijän lisääminen, työsuhteen muuttaminen, työsuhteen päättäminen, työntekijän tietojen haku. ## Payrolls [Live] A payroll bundles one calculation per employee and is what goes to payment: statuses, conditions for payment, partial payment, invoices created from a payroll, and recurring payrolls. Calculation rows are in Calculations. - Skill: [`skills/fi/payrolls/SKILL.md`](https://github.com/salaxy-payroll/salaxy-ai-for-payroll/blob/feature/multi-country/skills/fi/payrolls/SKILL.md) - Tools: [`payroll_create`](https://code.salaxy.com/reference/mcp.md#payroll_create) [Live], [`payroll_copy`](https://code.salaxy.com/reference/mcp.md#payroll_copy) [Live], [`payroll_set_employments`](https://code.salaxy.com/reference/mcp.md#payroll_set_employments) [Live], [`payroll_set_rows`](https://code.salaxy.com/reference/mcp.md#payroll_set_rows) [Live], [`payroll_update`](https://code.salaxy.com/reference/mcp.md#payroll_update) [Live], [`payroll_remove_calculation`](https://code.salaxy.com/reference/mcp.md#payroll_remove_calculation) [Live], [`payroll_get_summary`](https://code.salaxy.com/reference/mcp.md#payroll_get_summary) [Live], [`payroll_show_slips`](https://code.salaxy.com/reference/mcp.md#payroll_show_slips) [Live], [`payroll_search`](https://code.salaxy.com/reference/mcp.md#payroll_search) [Live] - Eval cases: [1](https://code.salaxy.com/reference/verified.md#payrolls) **Skill description as the agent sees it (Finnish)** > Palkkalista: laskelmien nippu ja sen vieminen maksuun. Tilat, maksuun viemisen ehdot ja osittainen maksuun vienti. **Ei laskelman rivejä** — ne ovat calculations-skilissä. Triggeröi sanoista: palkkalista, palkka-ajo, maksuun vienti, laskujen luonti palkkalistalta, toistuva palkkalista. ## Invoices [Live] For partners who pay through their own channel: fetch invoices, report their status back and build SEPA payment files. Paying is two-step — preview, a person approves, confirm — and a confirmation is never invented. The process and the meaning of the statuses are in Payroll process. - Skill: [`skills/fi/invoices/SKILL.md`](https://github.com/salaxy-payroll/salaxy-ai-for-payroll/blob/feature/multi-country/skills/fi/invoices/SKILL.md) - Tools: [`invoice_search`](https://code.salaxy.com/reference/mcp.md#invoice_search) [Live], [`invoice_get_summary`](https://code.salaxy.com/reference/mcp.md#invoice_get_summary) [Live], [`invoice_preview`](https://code.salaxy.com/reference/mcp.md#invoice_preview) [Live], [`invoice_confirm`](https://code.salaxy.com/reference/mcp.md#invoice_confirm) [Live] - Eval cases: [1](https://code.salaxy.com/reference/verified.md#invoices) **Skill description as the agent sees it (Finnish)** > Laskujen hakeminen maksukanavalta, niiden tilan päivittäminen takaisin ja SEPA-maksuaineiston muodostaminen. Kumppanikehittäjän rajapintaohje — **prosessin kulku ja tilojen merkitys ovat payroll-process-skilissä**. Triggeröi sanoista: laskun haku, laskujen listaus, laskun tilan päivitys, maksuaineisto, SEPA, erätunniste. ## Reports [Live] Turn a calculation into a readable document — exactly three types: salary slip, e-payslip material (XML) and the employer report. Only Finnish works. - Skill: [`skills/fi/reports/SKILL.md`](https://github.com/salaxy-payroll/salaxy-ai-for-payroll/blob/feature/multi-country/skills/fi/reports/SKILL.md) - Tools: [`salary_slip`](https://code.salaxy.com/reference/mcp.md#salary_slip) [Live], [`salary_slip_pdf`](https://code.salaxy.com/reference/mcp.md#salary_slip_pdf) [Live], [`summary_report`](https://code.salaxy.com/reference/mcp.md#summary_report) [Live], [`salary_summary`](https://code.salaxy.com/reference/mcp.md#salary_summary) [Live], [`accounting_report`](https://code.salaxy.com/reference/mcp.md#accounting_report) [Live], [`holiday_pay_debt`](https://code.salaxy.com/reference/mcp.md#holiday_pay_debt) [Live], [`ir_reports`](https://code.salaxy.com/reference/mcp.md#ir_reports) [Live], [`ir_report`](https://code.salaxy.com/reference/mcp.md#ir_report) [Live] - Eval cases: [2](https://code.salaxy.com/reference/verified.md#reports) **Skill description as the agent sees it (Finnish)** > Laskelman muuttaminen luettavaksi dokumentiksi: palkkalaskelma, verkkopalkka- aineisto ja työnantajan raportti. Käytä tätä skilliä, kun käyttäjä haluaa nähdä tai lähettää valmiin laskelman tulosteena eikä pelkkiä lukuja. Triggeröi sanoista: palkkalaskelma, palkkakuitti, tuloste, raportti, verkkopalkka, työnantajan raportti, näytä laskelma. ## Company settings [Coming soon] Company settings: bank account and SEPA id, pension contracts, cost-centre dimensions and language. Saving replaces the whole object — a partial save wipes the other sections. > The tools come with the Configuration Agent server. - Skill: [`skills/fi/settings/SKILL.md`](https://github.com/salaxy-payroll/salaxy-ai-for-payroll/blob/feature/multi-country/skills/fi/settings/SKILL.md) - Tools: none - Eval cases: [1](https://code.salaxy.com/reference/verified.md#settings) **Skill description as the agent sees it (Finnish)** > Yrityksen asetukset Salaxyn rajapinnassa: pankkitili ja SEPA-tunnus, eläkesopimukset, kustannuspaikkaulottuvuudet ja kieli. Ennen kaikkea se, että asetusten tallennus **korvaa koko objektin** eikä yhdistä — osittainen lähetys pyyhkii muut osiot. Käytä tätä, kun kysymys koskee yrityksen asetuksia. Triggeröi sanoista: asetusten muuttaminen, pankkitili, IBAN, SEPA-tunnus, eläkesopimus, eläkevakuutusyhtiö, vakuutussopimus, kustannuspaikka, dimensio, yrityksen kieli. ## Absences [Live] The absence calendar stored on an employment: absence periods and their fields, absence reports, lay-off notices, and how absences relate to the calculation. Absence rows themselves are in Calculations. - Skill: [`skills/fi/absences/SKILL.md`](https://github.com/salaxy-payroll/salaxy-ai-for-payroll/blob/feature/multi-country/skills/fi/absences/SKILL.md) - Tools: [`absence_search`](https://code.salaxy.com/reference/mcp.md#absence_search) [Live], [`absence_get_summary`](https://code.salaxy.com/reference/mcp.md#absence_get_summary) [Live], [`absence_set_periods`](https://code.salaxy.com/reference/mcp.md#absence_set_periods) [Live] - Eval cases: [1](https://code.salaxy.com/reference/verified.md#absences) **Skill description as the agent sees it (Finnish)** > Poissaolokalenteri: työsuhteelle tallennetut poissaolojaksot, niiden kentät ja suhde palkkalaskelmaan. **Ei poissaoloriviä laskelmalle** — se on calculations-skilissä. Triggeröi sanoista: poissaolokalenteri, poissaolojakso, poissaolojen kirjaaminen, poissaoloraportti, lomautusilmoitus. ## Holidays [Live] Holiday accounting: accrual, entitlement, holiday calculation settings, and exceptions such as falling ill during a holiday or saved leave. Holiday pay rows themselves are in Calculations. - Skill: [`skills/fi/holidays/SKILL.md`](https://github.com/salaxy-payroll/salaxy-ai-for-payroll/blob/feature/multi-country/skills/fi/holidays/SKILL.md) - Tools: [`holiday_spec_get_summary`](https://code.salaxy.com/reference/mcp.md#holiday_spec_get_summary) [Live], [`holiday_spec_update`](https://code.salaxy.com/reference/mcp.md#holiday_spec_update) [Live], [`holiday_year_create`](https://code.salaxy.com/reference/mcp.md#holiday_year_create) [Live], [`holiday_year_search`](https://code.salaxy.com/reference/mcp.md#holiday_year_search) [Live], [`holiday_year_get_summary`](https://code.salaxy.com/reference/mcp.md#holiday_year_get_summary) [Live], [`holiday_year_set_accruals`](https://code.salaxy.com/reference/mcp.md#holiday_year_set_accruals) [Live], [`holiday_year_set_leaves`](https://code.salaxy.com/reference/mcp.md#holiday_year_set_leaves) [Live], [`holiday_year_update`](https://code.salaxy.com/reference/mcp.md#holiday_year_update) [Live], [`holiday_year_recalculate`](https://code.salaxy.com/reference/mcp.md#holiday_year_recalculate) [Live] - Eval cases: [1](https://code.salaxy.com/reference/verified.md#holidays) **Skill description as the agent sees it (Finnish)** > Lomakirjanpito: lomaoikeuden kertyminen, lomalaskennan asetukset ja se, mitä lomalle tapahtuu poikkeustilanteissa. **Ei loma-ajan palkan riviä** — rivit ovat calculations-skilissä. Triggeröi sanoista: lomakertymä, lomaoikeus, lomanmääräytymisvuosi, lomakausi, lomalaskennan asetukset, säästövapaa, sairastuminen lomalla. --- Source: https://code.salaxy.com/reference/verified.md # Verified coverage Each case below drives a headless agent with **only the skills and the MCP tools**, gives it a free-form request (in Finnish), and checks what it did — deterministically, with no LLM judge. A wage type or flow with no case here is a **promise we have not made yet**. **Last full run:** 2026-10-16 — **44 passed, 5 failed, 0 skipped** of 49. **What this verifies — and what it does not:** The suite runs the skills with **Salaxy's reference agent instructions**. Your own agent with your own system prompt is a different configuration: the skills are written to stand on their own, but this suite does not cover your prompt. Run the same cases against your agent — see [Build your own agent](https://code.salaxy.com/get-started/agentic/build-your-agent.md). | Case type | Meaning | |---|---| | Builds rows | The calculation must contain the expected wage-type rows | | Refuses / no call | The correct outcome is to **not** calculate, or to say there is no tool — and not substitute another | | Renders report | A finished calculation is turned into the expected document | | Checks result | Specific result fields must match | | Checks tool order | The agent must call the tools in the expected order — e.g. look up before it changes anything | ## Payroll process | Case | Type | Wage types | Result | |---|---|---|---| | `status-question-needs-no-call` | Refuses / no call | | ✅ pass | | `sweden-is-not-this-tree` | Refuses / no call | | ✅ pass | ## Calculations | Case | Type | Wage types | Result | |---|---|---|---| | `absenceperiod-childcare-month` | Builds rows | `absencePeriod` | ✅ pass | | `absenceperiod-sickleave` | Builds rows | `absencePeriod` | ✅ pass | | `accomodationbenefit-spelling` | Builds rows | `accomodationBenefit` | ✅ pass | | `advance-deducted-from-net` | Builds rows | `monthlySalary`, `advance` | ✅ pass | | `board-no-social-insurance` | Builds rows | `board` | ✅ pass | | `carbenefit-agegroup` | Builds rows | `carBenefit` | ✅ pass | | `chainsawreduction-before-withholding` | Builds rows | `monthlySalary`, `chainsawReduction` | ✅ pass | | `childcaresubsidy-socialbase-only` | Builds rows | `monthlySalary`, `childCareSubsidy` | ✅ pass | | `compensation-no-social-insurance` | Builds rows | `compensation` | ✅ pass | | `dailyallowance-country` | Builds rows | `dailyAllowance` | ✅ pass | | `dailyallowancehalf-two-days` | Builds rows | `monthlySalary`, `dailyAllowanceHalf` | ✅ pass | | `expenses-vat` | Builds rows | `expenses` | ✅ pass | | `foreclosure-fixed` | Builds rows | `monthlySalary`, `foreclosure` | ✅ pass | | `holidaycompensation-percent` | Builds rows | `holidayCompensation` | ✅ pass | | `hourlysalary-basic` | Builds rows | `hourlySalary` | ✅ pass | | `mealbenefit-deduction` | Builds rows | `mealBenefit` | ✅ pass | | `mealcompensation-2026` | Builds rows | `mealCompensation` | ✅ pass | | `milage-2024` | Builds rows | `milageOwnCar` | ❌ fail | | `milage-2026` | Builds rows | `milageOwnCar` | ✅ pass | | `milage-basic` | Builds rows | `milageOwnCar` | ❌ fail | | `monthlysalary-basic` | Builds rows | `monthlySalary` | ✅ pass | | `otherbenefit-raises-taxable-not-cash` | Builds rows | `monthlySalary`, `otherBenefit` | ✅ pass | | `overtime-percent` | Builds rows | `overtime` | ✅ pass | | `paidsickleave-kind-required` | Builds rows | `paidSickLeave` | ✅ pass | | `phonebenefit-months` | Builds rows | `phoneBenefit` | ✅ pass | | `refuse-missing-amount` | Refuses / no call | | ✅ pass | | `refuse-public-sector-payer` | Refuses / no call | | ✅ pass | | `refuse-work-abroad` | Refuses / no call | | ✅ pass | | `salary-piecework` | Builds rows | `salary` | ✅ pass | | `sundaywork-quantity` | Builds rows | `sundayWork` | ✅ pass | | `taxwithholding-row` | Builds rows | `taxWithholding` | ✅ pass | | `timeratepay-military` | Builds rows | `timeRatePay` | ✅ pass | | `toolcompensation-taxfree` | Builds rows | `monthlySalary`, `toolCompensation` | ✅ pass | | `totalworkerpayment-net` | Builds rows | `totalWorkerPayment` | ✅ pass | | `training-kind-required` | Builds rows | `training` | ✅ pass | | `unionpayment-fixed` | Builds rows | `monthlySalary`, `unionPayment` | ✅ pass | | `unionpayment-percent-limits` | Builds rows | `monthlySalary`, `unionPayment` | ✅ pass | ## Employments | Case | Type | Wage types | Result | |---|---|---|---| | `adult-has-unemployment` | Builds rows | `monthlySalary` | ✅ pass | | `resolve-employee-by-name` | Checks tool order | `monthlySalary` | ✅ pass | | `underage-no-unemployment` | Builds rows | `monthlySalary` | ✅ pass | ## Payrolls | Case | Type | Wage types | Result | |---|---|---|---| | `payrolls-has-no-tool` | Refuses / no call | | ✅ pass | ## Invoices | Case | Type | Wage types | Result | |---|---|---|---| | `invoices-has-no-tool` | Refuses / no call | | ✅ pass | ## Reports | Case | Type | Wage types | Result | |---|---|---|---| | `employer-report-type` | Renders report | `monthlySalary` | ❌ fail | | `salaryslip-is-lowercase` | Renders report | `monthlySalary` | ❌ fail | ## Company settings | Case | Type | Wage types | Result | |---|---|---|---| | `settings-has-no-tool` | Refuses / no call | | ❌ fail | ## Absences | Case | Type | Wage types | Result | |---|---|---|---| | `absences-has-no-tool` | Refuses / no call | | ✅ pass | ## Holidays | Case | Type | Wage types | Result | |---|---|---|---| | `holidays-has-no-tool` | Refuses / no call | | ✅ pass | Hover a case name to see the prompt the agent was given. --- Source: https://code.salaxy.com/reference/rest-api.md # REST API reference [Finland] The API is **Finland only**; other countries launch on [MCP](https://code.salaxy.com/reference/mcp.md). Hosts for test, demo and production: [Environments](https://code.salaxy.com/get-started/environments.md). **Start on v03.** Salaxy API v03 is the current version. Salaxy API v04 is in beta: it may change, and it is not used in production yet. Build on v03, the current version. [Reference for v04 (beta)](https://code.salaxy.com/reference/rest-api-v04.md). Version: **v03 (current)** · [v04 (beta)](https://code.salaxy.com/reference/rest-api-v04.md) **Agents and code generators:** read the OpenAPI document directly — [`/openapi/salaxy-03.json`](https://code.salaxy.com/openapi/salaxy-03.json) — rather than this rendered page. It is the same content, and about 1 MB of JSON is far cheaper to parse than this UI. The interactive reference is rendered from the OpenAPI document: https://code.salaxy.com/openapi/salaxy-03.json **The API rules every call follows** (also in the reference's Introduction): - **REST authentication** — How to get an access token for the Salaxy REST API (Finland) — which flow fits which integration, and how tokens work. [Full page](https://code.salaxy.com/security/rest-authentication.md) - **Errors** — How the Salaxy REST API reports failures — one JSON error shape, a few HTTP statuses, no stable error codes. Branch on the status, not the message. [Full page](https://code.salaxy.com/reference/errors.md) - **Queries and paging** — OData-style queries on Salaxy REST list endpoints — $filter, $search, $orderby, and paging with nextPageLink. Avoid $top. [Full page](https://code.salaxy.com/reference/queries.md) - **Retries and idempotency** — How to make retried requests safe with the Salaxy REST API — no general idempotency key; use your own ids and look before you create. [Full page](https://code.salaxy.com/reference/idempotency.md) - **Events and polling** — The Salaxy REST API has no webhooks or push notifications today — poll the read endpoints. What to poll, and how often. [Full page](https://code.salaxy.com/reference/polling.md) - **Versions and changes** — Which Salaxy REST API version to build on, how v04 differs from v03, how to move one area at a time, and what changed in the v03 reference recently. [Full page](https://code.salaxy.com/reference/versions.md) --- Source: https://code.salaxy.com/reference/rest-api-v04.md # REST API reference v04 [Beta] **Warning:** Salaxy API v04 is in beta: it may change, and it is not used in production yet. Build on v03, the current version. Version: [v03 (current)](https://code.salaxy.com/reference/rest-api.md) · **v04 (beta)** The API is **Finland only**; other countries launch on [MCP](https://code.salaxy.com/reference/mcp.md). Hosts for test, demo and production: [Environments](https://code.salaxy.com/get-started/environments.md). **Agents and code generators:** read the OpenAPI document directly — [`/openapi/salaxy-04.json`](https://code.salaxy.com/openapi/salaxy-04.json) — rather than this rendered page. The interactive reference is rendered from the OpenAPI document: https://code.salaxy.com/openapi/salaxy-04.json **The API rules every call follows** (also in the reference's Introduction): - **REST authentication** — How to get an access token for the Salaxy REST API (Finland) — which flow fits which integration, and how tokens work. [Full page](https://code.salaxy.com/security/rest-authentication.md) - **Errors** — How the Salaxy REST API reports failures — one JSON error shape, a few HTTP statuses, no stable error codes. Branch on the status, not the message. [Full page](https://code.salaxy.com/reference/errors.md) - **Queries and paging** — OData-style queries on Salaxy REST list endpoints — $filter, $search, $orderby, and paging with nextPageLink. Avoid $top. [Full page](https://code.salaxy.com/reference/queries.md) - **Retries and idempotency** — How to make retried requests safe with the Salaxy REST API — no general idempotency key; use your own ids and look before you create. [Full page](https://code.salaxy.com/reference/idempotency.md) - **Events and polling** — The Salaxy REST API has no webhooks or push notifications today — poll the read endpoints. What to poll, and how often. [Full page](https://code.salaxy.com/reference/polling.md) - **Versions and changes** — Which Salaxy REST API version to build on, how v04 differs from v03, how to move one area at a time, and what changed in the v03 reference recently. [Full page](https://code.salaxy.com/reference/versions.md) --- Source: https://code.salaxy.com/get-started/white-label/index.md # Embedded white label: quick start [Finland] Embed the Salaxy payroll UI in your application with an iframe — with built-in navigation, in about five minutes. You embed a Salaxy single-page application (SPA) in an iframe and control it through its URL. You handle sign-in, layout and your application's own chrome; Salaxy handles the payroll logic, the payroll UI, compliance and maintenance. The bigger picture — what runs where and how a project goes — is in [How embedded white label works](https://code.salaxy.com/white-label/how-it-works.md). **Before you start:** - **A test account** in the test environment — see [1. Create an account](https://code.salaxy.com/get-started/rest/create-account.md). - **A web page you can edit** — a plain HTML file opened in the browser is enough. - Examples use the **test** hosts (`test-embed.palkkaus.fi`); see [Environments](https://code.salaxy.com/get-started/environments.md) for demo and production. ## The five-minute path 1. Get a test access token. 2. Paste the iframe example into a page. 3. Open the page and check that the payroll UI appears. If this works, you are most of the way there. ### 1. Get an access token The embedded UI needs an **access token** (a JWT) on its first load. While testing, get one with your test account's email and password — the password flow in [2. Authenticate](https://code.salaxy.com/get-started/rest/authenticate.md). In production, your backend gets it through your single sign-on: the [impersonation flow](https://code.salaxy.com/security/impersonation.md). - The token is needed **only on the first load** of the iframe. - It goes in the URL **hash**, not in a query parameter. - Salaxy issues and validates it; you do not need to read or change it. ### 2. Embed the iframe A minimal working example. This page includes Salaxy's built-in horizontal navigation, so there is no menu to build: ```html ``` ### 3. Read the URL The base URL selects the [environment](https://code.salaxy.com/get-started/environments.md) and the embed page; `?lang` and `?skin` are optional; the access token goes in the hash on the first load. The full contract — every parameter, the languages and iframe sizing — is in [URL parameters and sizing](https://code.salaxy.com/white-label/url-parameters.md). **Never change the part before the #:** After the first load, change only what comes after `#`. Changing anything before it restarts the SPA and ends the session. **Save for the next step:** - The **embed page** you chose — `embedded-horizontal.html` (built-in menu) or `embedded.html` (your own menu). See [Navigation](https://code.salaxy.com/white-label/navigation.md). - The **design name** in `?skin` — `palkkaus` in the example until your own design is ready. See [Designs](https://code.salaxy.com/white-label/designs.md). ## A full working example A complete, production-style example: [test-embed.palkkaus.fi/iframe-tester.html](https://test-embed.palkkaus.fi/iframe-tester.html). View the page source for the whole implementation: - plain HTML and JavaScript - handling the SPA load, with a loading indicator - session expiry - switching language and design - responsive navigation for mobile and desktop - the built-in horizontal navigation on and off ## Before going live - Token issuing through single sign-on is implemented ([impersonation flow](https://code.salaxy.com/security/impersonation.md)). - You have a strategy for renewing tokens — they last 48 hours and cannot be refreshed ([Tokens](https://code.salaxy.com/security/rest-authentication.md#tokens)). - The iframe height is handled. - Session expiry is handled in your UI. - Your design is final. ## What you built A payroll UI running inside your page, signed in with a token, with built-in navigation. Next: - [Navigation](https://code.salaxy.com/white-label/navigation.md) — keep the built-in menu, or render your own. - [Designs](https://code.salaxy.com/white-label/designs.md) — make the payroll UI look like your product. - [How embedded white label works](https://code.salaxy.com/white-label/how-it-works.md) — sign-in in production and how a project goes. --- Source: https://code.salaxy.com/white-label/index.md # Embedded white label [Finland] **Your brand. Your customers. Payroll taken care of.** Embedded white label is Salaxy's complete payroll software, **branded as yours** and embedded in your product's user experience. It comes as two products on the same Salaxy payroll platform, both with Salaxy AI agents built in: **Salaxy Business**, payroll for one company, embedded in financial management software, online banks and ERPs; and **Salaxy Pro**, payroll for many companies, for accounting firms and payroll outsourcing. You bring the customers and the context; Salaxy runs the payroll — calculation, payments, Incomes Register and pension reporting, accounting data — and keeps developing it. It is the fastest route to a full payroll offering when you do not want to build a payroll UI yourself. Available in **Finland**; for other countries it is not yet decided. **Developers:** see [How white label works](https://code.salaxy.com/white-label/how-it-works.md) — what runs where, how sign-in works, what you build and what Salaxy provides, and how a project goes. ## Two products ### Salaxy Business Payroll for one company, embedded in your product: financial management software, an online bank or an ERP. Your customers run their own payroll in it, and it can be fully branded to your requirements. The Payroll Agent is built in; more agents are coming. Over **30,000 companies** trust Salaxy for their payroll. The same software, branded three ways: ![Salaxy Business, branded as Palkkaus.fi](https://code.salaxy.com/white-label/palkkaus-fi.webp) ![The same payroll software branded for Aallon](https://code.salaxy.com/white-label/aallon.webp) ![The same payroll software branded for Lemon Tree's Lemon Aid](https://code.salaxy.com/white-label/lemon-aid.webp) ### Salaxy Pro Payroll for many companies: for accounting firms, payroll outsourcing companies and payroll managers. Under your brand, as your own payroll service or embedded in your team's software. - **All customers in one view:** tasks, pay dates and late items across every customer. - **All payroll functionality:** employments, payrolls, payments, employer reporting and accounting data, customer by customer. - **All three Salaxy AI agents built in:** the Data Agent, the Verification Agent and the Payroll Agent work in the side panel ([Salaxy AI agents on salaxy.com](https://www.salaxy.com/ai#agents)). ![Salaxy Pro To do view: tasks, pay dates and notes for all customers, with the agent panel open on the right](https://code.salaxy.com/white-label/salaxy-pro.png) ## Why white label ### Ready out of the box All the payroll functionality your customers need is ready, with no in-house development. The user interface — navigation, colours, logo — follows your design: **Salaxy implements your visual design** in the payroll UI as part of the partnership, so your users never leave your product. Prototyping and testing are fast, with no long integration project. ### Always compliant and secure We keep payroll up to date with legislation, so every calculation and report follows the current rules. Your customers' data is hosted in the EU and handled under GDPR. ### Transparent pricing You decide your customer pricing. We charge your solution per handled payslip — no additional fees and no cryptic price lists. ## What partners say > "Salaxy Payroll made it possible for us to provide salary payment easily in our solution." > > — Jukka Kivistö, CEO, Saarni Nepton > "An AI-assisted payroll agent takes payroll in Easor App to a new level and saves entrepreneurs' time." > > — Otto-Pekka Huhtala, CEO, Easor Oyj (translated from Finnish) > "Light years ahead of Mepco! We save several days of work each month." > > — Mikko Saari, COO, Holsti Forest ## White label in use | Solution | Use | |---|---| | Nepton Palkat | Working time with payroll embedded | | Easor App | Financial management for SMEs | | Easoft ERP | ERP with built-in payroll | | Visma Hausvise | Payroll for property management | | Procountor Solo | SME financial management | | Holvi | Business account for SMEs | Read the customer stories on [salaxy.com](https://www.salaxy.com/customers). ## White label, MCP or REST? The three work together. White label gives your users a complete payroll UI; the [REST API](https://code.salaxy.com/get-started/rest/index.md) handles what your own software does in the background, such as creating accounts; and the [MCP server](https://code.salaxy.com/get-started/agentic/index.md) lets an assistant in your product answer payroll questions and prepare calculations. See [MCP or REST?](https://code.salaxy.com/about/mcp-or-rest.md) ## For developers - [Quick start](https://code.salaxy.com/get-started/white-label/index.md) — the payroll UI running in your page in about five minutes. - [How embedded white label works](https://code.salaxy.com/white-label/how-it-works.md) — what runs where, sign-in, and how a project goes. - [Navigation](https://code.salaxy.com/white-label/navigation.md) · [URL parameters and sizing](https://code.salaxy.com/white-label/url-parameters.md) · [Designs](https://code.salaxy.com/white-label/designs.md) - [Embedded demo](https://code.salaxy.com/embedded-demo) — interactive, after sign-in; it stays on the current developer site. ## Get a demo Tell us about your solution and we will show you what Salaxy can do: [request a demo on salaxy.com](https://www.salaxy.com/white-label). --- Source: https://code.salaxy.com/white-label/how-it-works.md # How embedded white label works [Finland] **Draft:** A first technical overview, drawn from the white label and security guides of the current developer site. The step-by-step guides are now on this site (see the end of the page). Embedded white label puts **Salaxy's payroll UI** — a single-page application — in an **iframe** inside your product. You keep your product, your navigation and your users' sign-in; Salaxy runs the payroll. It has been used in production since 2018, on desktop and mobile browsers and in mobile apps through web views. ## What runs where *Diagram: Your web app shows the Salaxy payroll UI in an iframe. Your backend signs the user in and gets a Salaxy access token with a signed JWT. The iframe loads the payroll application from embed.palkkaus.fi with the token in the URL hash and calls the Salaxy API. (Purple: provided and run by Salaxy. Grey: built and run by you. Dashed: optional.)* 1. **The user signs in to your product** — with your own login. Your users do not sign in to Salaxy separately. 2. **Your backend asks Salaxy for a token for that user.** It signs a short-lived JWT with the certificate you created in Salaxy and posts it to the Salaxy token endpoint — the [impersonation flow for single sign-on](https://code.salaxy.com/security/impersonation.md). Salaxy only accepts it if the user's account has authorised your product. 3. **Salaxy returns a short-lived user access token.** There are no refresh tokens: when it expires, repeat step 2. 4. **Your page puts the token into the iframe's URL**, in the **hash** (`#access_token=…`), on the first load only. 5. **The iframe loads the payroll application** and your design from `embed.palkkaus.fi` (`test-embed.` and `demo-embed.` for testing — see [Environments](https://code.salaxy.com/get-started/environments.md)). The design is selected with the `skin` URL parameter or, without it, by the company's [service model](https://code.salaxy.com/integration/service-models.md). 6. **The payroll UI calls the Salaxy API** with the token. Payroll logic, payments, Incomes Register and pension reporting all happen on Salaxy's side. 7. **Optional:** your backend uses the REST API for what happens outside the UI — creating customer accounts from your system, taking payments through your own payment channel, fetching accounting data. **Navigation** is client-side routing inside the iframe. Either embed `embedded-horizontal.html`, which has Salaxy's own menu, or embed `embedded.html` and drive it from your own menu by changing only the part after `#` (for example `#/payroll`). Changing anything before the `#` reloads the application and ends the session. ## What you build and what Salaxy provides | You build | Salaxy provides | |---|---| | Your product, its header, menu and footer | The payroll UI, kept up to date — new features arrive without work on your side | | Your users' sign-in | Payroll logic and compliance: tax, insurance, Incomes Register, pensions | | Token issuing in your backend (signed JWT → access token) | The token endpoint; you create your certificate in the Salaxy web application | | The page that hosts the iframe: sizing, loading indicator, session-expiry handling | Hosting of the payroll application on test, demo and production hosts | | Your navigation choice — Salaxy's built-in menu or your own | **Your design implemented in the payroll UI** — colours, logo, fonts — from your visual design, as part of the partnership | | Optional REST integrations: account creation, payment channel, accounting data | The REST API and the payroll engine behind it | **What you do not do:** access the iframe's contents, change Salaxy's internal routing, or implement payroll logic yourself. If you need deep UI changes beyond the design, or control over the payroll components themselves, white label is the wrong fit — use the [REST API](https://code.salaxy.com/get-started/rest/index.md) and build your own UI, or the [MCP server](https://code.salaxy.com/get-started/agentic/index.md) for an agent. ## How a white label project goes *Diagram: Six phases: agree, test set-up, build, design, integrate (optional), go live. (Purple: done together with Salaxy. Grey: your development work. Dashed: optional.)* | Phase | What happens | Technical outcome | |---|---|---| | **1. Agree** | Commercial terms (per-payslip pricing), the data processing agreement, scope: which payroll features your users get | Agreement; test access | | **2. Test set-up** | Get a test account and create your certificate. Embed `test-embed.palkkaus.fi` with a test token — the five-minute proof of life | The payroll UI running inside your page | | **3. Build** | Token issuing in your backend (step 2 above); the hosting page with sizing, loading and session-expiry handling; your navigation choice | Your users reach payroll through your own sign-in | | **4. Design** | You provide your visual design; **Salaxy implements it** in the payroll UI (the *design*, formerly called the *skin*) — included in the partnership and its integration support | The payroll UI looks like your product | | **5. Integrate** *(optional)* | REST API integrations: creating accounts from your system, your own payment channel, accounting data | Payroll connected to the rest of your product | | **6. Go live** | Production checklist: token issuing, token renewal, iframe height, session-expiry UX, final design. Switch to `embed.palkkaus.fi` | Live for your customers | ## Availability Embedded white label is available in **Finland**. For other countries it is not yet decided — they launch on [MCP and skills](https://code.salaxy.com/countries/index.md). ## Technical guides - [Quick start](https://code.salaxy.com/get-started/white-label/index.md) — the five-minute proof of life - [Navigation](https://code.salaxy.com/white-label/navigation.md) — the built-in menu or your own - [URL parameters and sizing](https://code.salaxy.com/white-label/url-parameters.md) — the embed URL and the iframe height - [Designs](https://code.salaxy.com/white-label/designs.md) — your look in the payroll UI (formerly *skins*) - [Impersonation flow for SSO](https://code.salaxy.com/security/impersonation.md) · [Partner-initiated account creation](https://code.salaxy.com/security/account-creation.md) - Working example: [iframe tester](https://test-embed.palkkaus.fi/iframe-tester.html) · interactive [embedded demo](https://code.salaxy.com/embedded-demo) (current developer site, after sign-in) --- Source: https://code.salaxy.com/white-label/navigation.md # Navigation [Finland] The embedded payroll UI supports two ways to navigate. Pick the one that fits your product: - **Built-in horizontal navigation** — the fastest to ship; there is no menu to build. The [quick start](https://code.salaxy.com/get-started/white-label/index.md) uses it. - **Your own navigation** — full control; the menu blends into your application. Examples use the test hosts and assume a session is already established. The URL contract is in [URL parameters and sizing](https://code.salaxy.com/white-label/url-parameters.md); getting the access token is in the [quick start](https://code.salaxy.com/get-started/white-label/index.md). ## Built-in horizontal navigation Embed `embedded-horizontal.html` and Salaxy renders a horizontal menu bar inside the iframe: ```html ``` The menu moves between the payroll views; your application's own header, footer and navigation around the embed stay yours. The URL contract is the same as for `embedded.html`: `?lang` and `?skin` behave the same, and the access token is needed only on the first load, in the `#access_token` hash. ## Your own navigation Embed `embedded.html` and render the menu yourself. Navigation is client-side routing inside the iframe — no page reloads. You: - give the iframe a `name`, - point your menu links at it with `target="