Certificates for the production environment
Deploying application to production
The instruction is divided into actions of the organization using the interface and the software developer.
An organization using an interface
The user organization of the interfaces, the user of the software, is required to have a production certificate. The production certificate acts as the user's identifier. The user of the interfaces can be the customer, i.e. the obliged entity himself or a party authorized by him or herself, in accordance with the terms of use of the interfaces.
Software developer
Software developers register their software in the API portal and selects the interfaces they use before starting production use. The registered software receives an API key. The API key is software-specific and acts as a software identifier. The API key is not intended to be managed by the users of the software, and the software developer should build the key handling inside the software.
The software developer should ensure the technical functionality of the software's production connection and API key against the interfaces it uses. The verification is done independently against the integration verification address published in the API portal (URL Integration verification).
After verification of the integration, the software is ready for production.
Learn more about software registration
How to apply for a production certificate:
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
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.
- the production certificate is retrieved from the production address of the certificate service's Web Service interface: https://pkiws.vero.fi/2017/10/CertificateServices (TCP port 443)
- 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. 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 at the latest on the following day.
For more information on the certificate service, visit the pages of the Incomes Register:
Certificate service
Questions and answers about certificates
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:
- 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.
Production environment
Documentation for Vero APIs and production environment URLs can be found on the Vero API portal.