Skip to content

PaymentChannel ​

Payment channels are methods that hanlde salary payments: Paytrail / Palkkaus.fi Customer funds account handling, Finvoice, Accounting software, Banks Web Services etc. This controller is for those channels to fetch Invoices and other data as well as to update payment feedback back to Palkkaus.fi. The services can only be used by registered payment channels: Ask us if you wish to register.

Salaxy API v03, Finland only. 23 operations. Interactive version: REST API reference. Machine-readable: OpenAPI document.

The reference wins

These pages are generated from the OpenAPI document. If a guide and this reference disagree about a field, follow the reference. Error responses are not in the document — see Errors.

GET /v03/api/payment-channel/{channel} ​

Returns list of invoices for the payment channel using OData query and search.

ParameterInTypeRequiredDescription
channelpathPaymentChannelyesPayment channel key.
$searchquerystring
$filterquerystringSpecifies the logic to pull back a subset of records.
$orderbyquerystringSpecifies the values used to sort the collection of entries.
$selectquerystringThe $select system query option allows the clients to requests a limited set of properties for each entry.
$topquerynumberSpecifies the subset of entries by count.
$skipquerynumberSpecifies the count of entries to skip.
$countquerybooleanIndicates whether or not to include a total entry count.

Response: PageResultOfInvoiceListItem

Try it: interactive reference

POST /v03/api/payment-channel/{channel} ​

Updates a single invoice in the payment channel. Please note this is valid only in the test environment, and only very restricted set of changes are allowed.

ParameterInTypeRequiredDescription
channelpathPaymentChannelyesPayment channel key.

Request body: Invoice (required)

Response: Invoice

Try it: interactive reference

GET /v03/api/payment-channel/{channel}/{id} ​

Gets a single invoice in the payment channel.

ParameterInTypeRequiredDescription
channelpathPaymentChannelyesPayment channel key.
idpathstringyesUnique identifier for the object

Response: Invoice

Try it: interactive reference

DELETE /v03/api/payment-channel/{channel}/{id} ​

Deletes an object from the storage

ParameterInTypeRequiredDescription
channelpathPaymentChannelyesPayment channel key.
idpathstringyesUnique identifier for the object.

Response: string

Try it: interactive reference

GET /v03/api/payment-channel/{channel}/{id}/content ​

Downloads the pdf file for the single invoice.

ParameterInTypeRequiredDescription
channelpathPaymentChannelyesPayment channel key.
idpathstringyesThe id of the invoice.
inlinequerybooleanIf true, returns the content as inline (disposition) in browser. If false, the content is returned as an attachment (download, default).

Response: OK

Try it: interactive reference

GET /v03/api/payment-channel/{channel}/content ​

Downloads the pdf file for the invoices.

ParameterInTypeRequiredDescription
channelpathPaymentChannelyesPayment channel key.
idsquerystring[]The ids of the invoices.
inlinequerybooleanIf true, returns the content as inline (disposition) in browser. If false, the content is returned as an attachment (download, default).

Response: OK

Try it: interactive reference

POST /v03/api/payment-channel/{channel}/content ​

Downloads the pdf file for the invoice.

ParameterInTypeRequiredDescription
channelpathPaymentChannelyes
inlinequerybooleanIf true, returns the content as inline (disposition). If false, the content is returned as an attachmnent.

Request body: Invoice (required)

Response: OK

Try it: interactive reference

GET /v03/api/payment-channel/{channel}/{id}/{type} ​

Downloads the calculation report pdf file for the single invoice. Please note that this is applicable only for net invoices.

ParameterInTypeRequiredDescription
channelpathPaymentChannelyesPayment channel key.
idpathstringyesThe id of the invoice.
typepathReportTypeyesCalculation report type. Currently only salarySlip, employerReport, paymentReport and accountingReport are supported.
inlinequerybooleanIf true, returns the content as inline (disposition) in browser. If false, the content is returned as an attachment (download, default).
isSensitivequerybooleanIf true, the pdf hides any personal ids of the worker.
targetquerystringAccounting target: contains ruleset for creating accounting entries. Can be null. Only for accounting reports.

Response: OK

Try it: interactive reference

GET /v03/api/payment-channel/{channel}/{type} ​

Downloads the calculation report pdf file for the invoice. Please note that this is applicable only for net invoices.

ParameterInTypeRequiredDescription
channelpathPaymentChannelyesPayment channel key.
idsquerystring[]The id of the invoice.
typepathReportTypeyesCalculation report type. Currently only salarySlip, employerReport, paymentReport and accountingReport are supported.
inlinequerybooleanIf true, returns the content as inline (disposition) in browser. If false, the content is returned as an attachment (download, default).
isSensitivequerybooleanIf true, the pdf hides any personal ids of the worker.
targetquerystringAccounting target: contains ruleset for creating accounting entries. Can be null. Only for accounting reports.

Response: OK

Try it: interactive reference

GET /v03/api/payment-channel/{channel}/{id}/accounting ​

Gets the accounting data based on calculation in a single net salary invoice. Please note that this is applicable only for net invoices. Please note that the accounting does not contain holiday accruals.

ParameterInTypeRequiredDescription
channelpathPaymentChannelyesPayment channel key.
idpathstringyesThe id of the invoice.
targetquerystringAccounting target: contains ruleset for creating accounting entries.

Response: AccountingData

Try it: interactive reference

GET /v03/api/payment-channel/{channel}/accounting ​

Gets the accounting data based on calculations in net salary invoices. Please note that this is applicable only for net invoices. Please note that the accounting does not contain holiday accruals.

ParameterInTypeRequiredDescription
channelpathPaymentChannelyesPayment channel key.
idsquerystring[]The ids of the invoices.
targetquerystringAccounting target: contains ruleset for creating accounting entries.

Response: AccountingData

Try it: interactive reference

GET /v03/api/payment-channel/{channel}/{id}/sepa ​

Downloads the sepa file for the single invoice.

ParameterInTypeRequiredDescription
channelpathPaymentChannelyes
idpathstringyesId of the invoice for the sepa payment.
payerIbanNumberquerystringPayer iban number.
payerBicquerystringPayer BIC.
bankPartyIdquerystringPayer bank party id. Depends on the bank.
inlinequerybooleanIf true, returns the content as inline (disposition). If false, the content is returned as an attachmnent.
versionquerystringISO 20022 version, pain.001.001.02 (default) or pain.001.001.03

Response: OK

Try it: interactive reference

GET /v03/api/payment-channel/{channel}/sepa ​

Downloads the sepa file for the given invoices.

ParameterInTypeRequiredDescription
channelpathPaymentChannelyes
idsquerystring[]Ids of the invoices for the sepa payment.
payerIbanNumberquerystringPayer iban number.
payerBicquerystringPayer BIC.
bankPartyIdquerystringPayer bank party id. Depends on the bank.
inlinequerybooleanIf true, returns the content as inline (disposition). If false, the content is returned as an attachmnent.
versionquerystringISO 20022 version, pain.001.001.02 (default) or pain.001.001.03

Response: OK

Try it: interactive reference

POST /v03/api/payment-channel/{channel}/sepa ​

Downloads the sepa file for the posted invoices.

ParameterInTypeRequiredDescription
channelpathPaymentChannelyes
payerIbanNumberquerystringPayer iban number.
payerBicquerystringPayer BIC.
bankPartyIdquerystringPayer bank party id. Depends on the bank.
inlinequerybooleanIf true, returns the content as inline (disposition). If false, the content is returned as an attachmnent.
versionquerystringISO 20022 version, pain.001.001.02 (default) or pain.001.001.03

Request body: Invoice[] (required)

Response: OK

Try it: interactive reference

GET /v03/api/payment-channel/{channel}/{id}/calculation ​

Gets the calculation in a single net salary invoice. Please note that this is applicable only for net invoices.

ParameterInTypeRequiredDescription
channelpathPaymentChannelyesPayment channel key.
idpathstringyesThe id of the invoice.

Response: Calculation

Try it: interactive reference

GET /v03/api/payment-channel/{channel}/calculation ​

Gets the calculations in net salary invoices. Please note that this is applicable only for net invoices.

ParameterInTypeRequiredDescription
channelpathPaymentChannelyesPayment channel key.
idsquerystring[]The ids of the invoices.

Response: Calculation[]

Try it: interactive reference

GET /v03/api/payment-channel/{channel}/status/{status} ​

Returns invoices to be paid by the partners customer companies. The status filter can be set for the query. Optionally the period range (start and end date) can be given for the query. If the period is not specified, it is last 14 days.

ParameterInTypeRequiredDescription
channelpathPaymentChannelyesPayment channel key.
statuspathInvoiceStatusyesStatus filter for the query.
dateKindqueryInvoiceDateKindDate specifier for the period: invoicing date, due date or logical date (like salary date).
startquerystringOptional start date for the period to query the invoices. If not set, defaults to last 14 days.
endquerystringOptional end date for the period to query the invoices. If not set, today is used.

Response: Invoice[]

Try it: interactive reference

POST /v03/api/payment-channel/{channel}/update-status ​

Accepts and processes an invoice status notification message. The 3rd party system can notify the invoice to be unread, read, paid or canceled. The external id can be set in the notification for the invoice for later messaging. If the notification message contains an external id and not a regular id, the system tries to find the correct invoice using the earlier given external id for the invoice.

ParameterInTypeRequiredDescription
channelpathPaymentChannelyesPayment channel key.

Request body: InvoiceStatusNotification[] (required)

Response: Invoice[]

Try it: interactive reference

POST /v03/api/payment-channel/{channel}/payment-messages ​

Creates a payment message (maksuaineisto) from unread invoices of one payer, or resends a message with parentMessageId. The server renders the file and allocates the display number; the message stays new until the deliverer marks it sent (PATCH status sent). Returns 201 with a Location header. Send an Idempotency-Key header to make a retry safe: the same key and body within 24 hours returns the original message; the same key with another body is refused. A create whose invoices span partitions, under a rejecting partition policy, is refused with 400 and validation.partitions.

ParameterInTypeRequiredDescription
channelpathPaymentChannelyesPayment channel key.
Idempotency-Keyheaderstring

Request body: PaymentMessageCreateRequest (required)

Response: PaymentMessage

Try it: interactive reference

GET /v03/api/payment-channel/{channel}/payment-messages ​

Lists the payment messages of the channel from the search index, newest first unless ordered: summary rows without batches, one page at a time. The index follows the table about a second later; get, patch and the file read the table.

ParameterInTypeRequiredDescription
channelpathPaymentChannelyesPayment channel key.
statusquerystringOptional status filter. The status set is open.
$searchquerystring
$filterquerystringSpecifies the logic to pull back a subset of records.
$orderbyquerystringSpecifies the values used to sort the collection of entries.
$selectquerystringThe $select system query option allows the clients to requests a limited set of properties for each entry.
$topquerynumberSpecifies the subset of entries by count.
$skipquerynumberSpecifies the count of entries to skip.
$countquerybooleanIndicates whether or not to include a total entry count.

Response: PageResultOfPaymentMessageListItem

Try it: interactive reference

GET /v03/api/payment-channel/{channel}/payment-messages/{id} ​

Gets a payment message with its batches and transaction ids.

ParameterInTypeRequiredDescription
channelpathPaymentChannelyesPayment channel key.
idpathstringyesId of the payment message.

Response: PaymentMessage

Try it: interactive reference

PATCH /v03/api/payment-channel/{channel}/payment-messages/{id} ​

Changes the status of a payment message: { "status": "sent" } marks it sent after the deliverer fetched the file (its unread invoices become read), { "status": "cancellationRequested" } asks to cancel (the invoices are not touched), { "status": "executed" } marks it paid where the channel allows it (the invoices become paid).

ParameterInTypeRequiredDescription
channelpathPaymentChannelyesPayment channel key.
idpathstringyesId of the payment message.

Request body: PaymentMessagePatch (required)

Response: PaymentMessage

Try it: interactive reference

GET /v03/api/payment-channel/{channel}/payment-messages/{id}/sepa ​

Downloads the stored file of a payment message, under its stored file name. An idempotent read: the same file every time.

ParameterInTypeRequiredDescription
channelpathPaymentChannelyesPayment channel key.
idpathstringyesId of the payment message.
inlinequerybooleanIf true, returns the content as inline (disposition). If false, the content is returned as an attachment.

Response: OK

Try it: interactive reference

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.