Withholding percentage request view enables fetching withholding percentage details for employees without a time limit via VeroApi. The view can be found in section Payroll > Withholding percentage request.
Users with access rights to payroll and Notifications can access the view.
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
Once tax authorities publish the notification service, we'll be able to automatize the process ant there is no longer a need to do a separate fetching.
Direct transfer of tax cards function has been disabled in the version update of August 2024.
Excluding the employee from the withholding request
Note that only wages tax cards are fetched, any other type of tax card need to be still entered manually. 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.
Fetching the tax cards to Procountor
Only wages tax cards are fetched via VeroApi. 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.
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 |
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.