Certificate
This instruction document is about the certificates needed to report data to the Positive credit register and to use the register’s data. Note that the certificate used in production is different from the one used in testing. Read the instructions on the testing certificate used in stakeholder testing.
The instructions were updated on 8th October 2024. The update concerns the Tax Administration's new e-service for the certificate service.
Key terms and definitions
Project
The project to establish a positive credit register answers for the register’s implementation.
Certificate Signing Request (CSR)
A PKCS#10 certificate signature request is sent to the certificate service API or request is entered into the Tax Administration's certificate service, depending on the certificate retrieval method.
In the case of a retrieval via the API, after a signature request the certificate service generates a certificate that can be retrieved via the certificate service's API. When using the certificate service, the certificate file is uploaded directly to the device used by the person, according to the file manager.
Certificate
An electronic identifier issued by the Incomes Register Unit to identify the user.
Organisation
A company or an organisation using the Positive credit register’s APIs.
Technical contact person for certificates
A person who is specified by the organisation in connection with the sign-up or in the data permission application and to whom the information needed to retrieve a certificate is sent.
Signing up as a data notifier
The Act on the Positive Credit Register defines the parties with the reporting obligation that must sign up to the Incomes Register Unit through the e-service before starting to report data.
If the organisation cannot use the e-service provided for organisations, they must sign up through another service channel. In that case, the organisation can contact the Positive credit register’s customer service by phone.
Read the instructions: Signing up to the Positive credit register as a data notifier
Data permission
The Act on the Positive Credit Register prescribes who has the right to receive information from the register. A condition for a data permission is that the applicant has submitted a data permission application in the e-service and received a decision of acceptance.
If the organisation cannot use the e-service provided for organisations, they must submit a data permission application through another service channel. In that case, the organisation can contact the Positive credit register’s customer service by phone.
Read the instructions for lenders on how to request a data permission
Authorities and credit information companies will receive separate instructions on how to apply for a data permission.
You can find more terminology in the Positive credit register’s glossary (suomi.fi).
1 Introduction
This instruction document is about the certificates needed to report data to the Positive credit register and to use the register’s data. Note that the certificate used in production is different from the one used in testing. Read the instructions on the testing certificate used in stakeholder testing.
In order that the APIs of the Positive credit register could be used, a party calling an API must be identified. The API user is identified based on a certificate. The certificates acceptable in the service are issued by the Tax Administration.
2 Certificate service
The Positive credit register uses the Incomes Register Unit's certificate service. The certificate service is based on a PKI solution (Public Key Infrastructure).
The customer is identified and the API access right verified based on a certificate. The Incomes Register Unit issues certificates to a specific organisation for specific purposes, and the certificates cannot be used for any other purposes.
2.1 Certificate types
There are two types of certificates: the certificate for data notifier and the certificate for data user. In other words, the certificates used in the API for reporting data and in the API for requesting data are different. If the service user is both a data notifier and a data user, they need different types of certificates for the different purposes of use. One operator can have several certificates. The certificates can be of the same type or of different types.
Certificate for data notifier: Data Providers Issuing CA v1
Certificate for data user: PCR Credit Data Users Issuing CA v1
3 Generating a new certificate
To receive a certificate, the organisation must sign up as a data notifier or apply for a data permission. Once the organisation has received a decision of acceptance, the information needed to retrieve a certificate is sent to the technical contact person for certificates.
The technical contact person for certificates can retrieve the certificate from the Incomes Register Unit’s certificate service after receiving the transfer ID and one-time password sent for the certificate request by secure email. The one-time password is valid for 14 days. If the certificate is not retrieved within this time period, the one-time password expires. In that case, the organisation must request a new certificate from the Positive credit register’s customer service.
The technical contact person for the certificate retrieves the certificate via the Web Service API of the certificate service or via the Tax Administration's certificate service.
Via the API, the certificate is retrieved using two different API calls: certificate request and certificate retrieval request. Once the API has received the certificate request, it responds to the call by returning the certificate retrieval ID. The technical contact person for the certificate captures the retrieval ID and uses it to send a certificate retrieval request. Finally, the certificate service returns the certificate in response to the certificate retrieval request.
When a certificate is retrieved via the Tax Administration's certificate service, the technical contact person for the certificate is asked for the transfer ID and password received by him or her via a separate security e-mail, as well as the certificate signature request (CSR) generated by the technical contact person. Once the person has sent the retrieval information via the certificate service, the certificate file is uploaded to the person's device according to the file manager.
The diagram below depicts the technical process. Each phase is explained in more detail after the diagram.
Figure 1. Process diagram for certificate retrieval.
In the following description of the certificate retrieval process depicted in the diagram, the numbering refers to the numbers used in the diagram. Points 2–7 refer to the APIs and their elements mentioned in the interface description of the certificate service.
1. To receive a certificate, the organisation must sign up as a data notifier or apply for a data permission. In that connection, the organisation also specifies a technical contact person for certificates, who will retrieve the certificate. The technical contact person for certificates must have sufficient technical competence for certificate retrieval.
The contact email you provide for the technical contact person for certificates must be an email address that is not a distribution list or a shared mailbox. In addition, you must give a telephone number that can be used to receive text messages. The telephone number must include the country prefix.
If an organisation has already retrieved one certificate and wants to request additional certificates, it can order them through the Tax Administration's certificate service. The organisation must inform the Incomes Register Unit of such certificates it has ordered through the Tax Administation’s certificate service. An order for an additional certificate can be reported to the Incomes Register Unit using the Positive credit register contact form or by calling the Positive credit register customer service. Additional certificates are retrieved in the same way as the first certificate.
If an organisation cannot use the Tax Administration's certificate service for reasons such as authentication, the organisation can order additional certificates via the Positive credit register contact form or by calling the Positive credit register customer service.
2. When the Incomes Register Unit has issued a positive decision on the sign-up or data permission application, the certificate service will send a secure email message to the technical contact person for certificates specified by the organisation. The secure email includes two unique credentials: a transfer ID (TransferId) and a one-time password (OTP). You can open the secure email message only with a PIN code. The technical contact person for certificates is first sent an email message that includes a link to open the secure email message. When the technical contact person for certificates clicks the link, the PIN code needed to open the message is sent to their mobile phone by text message.
The transfer ID and the one-time password are valid for 14 days from the date the messages were sent. The certificate must be retrieved during that period. If the certificate is not retrieved within the period, the certificate order expires and the organisation must request a new certificate from the Positive credit register’s customer service.
3. The technical contact person for certificates creates a 2,048-bit key pair generated by the RSA algorithm for the certificate request. In addition, the contact person creates a PKCS#10 certificate signing request (CSR) signed with a private key. Section 5.3 describes the information to be entered in the CSR.
4. The technical contact person for the certificate sends a certificate request to the Web Service API of the certificate service or retrieves the certificate via the ‘Retrieve certificate’ function of the Tax Administration's certificate service.
The following sections of this chapter deal with retrieving a certificate using the API.
When an API is used to retrieve a certificate, the service calls must be sent to https://pkiws.vero.fi/2017/10/CertificateServices. The request used is a SignNewCertificateRequest. In addition to the newly formed CSR, the message contains a transfer ID (TransferId) and one-time password (TransferPassword) received by secure email. Further, the Business ID (CustomerId) and name (CustomerName) of the party with the reporting obligation or of the data permission holder are included in the message.
The certificate service receives the CSR and returns a response message.
5. The technical contact person for certificates receives a certificate retrieval ID (RetrievalId) in the SignNewCertificateResponse. It is important to save the retrieval ID before moving on to the next phase.
Generating a certificate takes a few seconds, so you must wait 30–60 seconds before sending a certificate retrieval request. If you try to retrieve the certificate before it has been generated, the retrieval fails. In that case, it is important that you have saved the retrieval ID so that you can make a new attempt. If the retrieval ID was not saved and the retrieval fails, the organisation must request a new certificate.
6. The technical contact person for certificates sends the certificate retrieval request (GetCertificateRequest) to the API of the certificate service. The certificate retrieval ID (RetrievalId) received in response to the previous call must be included in the message. In addition, the message must include the Business ID and name which were included in the previous message and for which the certificate has been granted.
The certificate service returns a certificate in the response message.
7. In the GetCertificateResponse, the technical contact person for certificates receives the certificate (Certificate) that the certificate service generated for the organisation. After this, the organisation can use the certificate in its API calls by linking the certificate to the private key they have generated.
If the certificate retrieval needs to be repeated, the same RetrievalId must be used.
For more detailed technical instructions on how to retrieve a certificate, see the interface description of the certificate service.
4 Other situations
4.1 Requesting additional certificates
If an organisation needs multiple certificates, it can order additional certificates through the Tax Administration's certificate service.
The certificate is operator-specific, so it is not possible for the lender and an operator acting on its behalf to use the same certificate. If the organisation uses its own certificate but some of its API activity is also performed by an organisation acting on its behalf, an additional certificate must be requested for the organisation acting on its behalf.
Additional certificates ordered by an operator on behalf of another organisation must be reported to the Incomes Register Unit using the Positive credit register contact form, where the organisation provides the name and business ID of the organisation for which the additional certificate is being issued.
If an organisation cannot use the Tax Administration's certificate service and needs additional certificates, it must contact the Positive credit register, by either using the contact form or calling the telephone customer service.
4.2 Revoking a certificate
The certificate holder must request the revocation of the certificate if the private key is misplaced or passed on to a third party by mistake. A certificate must also be revoked if it is no longer needed.
The Incomes Register Unit can revoke a certificate when, for example, the agreement entitling to use the service ends, or it is apparent that the issued certificate has been misused.
Request the revocation of the certificate by phone:
During office hours
The Positive credit register’s customer service: +358 29 497 570
On weekdays between 9 am and 4 pm.
Outside office hours
Urgent certificate revocations only: +358 9 427 34 834
5 Frequently asked questions
Below you can find some frequently asked questions about certificate retrieval.
5.1 What is the address of the certificate service, and where should the service calls be sent?
- You can download a dynamic WSDL description from the address https://pkiws.vero.fi/2017/10/CertificateServices.wsdl.
- The WSDL description and XML schemas can also be downloaded from the Incomes Register's website.
- When an API is used to retrieve a certificate, the service calls must be sent to https://pkiws.vero.fi/2017/10/CertificateServices.
- The service call must be made using the HTTP POST method. In addition, the following HTTP headers must be set:
Content-Type: “text/xml;charset=UTF-8”
Content-Length: "VALUE"
SOAPAction: "getCertificate"
The value of Content-Length is the length of the message in question, i.e. "calculated value". You must calculate the length when sending the message.
The value of SOAPAction must be the value of the API operation in question. These values can be found in the WSDL description.
-
- SOAP messages cannot be sent from a web browser (at least not without browser extensions and plugins); instead, software that can send SOAP messages must be used.
5.2 What Business ID and customer name should be used in a GetCertificateRequest?
Below is an example of a GetCertificateRequest and the Business ID and customer name to be used.
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:cer="http://certificates.vero.fi/2017/10/certificateservices">
<soapenv:Header/>
<soapenv:Body>
<cer:GetCertificateRequest>
<Environment>PRODUCTION</Environment>
<CustomerId> Business ID</CustomerId>
<!--Optional:-->
<CustomerName>Name of organisation</CustomerName>
<RetrievalId>Certificate retrieval ID (RetrievalId) received in the SignNewCertificateResponse</RetrievalId>
</cer:GetCertificateRequest>
</soapenv:Body>
</soapenv:Envelope>
5.3 What information should be used in the CSR?
When the certificate signing request (CSR) is generated, the technical contact person for certificates provides the information of the organisation (Subject) for which the certificate was granted. The following details on the organisation must be entered in the CSR:
Common Name (CN), enter the Business ID or foreign business ID.
Organization (O), enter the name of the organisation.
Country (C), enter the organisation’s 2-letter country code (ISO 3166).
5.4 How should I connect the CSR to a SignNewCertificate operation?
Enter the base64-encoded certificate signing request (CSR) contained in the CertificateRequest element without the begin and end tags:
-----BEGIN CERTIFICATE REQUEST-----
base64 encoded CSR-----
END CERTIFICATE REQUEST-----
5.5 How should I save the certificate from the getCertificate operation in a file?
If the certificate contained in the response message is saved in a file manually, the begin and end tags must be added to the base64-enconded data contained in the Certificate element such that the tags are on their own lines and the certificate data is between the tags:
-----BEGIN CERTIFICATE-----
base64-encoded certificate
-----END CERTIFICATE-----
6 Error situations
As a rule, the certificate service returns information on errors immediately when responding to an API call. However, some errors are not detected until the certificate request is processed, in which case the certificate service responds to an API call related to a certificate retrieval request by returning an error message instead of a certificate.
Information on an error is returned immediately when a service call is acknowledged as received if
- the service call does not comply with the service schema
- the transfer IDs are invalid
- a certificate signing request included in the request is incorrect in form
- some other technical error caused by an exceptional situation occurs.
The returned error codes and their descriptions are found in the interface description of the certificate service.
In an error situation, the organisation can contact the Incomes Register Unit by contacting the Positive credit register’s customer service.
6.1 An error occurs when a certificate retrieval request is being sent
If certificate generation fails, any errors (e.g. invalid identifiers) must be corrected. After this, a new API call must be made to request a certificate. An exception is a situation where the system has not had time to process the certificate request before an attempt is made to retrieve the certificate. If the certificate retrieval request is sent too soon after the certificate request, certificate retrieval may fail. Always save the retrieval ID (RetrievalId) and try again after a while. Allow 30–60 seconds for processing and then try again with the same retrieval ID.
The returned error codes and their descriptions are found in the interface description of the certificate service.
In most cases, errors in certificate retrieval take place in points 4–6 of figure 1. Before retrieving a certificate, read the instructions carefully.
6.2 The certificate was not retrieved in time
The technical contact person for certificates must retrieve the certificate within 14 days from the date when they received a secure email message containing the information for certificate retrieval. If the certificate is not retrieved within this time period, the organisation must request a new certificate from the Positive credit register’s customer service.
7 Further information and support
Read the interface description of the certificate service.
The technical documentation regarding the Positive credit register’s APIs is available on the Documentation page.
Support requests regarding certificates and certificate retrieval can be submitted using the observation form on the register's website, or by calling the Positive credit register’s customer service at +358 29 497 570.