Instructions on the testing certificate

The instructions were updated on 8 January 2023. The update concerns the Tax Administration's new e-service for the certificate service. In the service, you can request additional testing certificates and retrieve testing certificates. Testing certificates can also retrieved through the API as before.

The way of requesting revocation of a testing certificate has also changed. The e-service and the making of a revocation request are discussed in more detail in these instructions.

Key terms

Project
The project to establish a positive credit register answers for the development of the register. The project provides stakeholder support during testing.

Certificate Signing Request (CSR)
A PKCS#10 certificate signing request is sent to the certificate service API. The certificate service then generates a certificate, which can be retrieved through the certificate service API.

Certificate
An electronic identifier issued by the Incomes Register Unit to identify the user.

A testing certificate is for use in the stakeholder testing environment. Access rights and certificates for the API that will be used when the Positive credit register is rolled out to production at the beginning of 2024 must be requested separately before the rollout.

Testing organisation
A company or organisation participating in the stakeholder testing of the Positive credit register.

Technical contact person
A person who is specified by the testing organisation in the testing start notification and to whom the information needed to retrieve a testing certificate is sent.

Testing start notification
A testing start notification is submitted with an online form. In the notification, the stakeholder gives the Positive credit register the information needed to start testing, specifies the services to be tested, and accepts the terms and conditions of the testing environment.

More terminology in the instructions on stakeholder testing and in the Positive credit register’s glossary (Suomi.fi).

1 Introduction

This document provides instructions on the testing certificate used in the Positive credit register’s stakeholder testing. Instructions on stakeholder testing provide a general description of how the stakeholder testing is implemented.

In order that the APIs of the Positive credit register could be used, the party calling the 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.

The certificate that will be used in production is different from the one used in testing. The stakeholders have received separate instructions on the certificate needed in the production environment. Read the instructions on the production certificate.

2 Certificate service

The customer is identified and the API access right is verified based on a certificate. Certificates are issued to a specific organisation for a specific purpose, and they cannot be used for purposes differing from the original. The certificate user must accept the terms and conditions of use for stakeholder testing and comply with them.

The Tax Administration's certificate service is used in the Positive credit register’s stakeholder testing. The certificate service is based on a PKI solution (Public Key Infrastructure). Certificates can be retrieved through the API or from the Tax Administration's certificates e-service. These instructions describe how to retrieve the first testing certificate from the API of the certificate service.

In the certificates e-service, stakeholders can not only retrieve testing certificates but also order additional testing certificates themselves. Once the stakeholder has signed up for testing, the testing contact person can log in to the service through a link sent to them by email. After logging in, the contact person can invite others to use the service. Users identify themselves for the e-service in the Suomi.fi service.

Read the instructions on the certificates e-service (vero.fi).

2.1 Certificate types

The APIs for reporting data and for requesting data are used with different types of certificates. 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. 

If the testing organisation tests both the reporting and the requesting of data, it needs different types of certificates.

• Two types of certificates are used in the Positive credit register: a certificate for reporting data and a certificate for requesting data.
• Each testing certificate is connected to an artificial Business ID and an artificial organisation name. The information is delivered to the person who filled in the testing start notification. 
• If the testing organisation tests both the reporting and the requesting of data, the same artificial Business ID is connected to both certificates. However, the testing organisation may have several artificial Business IDs and associated certificates, if needed. This may be necessary, for example, when the organisation tests the reporting of data on behalf of several stakeholders. The testing organisation can request additional certificates or artificial Business IDs by filling in the contact form for stakeholder testing.

The Tax Administration is the issuer of the certificates it grants. Because of this, the issuer information about these certificates cannot be found in the distribution of commercial off-the-shelf software. The testing organisation ensures the technical reliability of the certificates in its own system by downloading the root certificates and issuer certificates of the certificates granted by the Tax Administration from the website. Once the organisation has installed the downloaded certificates in its own system, a trusted relationship with the Tax Administration’s certificates is established and the APIs can be used securely.

The root and issuer certificates can also be downloaded from the links below:

Certificate for data notifier: Data Providers Test Issuing CA v1 (ZIP)

Certificate for data user: PCR Credit Data Users Test Issuing CA v2 (ZIP)

Read more in the interface description of the certificate service.

3 Retrieving the first testing certificate

This chapter describes how to retrieve your first testing certificate from the certificate service API. You can also retrieve the certificate from the Tax Administration’s certificates e-service.

Read the instructions on how to retrieve a certificate from the certificates e-service (vero.fi).

In order to retrieve their first testing certificate, the testing organisation must first sign up for stakeholder testing. Instructions on how to sign up for stakeholder testing are found in the instructions on stakeholder testing.

Once the project has processed the signing up, the certificate service sends the technical contact person the information needed to retrieve a certificate. The information is sent to the technical contact person by secure email. The contact person can open the email message with a code sent by text message. For this reason, the technical contact person's contact information must contain an email address that is not a distribution list or a shared mailbox, and a telephone number on which text messages can be received. The telephone number must include the country prefix.

The technical contact person 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. 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 testing organisation must request a new certificate by filling in the contact form for stakeholder testing.

The technical contact person retrieves the certificate through the Web Service interface of the certificate service. The certificate is retrieved by 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 a certificate retrieval ID. The technical contact person saves the retrieval ID and uses it to send a certificate retrieval request. The certificate service then returns a certificate in response to the certificate retrieval request.

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. Instructions on how to sign up for testing and request additional certificates are found in the instructions for stakeholder testing.

1. To get a new testing certificate, the testing organisation must submit a testing start notification in the portal. The technical contact person who retrieves the certificate is specified in the start notification. The technical contact person must have sufficient technical competence for certificate retrieval.

Instructions on how to request additional testing certificates are provided in chapter 4.1. Additional certificates can be retrieved in the same way as the first certificate.

2. Once the testing start notification has been processed, the certificate service sends the technical contact person specified in the notification a secure email message containing two unique identifiers: a transfer ID (TransferId) and a one-time password (TransferPassword). The email message can be opened with a PIN code. The technical contact person is first sent an email message that contains a link to open the secure email message. When the technical contact person 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 testing organisation must request a new testing certificate.

3. The technical contact person generates a 2,048-bit key pair by the RSA algorithm for the certificate request. In addition, the technical 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 signing request.

4. The technical contact person sends a certificate request to the certificate service's Web Service interface.

The certificate request is a SignNewCertificateRequest. In addition to the newly formed CSR, the message contains a transfer ID (TransferId) received by secure email and a one-time password (TransferPassword). Further, the artificial Business ID (CustomerId) and name (CustomerName) provided for the organisation during the processing of the notification are included in the message.

You can download a dynamic WSDL description from the address https://pkiws-testi.vero.fi/2017/10/CertificateServices.wsdl. The WSDL description and XML schemas can also be downloaded from the Incomes Register's website.

Service calls are sent to https://pkiws-testi.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: "signNewCertificate"

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.

The certificate service receives the signing request and returns a response message.

5. The technical contact person 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 you send 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.

6. The technical contact person sends the certificate retrieval request (GetCertificateRequest) to the API of the certificate service. The certificate retrieval ID (RetrievalId) received in the response to the previous call must be included in the message. In addition, the message must contain the same artificial Business ID and name as the previous message.

The certificate service returns a certificate in the response message.

7. In the GetCertificateResponse, the technical contact person receives the certificate generated for the organisation by the certificate service. After this, the organisation can use the certificate in its API calls by connecting the certificate to the private key it has 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 the testing organisation needs additional testing certificates for an API they are testing, they can order a new certificate themselves in the certificates e-service. Read the instructions on the certificate service (vero.fi).

You can also request a new certificate by filling in the contact form. The organisation must specify on the form whether the certificate is needed for reporting data or for requesting data, and whether the same or different artificial Business ID as in the previous certificates should be connected to the new certificate. It is possible to connect several certificates of the same type (for example, several certificates for reporting data) to the same artificial Business ID.

4.2 Testing on behalf of a stakeholder

If stakeholder testing is performed by a party other than the stakeholder, the certificate can be requested for the party performing the testing. Before submitting a testing start notification, the stakeholder must check who in the testing organisation will act as the technical contact person and retrieve the certificate. The contact information of this person must be reported in the testing start notification to make sure the information needed for certificate retrieval is sent to the correct person.

If the stakeholder also wants to perform testing at the same time, they can request a separate certificate for themselves in the certificates e-service.If the stakeholder cannot use the certificates e-service, additional testing certificates can also be requested with the contact form. The stakeholder can also agree on a shared testing certificate with the testing party.

Read more about the certificates e-service (vero.fi).

4.2.1 The certificate processes for testing and production are different

In the Positive credit register, only a party with the reporting obligation or a party with the right to use data can sign up as a data notifier or request a data permission for requesting data. Only such operators can request and obtain a production certificate required for reporting and requesting data.

Read more:

Procedures applicable to the use of the Positive credit register’s certificate
Instructions on the certificate used in production

The present instruction document describes the use of testing certificates only.

4.3 Renewing a testing certificate

The testing certificate is valid for two years, after which it must be renewed. The organisation is responsible for renewing the certificate themselves.

Read more about the lifecycle and renewal of certificates in the instructions on the certificate service (vero.fi). If the testing certificate is not renewed before its expiry and the testing organisation cannot use the certificates e-service, they can request a new testing certificate with the contact form for stakeholder testing.

4.4 Closing a testing certificate

If the stakeholder wants the testing certificate to be closed, they can request revocation by filling in the certificate service observation form. The serial number of the certificate must be stated on the form.

Certificate service observation form (vero.fi).

5 Frequently asked questions

Below you can find some frequently asked questions about certificate retrieval.

5.1 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="https://pkiws-testi.vero.fi/2017/10/CertificateServices">
<soapenv:Header/>
<soapenv:Body>
<cer:GetCertificateRequest>
<Environment>TEST</Environment>
<CustomerId>Artifical Business ID received from the Positive credit register</CustomerId>
<!--Optional:-->
<CustomerName>Artificial organisation name received from the Positive credit register</CustomerName>
<RetrievalId>Certificate retrieval ID (RetrievalId) received in the SignNewCertificateResponse</RetrievalId>
</cer:GetCertificateRequest>
</soapenv:Body>
</soapenv:Envelope>

5.2 What data is used in the certificate signing request?

When creating a certificate signing request (CSR), the testing organisation provides information on an artificial organisation requesting a certificate (Subject). The following details on the artificial organisation must be entered in the CSR:

Common Name (CN), enter the artificial Business ID received from the Positive credit register.
Organization (O), enter the artificial organisation name received from the Positive credit register.
Country (C), enter FI.

In the test environment, the artificial information provided to the organisation for testing purposes is used. The organisation's own information is used only in production.

5.3 How to connect CSR data 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.4 How to save a 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 should 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-----

5.5 Testing of certificate retrieval

It is possible to test the retrieval of a certificate in the test bench of the Incomes Register's certificate service. The test bench of the certificate service is a separate service that has separate addresses and is designed only for certificate testing.

In the test bench, the technical contact person can test the accuracy of the messages sent to the certificate service’s API without that a certificate is generated. Testing stakeholders can also use the test bench to develop an application calling the certificate service API.

Please note that the testing certificate needed in stakeholder testing cannot be retrieved from the test bench. Further, the addresses and data used in the test bench should not be used when the testing certificate is retrieved.

Read the instructions on the certificate service's test bench (pdf)
Download the certificate service’s test data (zip)

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 in the acknowledgement of receipt of a service call, when

• the service call does not comply with the service schema
• the transfer IDs are invalid
• a certificate signing request connected to the request is incorrect in form
• some other technical error caused by an exceptional situation is detected.

The returned error codes and their descriptions are found in the interface description of the certificate service.

6.1 An error occurs when a certificate retrieval request is being sent

If the 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 yet processed the certificate request before an attempt is made to retrieve the certificate. If a 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 must retrieve the certificate within 14 days from the date when they received a secure email message containing information for certificate retrieval. If the certificate is not retrieved within this time period, the testing organisation must request a new testing certificate by filling in the contact form for stakeholder testing.

7 Further information and support

The technical documentation used in stakeholder testing for the positive credit register has been published on the Documentation page.

Dokumentation of the certificate service (vero.fi)

Certificate service – Interface description (pdf)
General instructions for application developers (pdf)
Testing instructions for stakeholders

Technical errors can be reported with the observation form for stakeholder testing. If you need additional testing certificates, fill in the contact form.

Forms for stakeholder testing