Appearance
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.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
channel | path | PaymentChannel | yes | Payment channel key. |
$search | query | string | ||
$filter | query | string | Specifies the logic to pull back a subset of records. | |
$orderby | query | string | Specifies the values used to sort the collection of entries. | |
$select | query | string | The $select system query option allows the clients to requests a limited set of properties for each entry. | |
$top | query | number | Specifies the subset of entries by count. | |
$skip | query | number | Specifies the count of entries to skip. | |
$count | query | boolean | Indicates 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.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
channel | path | PaymentChannel | yes | Payment 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.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
channel | path | PaymentChannel | yes | Payment channel key. |
id | path | string | yes | Unique identifier for the object |
Response: Invoice
Try it: interactive reference
DELETE /v03/api/payment-channel/{channel}/{id}
Deletes an object from the storage
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
channel | path | PaymentChannel | yes | Payment channel key. |
id | path | string | yes | Unique 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.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
channel | path | PaymentChannel | yes | Payment channel key. |
id | path | string | yes | The id of the invoice. |
inline | query | boolean | If 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.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
channel | path | PaymentChannel | yes | Payment channel key. |
ids | query | string[] | The ids of the invoices. | |
inline | query | boolean | If 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.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
channel | path | PaymentChannel | yes | |
inline | query | boolean | If 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.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
channel | path | PaymentChannel | yes | Payment channel key. |
id | path | string | yes | The id of the invoice. |
type | path | ReportType | yes | Calculation report type. Currently only salarySlip, employerReport, paymentReport and accountingReport are supported. |
inline | query | boolean | If true, returns the content as inline (disposition) in browser. If false, the content is returned as an attachment (download, default). | |
isSensitive | query | boolean | If true, the pdf hides any personal ids of the worker. | |
target | query | string | Accounting 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.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
channel | path | PaymentChannel | yes | Payment channel key. |
ids | query | string[] | The id of the invoice. | |
type | path | ReportType | yes | Calculation report type. Currently only salarySlip, employerReport, paymentReport and accountingReport are supported. |
inline | query | boolean | If true, returns the content as inline (disposition) in browser. If false, the content is returned as an attachment (download, default). | |
isSensitive | query | boolean | If true, the pdf hides any personal ids of the worker. | |
target | query | string | Accounting 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.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
channel | path | PaymentChannel | yes | Payment channel key. |
id | path | string | yes | The id of the invoice. |
target | query | string | Accounting 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.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
channel | path | PaymentChannel | yes | Payment channel key. |
ids | query | string[] | The ids of the invoices. | |
target | query | string | Accounting 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.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
channel | path | PaymentChannel | yes | |
id | path | string | yes | Id of the invoice for the sepa payment. |
payerIbanNumber | query | string | Payer iban number. | |
payerBic | query | string | Payer BIC. | |
bankPartyId | query | string | Payer bank party id. Depends on the bank. | |
inline | query | boolean | If true, returns the content as inline (disposition). If false, the content is returned as an attachmnent. | |
version | query | string | ISO 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.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
channel | path | PaymentChannel | yes | |
ids | query | string[] | Ids of the invoices for the sepa payment. | |
payerIbanNumber | query | string | Payer iban number. | |
payerBic | query | string | Payer BIC. | |
bankPartyId | query | string | Payer bank party id. Depends on the bank. | |
inline | query | boolean | If true, returns the content as inline (disposition). If false, the content is returned as an attachmnent. | |
version | query | string | ISO 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.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
channel | path | PaymentChannel | yes | |
payerIbanNumber | query | string | Payer iban number. | |
payerBic | query | string | Payer BIC. | |
bankPartyId | query | string | Payer bank party id. Depends on the bank. | |
inline | query | boolean | If true, returns the content as inline (disposition). If false, the content is returned as an attachmnent. | |
version | query | string | ISO 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.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
channel | path | PaymentChannel | yes | Payment channel key. |
id | path | string | yes | The 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.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
channel | path | PaymentChannel | yes | Payment channel key. |
ids | query | string[] | 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.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
channel | path | PaymentChannel | yes | Payment channel key. |
status | path | InvoiceStatus | yes | Status filter for the query. |
dateKind | query | InvoiceDateKind | Date specifier for the period: invoicing date, due date or logical date (like salary date). | |
start | query | string | Optional start date for the period to query the invoices. If not set, defaults to last 14 days. | |
end | query | string | Optional 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.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
channel | path | PaymentChannel | yes | Payment 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.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
channel | path | PaymentChannel | yes | Payment channel key. |
Idempotency-Key | header | string |
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.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
channel | path | PaymentChannel | yes | Payment channel key. |
status | query | string | Optional status filter. The status set is open. | |
$search | query | string | ||
$filter | query | string | Specifies the logic to pull back a subset of records. | |
$orderby | query | string | Specifies the values used to sort the collection of entries. | |
$select | query | string | The $select system query option allows the clients to requests a limited set of properties for each entry. | |
$top | query | number | Specifies the subset of entries by count. | |
$skip | query | number | Specifies the count of entries to skip. | |
$count | query | boolean | Indicates 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.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
channel | path | PaymentChannel | yes | Payment channel key. |
id | path | string | yes | Id 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).
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
channel | path | PaymentChannel | yes | Payment channel key. |
id | path | string | yes | Id 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.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
channel | path | PaymentChannel | yes | Payment channel key. |
id | path | string | yes | Id of the payment message. |
inline | query | boolean | If true, returns the content as inline (disposition). If false, the content is returned as an attachment. |
Response: OK
Try it: interactive reference

