Withholding Percentage Request – notification service

The user is a company that does its own salary payment. The user may also be an accounting firm that attends to salary payment on behalf of other companies.

The company uses financial management software with integrations into the Withholding Percentage Request API and the push notification service.

The software has an automated management of notification activities, so it can receive push notifications from the Tax Administration. The software responds to the notifications by retrieving the latest tax cards in the Withholding Percentage Request API. The software also keeps records on the notifications and tax cards that have already been processed in salary payment.

Order of actions:

1. In the Subscribe Notifications API, the user selects the individuals whose tax cards they need to pay them wages or other income. Select the income type, such as 'Wages', and the personal identity code and taxpayer type (individual taxpayer) of person A, on whose new tax cards you want to receive notifications.
2. The software uses the push notification service. The software has been registered for push notifications, and the notification subscription made includes tax cards of person A.
3. A tax card is created for person A either in MyTax or in customer service in the Tax Administration's system, and a notification of the tax card will be created within 24 hours.
4. The Tax Administration will send the key data of the notification automatically to the software that has an active push registration and active subscription for tax cards. The key data does not contain personal data but only a notification key that can be used to retrieve the actual data content of the notification.
5. Based on the key data, the software retrieves the exact data content of the notification (tax card's income type, person A's personal identity code, taxpayer type and "tax card valid from" data) in the GetNotification API.
6. Based on the exact data content of the notification, the software retrieves person A's tax card for wages in the Witholding Percentage Request API.
7. The software will use the tax card in salary payment and in submitting the withholding tax for the Tax Administration. Individual taxpayers don’t need to send their tax cards to salary payment by themselves.

The software will not send tax card requests regarding person A every day but only when it receives a notification stating that a new tax card has been generated. The user can select multiple persons in a single notification subscription. For each person specified in the subscription, the user can select the income type on which they want to request tax cards. The tax cards of all persons selected in the subscription will be retrieved for the payor only when new revised tax cards are generated.

• Note: Tax card notifications are retained for only one year. The notifications are intended to serve as alerts, not as a record of change history.
• In addition, the software has a functionality that it will call the ListNotifications API on a regular basis to make sure all notifications have been processed.
• The additional check has been built in the software because the Tax Administration does not guarantee the arrival of push notifications due to unexpected errors. Errors include situations such as the following: maintenance or data communications breaks, and random errors in the functionality of the Tax Administration / software.

The software has an active subscription for tax card notifications. The subscription concerns selected individuals whose tax cards are requested for the payment of wages or other income.

The company has some changes in personel and some of the individuals which receive wages change also. The software must terminate the current tax card subscription with the End notification request API. Changes to a valid subscription are made by first ending the subscription and then making a new subscription with the desired changes.

If the software is integrated with the push notification service, the push registration will end as the notification subscription is terminated. The software must make a new push registration and select the identifier of the new, updated tax card subscription. If the software uses only the ListNotifications API in accordance with example 2, the identifier in the ListNotifications API must be replaced with that of the new request.

If the user wants to stop using the notification service altogether, the software must take the above actions but not make any new subscriptions.