# 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](https://code.salaxy.com/reference/rest-api.md). Machine-readable: [OpenAPI document](https://code.salaxy.com/openapi/salaxy-03.json).

**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](https://code.salaxy.com/reference/errors.md).

## `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](https://code.salaxy.com/reference/rest-api.md#tag/paymentchannel/GET/v03/api/payment-channel/{channel})

## `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](https://code.salaxy.com/reference/rest-api.md#tag/paymentchannel/POST/v03/api/payment-channel/{channel})

## `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](https://code.salaxy.com/reference/rest-api.md#tag/paymentchannel/GET/v03/api/payment-channel/{channel}/{id})

## `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](https://code.salaxy.com/reference/rest-api.md#tag/paymentchannel/DELETE/v03/api/payment-channel/{channel}/{id})

## `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](https://code.salaxy.com/reference/rest-api.md#tag/paymentchannel/GET/v03/api/payment-channel/{channel}/{id}/content)

## `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](https://code.salaxy.com/reference/rest-api.md#tag/paymentchannel/GET/v03/api/payment-channel/{channel}/content)

## `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](https://code.salaxy.com/reference/rest-api.md#tag/paymentchannel/POST/v03/api/payment-channel/{channel}/content)

## `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](https://code.salaxy.com/reference/rest-api.md#tag/paymentchannel/GET/v03/api/payment-channel/{channel}/{id}/{type})

## `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](https://code.salaxy.com/reference/rest-api.md#tag/paymentchannel/GET/v03/api/payment-channel/{channel}/{type})

## `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](https://code.salaxy.com/reference/rest-api.md#tag/paymentchannel/GET/v03/api/payment-channel/{channel}/{id}/accounting)

## `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](https://code.salaxy.com/reference/rest-api.md#tag/paymentchannel/GET/v03/api/payment-channel/{channel}/accounting)

## `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](https://code.salaxy.com/reference/rest-api.md#tag/paymentchannel/GET/v03/api/payment-channel/{channel}/{id}/sepa)

## `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](https://code.salaxy.com/reference/rest-api.md#tag/paymentchannel/GET/v03/api/payment-channel/{channel}/sepa)

## `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](https://code.salaxy.com/reference/rest-api.md#tag/paymentchannel/POST/v03/api/payment-channel/{channel}/sepa)

## `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](https://code.salaxy.com/reference/rest-api.md#tag/paymentchannel/GET/v03/api/payment-channel/{channel}/{id}/calculation)

## `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](https://code.salaxy.com/reference/rest-api.md#tag/paymentchannel/GET/v03/api/payment-channel/{channel}/calculation)

## `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](https://code.salaxy.com/reference/rest-api.md#tag/paymentchannel/GET/v03/api/payment-channel/{channel}/status/{status})

## `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](https://code.salaxy.com/reference/rest-api.md#tag/paymentchannel/POST/v03/api/payment-channel/{channel}/update-status)

## `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](https://code.salaxy.com/reference/rest-api.md#tag/paymentchannel/POST/v03/api/payment-channel/{channel}/payment-messages)

## `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](https://code.salaxy.com/reference/rest-api.md#tag/paymentchannel/GET/v03/api/payment-channel/{channel}/payment-messages)

## `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](https://code.salaxy.com/reference/rest-api.md#tag/paymentchannel/GET/v03/api/payment-channel/{channel}/payment-messages/{id})

## `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](https://code.salaxy.com/reference/rest-api.md#tag/paymentchannel/PATCH/v03/api/payment-channel/{channel}/payment-messages/{id})

## `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](https://code.salaxy.com/reference/rest-api.md#tag/paymentchannel/GET/v03/api/payment-channel/{channel}/payment-messages/{id}/sepa)
