Certificates for the production environment
Starting with the Vero API interface
First make a subscription for a certificate. After you have done that, your organisation can start using the Vero API.
However, if the user organisation’s software application already contains a Web Service certificate, issued to data providers by the Incomes Register, there is no need for a new certificate. Vero API can be access with the certificate you already have.
How to apply for a production certificate:
Make an application in the Incomes Register’s e-service.
- Log in and select the company applying for a certificate (a production certificate can be requested only by a person authorised to sign for the company).
- On the company’s pages, select: Settings > Technical interface
- Check that the purpose of use of the interface indicated at Valid rights is “Earnings payment data, organisation reports the wages it has paid and Earnings payment data, organisation reports wages on behalf of another party”, and that the channel selection is “Earnings payment data – Web Service”. Other rights may also be selected.
- If the purpose of use is not reporting earnings payment data and the channel selection is not Web Service, then you must submit a replacement application. Select Make a replacement application.
- In the replacement application, tick the following options in addition to any other options already selected: at purpose of use of the interface, tick “Earnings payment data, organisation reports the wages it has paid and Earnings payment data, organisation reports wages on behalf of another party”, and at channel, tick “Earnings payment data – Web Service”. The replacement application replaces all previous selections, so make sure the application contains all the purposes of use and all the channels that the company needs.
- When your right to access the interface has been verified, make the certificate application: Certificates > Apply for a new certificate
- Select “Earnings payment data – Web Service” as the type of production certificate
- Production certificate users must accept and follow the terms and conditions of use for the Tax Administration’s and the Incomes Register’s interface services (available in pdf format in Finnish and Swedish, link to Finnish)
- You must specify a technical contact person in the certificate application. The technical contact person retrieves the certificate from the certificate service interface.
- Send the application by clicking Submit. The system immediately starts processing your request.
- The technical contact person will be sent instructions for retriving the certificate by secure e-mail. They will receive a text message on their mobile phone containing a PIN for opening the secure e-mail message. The PIN will be sent after the contact person has clicked the “Open message” link on the secure e-mail message they received when they applied for the certificate. The certificate must be retrieved from the certificate service interface within 14 days after you submitted the application.
- After successful retrieval, the technical contact person specified in the application imports the certificate into the software. If the user organisation does not have a valid certificate, Vero API will not transmit the records the organisation requests.
- Vero API responds to calls made with production certificates only after the certificate has been retrieved and installed in the organisation’s environment. Certificates for Vero API are retrieved from the Incomes Register's certificate service once a day on workdays. In general, production certificates generated in the certificate service during office hours (8.00 am to 4.15 pm) will work in Vero API calls on the following day.
You can watch the following videoclip about the Incomes Register:
Näin käytät tulorekisteriä - Hae uutta varmennetta (only in finnish)
Notes for IT developers:
- The organisation that wants to have a certificate subscription must have an agreement on the provision of services with their customer within the meaning of the terms and conditions of interface services. You may have a software program designed for accounting firms or other third-party providers of services to taxpayers. If the users of your software are usually not taxpayers or filers, the users must submit applications for certificates.
- After retrieval of a certificate, the commercial software vendor must give sufficient guidance to their customers, the user organisations, on how certificates must be handled when the software program is being used.
- The user organisation’s certificate must be fed into the software program because it replaces the user organisation’s electronic signature.
- The Tax Administration recommends that software programs are encoded so as to support certificate-based authentication and production certificates.
You can find documentation on the interfaces of Vero API and the URL addresses for the production environment at the following address: https://avoinomavero.vero.fi/APIPortal/