# 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": "<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](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 <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 `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)
