Appearance
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.
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.
| 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 |
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
| Method | Path | Purpose |
|---|---|---|
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}/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.
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.typetells 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.logicalDateis the salary date.header.businessObjectslists the salary calculations the invoice is based on.header.externalIdholds your own key, if you stamped one.- A
taxinvoice 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
netandforeclosureinvoices fall due on the working day before the salary date, never earlier than today. Thetaxinvoice falls due on the 12th of the month after the salary month, theunioninvoice on the 15th, each moved to the next working day. logicalDateis the salary date only onnetandforeclosureinvoices. On ataxorunioninvoice it is the first day of the salary month.
The core loop
- Fetch.
GET /v03/api/payment-channel/{channel}/status/unread. Store what you get. - Mark read. Report
readfor each invoice you have stored, so it is not handled twice. - Pay. Pay in your bank or accounting system.
- Report paid. Report
paidwith 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:
| 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
200with[], 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.dateKindchooses which date the range filters on:invoiceDate,dueDateorlogicalDate. - Retries are safe. Re-sending an invoice's current status is accepted as a no-op.
- Stamp your own key. Send
externalIdwithidon the first update; it is stored and indexed, and later updates can name the invoice byexternalIdalone. AnexternalIdthat matches no invoice, or more than one, fails the whole batch, so keep it unique per invoice. - Which event means
paidis 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 reportingpaidfor a payment that later fails. Choose one and apply it consistently. paid.dateis the salary date, that isheader.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
netandgrosschanges reach the calculation. Reportingpaidon thenetinvoice closes the calculation; reportingcanceledon it returns the calculation topayrollDraft, or todraftif it is not in a payroll. A change on any other invoice type changes only that invoice: cancelling aforeclosureortaxinvoice does not change the calculation, so the salary carries on while that payment simply does not happen. To undo a salary, cancel thenetinvoice.
Cannot pay by the salary date?
Do not report paid with a later date. Instead:
- Cancel the payment in your system.
- Report
canceledfor the invoice. The calculation returns topayrollDraft(ordraft). - A user in the Company or Pro site corrects the salary date and commits the calculation again.
- A new invoice appears as
unreadwith the newlogicalDate.
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
contentendpoints 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 reportread,paidorcanceled. The endpoints, grouping, theSALAsalary flag and the one-payer rule are in Payment channels and SEPA payment files.
Test it
- Create a payroll and commit it with the
palkkausManualchannel as in Set for payment. Thenetinvoice appears asunread. - 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. - Report
read, thenpaidwithdateequal toheader.logicalDate. - Read the calculation with
GET /v03/api/calculations/{id}. Itsworkflow.statusshould bepaymentSucceeded. - Repeat with a second payroll and report
canceledon thenetinvoice instead. The calculation should be back atpayrollDraft. - Fetch with an old
startdate to see the 14-day window at work.
Checklist
- You fetch
unreadinvoices on a fixed interval and store them before you reportread. - Every
paidcarriesdateequal toheader.logicalDate. - You decided which event stands for
paid, and a failed or late payment is reportedcanceled. - Catch-up and reconciliation queries pass an explicit
startandend. - Retries re-send the same notification: they are safe. Your own
externalIdis unique per invoice. - You do not expect a fixed set of invoices per calculation.
Next: Accounting data

