Skip to content

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 for demo and production. The running loop (fetch unpaid invoices, report their status) is on Invoices and payments; this page covers the choice, the set-up and the SEPA files.

A payment channel carries the invoices of a payroll to the payerA 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.Payrollcreates invoicesPayment channelchosen with SalaxyCustomer funds accountSalaxy pays the workersYour systemfetch, pay, report status back
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.
  • 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.
  • 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.
  • 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 below. Salaxy can also store the file as a payment message; see Payment messages (v04 beta).

Provisioning ​

StepWho
Create the channelSalaxy, with you verifying it
Make it available to your customersSalaxy, through a service model
Choose which customers use itYou, 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.

Endpoints ​

All paths are under /v03/api/payment-channel/{channel} (the same set exists under /v04/api/). The owner account calls them.

MethodPathPurpose
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-statusReport status changes, body is an array.
GET/{channel}/{id}/contentThe invoice PDF. /{channel}/content?ids=... for several.
GET/{channel}/{id}/calculationThe calculation behind a net invoice.
GET/{channel}/{id}/accountingAccounting data for a net invoice. See Accounting data.
GET, POST/{channel}/sepa, GET /{channel}/{id}/sepaSEPA file. See below.

The reference pages are PaymentChannel (v03) and PaymentChannel v04.

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.

MethodPathReturns
GET/v03/api/payment-channel/{channel}/{id}/sepaA 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}/sepaA 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.

ParameterMeaning
idsInvoice ids, repeated (ids=...&ids=...).
versionpain.001.001.02 (default) or pain.001.001.03.
payerIbanNumber, payerBic, bankPartyIdPayer bank details; bankPartyId depends on the bank.
inlinetrue 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.

MethodPathPurpose
POST/v04/api/payment-channel/{channel}/payment-messagesCreate from invoiceIds, or resend with parentMessageId. Optional Idempotency-Key header.
GET/v04/api/payment-channel/{channel}/payment-messagesList, 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}/sepaThe stored file.
GET/v04/api/payment-messages/settings/{channel}The company's allowed actions, split, format and file name.
POST, GET/v04/api/payment-messagesCreate, 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}/sepaThe 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.
  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

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.