General
On the Withholding percentage request view , you can fetch payroll tax cards and other income types from the Finnish Tax Administration (VeroAPI) for employees without any time restrictions, either manually or automatically. The view can be found in section Payroll > Withholding percentage request.
Withholding percentage request saves the following tax card information in the employee's Salary info:
tax card type
tax percentages (Base and Additional)
tax card date and creation date
income limit
User rights
Users with access rights to payroll and Notifications can access the view.
Certificate
Both retrieval methods require a certificate. In manual retrieval, the certificate selected in the user’s Personal info and settings section is used.
Since automatic retrieval runs without user intervention, the certificate defined in the user’s settings cannot be used; instead, automatic retrieval uses the certificate specified in the company’s usage settings.
Fetching the tax cards to Procountor
Wages tax cards and other income types are fetched via VeroApi.
You can select which income type(s) the tax card details are retrieved. This enables, for example, the automatic retrieval of tax card data for compensation for work. An employee may have tax cards corresponding to several different income types. Tax card income types used for withholding requests can be defined in the employee's salary info view under the Payroll > Employee register > Salary info > Tax card.
The newest tax card is the valid tax card.
Expections regarding revised cards
If you have used the direct transfer of tax cards (1.2.2024) and the employee has applied for a revised tax card after that date, the tax card with the most recent date is selected for use when fetching it with VeroApi.
If you have entered a newer card manually or fetched a new tax card with VeroApi, the tax card with the newer date is valid regardless of whether it is marked as a revised tax card or not.
If the employee has applied tax card for the same day as the direct transfer of tax card (valid from 1.2) and the employee has not applied for revised tax cards later, then the program will select the tax card with the revised tax card: yes mark.
If the employee has applied for a revised tax card that is already valid before the direct transfer of tax card (before 1.2), the direct transfer of tax card should be removed from the program, unless the employee has applied for a new revised tax card later with a newer date.
In the future (starting in 2025), the revised tax card information is not needed, because the VeroApi will always deliver a valid card for the requested date.
Search criteria
You can request withholding tax info for all employees, who have all the required information filled in Person register and in Employee register.
The list of employees can be filtered based on the name of the employee or person group. The search can also include inactive persons. With the Search button, the program performs a search according to the conditions. Use the Clear button to clear the search criteria and the program will re-list all employees.
Fetching tax cards
Tax cards can be retrieved in two ways:
Manually: The user starts the retrieval.
Automatically: The system retrieves updated tax cards every night.
Manual retrieval
Manual retrieval of tax cards has already been possible in previous versions of Procountor.
In manual retrieval, the user starts the process using the Withholding percentage request function and specifies the payment date for which the tax cards should be retrieved, for example, the payday of the salary period.
The Tax Administration returns a tax card for all selected employees that is valid on the given date. The retrieved tax card is updated in Procountor only if it differs from the tax card currently assigned to the employee.
Create a new request
By default, the Withholding percentage request view lists all employees added to the environment. The grid shows the latest tax card request details per employee.
In order to fetch the withholding percentage details for the employees, navigate to Payroll > Withholding percentage request.
Enter the Payment date ie the date when salaries are going to be paid.
Select the employees and click Send request.
Request is sent within 5 minutes and response is almost immediate. View refreshes automatically after sending request.
The new tax card information is updated if the tax card date, the additional % or the annual income limit has changed. If the information is the same as in the previous tax card, a new tax card will not be added. For example if the employee's tax percentage has been changed manually in the Salary info view after the latest tax card request, the tax card information will not be updated.
The tax cards statuses are as follows:
Queued = Waiting to be sent on Procountor side (5min interval)
In progress = Request has been sent to tax authorities
Received, new = Tax card updated successfully behind the employee in Employee register/Salary info
Received, no changes = Tax card has not been updated, ie the tax card is the same as the previous one
Received, incomplete = No tax cards available. Request employee to apply for a tax card.
Empty = The first request has not yet been made.
Failed = Tax card request failed for some reason. Error code is given by the tax authorities.
Error codes given by the tax authorities (If you receive one of the error messages below, contact the Tax authorities for further instructions:
Value | Description |
1005 | Virhe pyynnön käsittelyssä |
1010 | No data |
1101 | Virheellinen henkilö- tai Y-tunnus |
WHP001 | Missing parameter place holder |
WHP002 | Invalid recipient id requested |
WHP003 | Invalid Payer id requested |
WHP004 | Invalid Payment date requested |
WHP006 | Too many income types are being queried, a maximum of 10 income types can be requested in one call. |
WHP007 | Withholding data not yet available |
Automatic retrieval
Automatic retrieval is a new feature in Procountor.
In automatic retrieval, the system fetches updated tax cards every night and updates them for employees without any user action. The Tax Administration returns tax cards only for employees whose tax card has changed.
Automatic retrieval is enabled by selecting Allow the usage of Withholding percentage request automation in the Integration Settings section of the Management > Company Info > Usage Settings. In addition, under Selected incomes register certificate, select the certificate that the automatic retrieval will use.
New employee
When a new employee is added to the employee register, the employee's tax card valid on that day is automatically retrieved if automatic retrieval has been enabled and the employee has not been excluded from automatic retrieval.
Request history
Automatic retrieval is also displayed on Payroll > Withholding Percentage request > Request History tab.
Newest automatically fetched tax cards
The Newest Automatically Fetched Tax Cards -widget on the front page displays automatically retrieved tax cards from the last week. The widget displays a time stamp, the employee's name, and any errors that may have occurred during the retrieval. The widget's Withholding percentage request -button allows you to easily navigate to the Withholding percentage request -view, whose Request History -tab shows more detailed information about the automatic retrieval.
The Employee Register -button opens the employee register, from which you can easily change, for example, the employee's Tax Card settings on the Salary Info -tab.
Excluding the employee from the withholding request
In case an employee has some other tax card than wages, you can exclude the employee from the withholding request. This is done in Employee register > Salary info: Exclude employee from Withholding percentage request (VeroAPI). After this, the employee cannot be selected for the request.
Clicking toggle Show employees excluded from the withholding percentage request, shows employees who were excluded from the tax card fetching. As a default they are not visible.
Withholding percentage request history
The bottom grid shows the history of requests e.g. 2 employees' details were requested on 6.5.2024. And shows their success ratio (e.g. Received 2/2).
The grid shows:
When the request is sent
Request sender
number of tax cards
Request's status and success ratio
Other comments
By activating the line of an individual request and pressing Show request button, you can access a view where you can see the employees and tax card statuses contained in the request.
When you right-click on any search result, a drop-down list opens where you can export the results to Excel, PDF or HTML.