Skip to content

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 for demo and production.

The invoice loopSalaxy 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.Invoicestatus unreadFetchunread onesMark readstored by youPayin your bankReport paidwith the dateClosedsalary paidCannot pay in time?Report canceled. The salary returns to draft;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; reading the outcome from the calculation side is in Track the payment status. Committing is in Set for payment.

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.

One channel: how it works

Use the payment-channel endpoints. {channel} is the channel code provisioned for you.

MethodPathPurpose
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-statusReports status changes in a batch
GET/v03/api/payment-channel/{channel}/{id}/contentOne invoice as PDF. Optional inline
GET/v03/api/payment-channel/{channel}/content?ids=Several invoices as PDF
GET/v03/api/payment-channel/{channel}/{id}/accountingAccounting entries of an invoice, see Accounting data

SEPA payment files for the same invoices are fetched from /v03/api/payment-channel/{channel}/sepa; see Payment channels and SEPA payment files.

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
MethodPathPurpose
GET/v03/api/invoices?$filter=status eq 'unread'Unread invoices of this account; query syntax in Queries
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}/contentThe invoice as PDF
GET/v03/api/invoices/{id}/finvoiceThe 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.

The invoice object ​

json
{
  "id": "<invoice 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": ["<calculation id>"]
  },
  "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.
  • 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 <token>
Content-Type: application/json

[
  { "id": "<invoice id>", "status": "read" },
  { "id": "<invoice id>", "status": "paid", "date": "2026-03-31" }
]

Each item is an InvoiceStatusNotification. It names the invoice by id or by your own externalId:

FieldRequired?Notes
id / externalIdOne of themThe Salaxy invoice id, or your own key, see below
statusAlwaysread, paid or canceled
dateFor paidMust equal header.logicalDate. If omitted, Salaxy books today. Always send it
paymentTypeOptionaldefault, salary or salaryInPast. If your channel cannot use the requested type, report the one it used
referenceNumber, receiverFullName, receiverIban, receiverBicOptionalOverrides. 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; the monthly timing is in Monthly cycle.

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.

Test it ​

  1. Create a payroll and commit it with the palkkausManual channel as in Set for payment. 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

Every page is also available as Markdown: add .md to its URL — a folder page such as white-label/ is white-label/index.md. Index for LLMs: llms.txt. Questions: Support.