Testing instructions for stakeholders

The instructions were last updated on 10 August 2023. Addresses of the testing environment APIs and a chapter on version releases in the testing period have been added to the instructions. Signing up for testing has been clarified in the following way: When a stakeholder signs up for testing, the project does not examine their obligation to report data or their right to use register data in the production phase. Recommendations for testing organisations have been added to chapter 10. The instructions concerning stakeholders’ own test IDs have been clarified. The chapter concerning the Suomi.fi data exchange layer has been removed. Instructions on the Suomi.fi data exchange layer will be included in the register’s second rollout stage. A new chapter on user identification in connection with data retrieval has been added to the instructions. This concerns organisations that are testing the retrieval of authorities’ or credit information companies’ data. As of 15 August 2023, the day of new version releases and associated service breaks is Tuesday (previously Wednesday).

1 Purpose and objectives

These instructions are for operators participating in the Positive credit register’s stakeholder testing. They apply to the first stage of the register rollout, i.e. the reporting and requesting of information on consumer credits and loans comparable to them. The participants of the stakeholder testing include organisations that report information on loan contracts to the Positive credit register, organisations that use the loan data, credit information companies, and authorities that use the registered data. The focus in the stakeholder testing is on technical APIs. The content of the instructions may still change.

The purpose is that the stakeholders would test the functionality of the Positive credit register's APIs. The stakeholders can make use of the testing environment in their own development and testing. Advance testing enables smooth introduction of the register to all parties. On account of the testing, the register is expected to operate more smoothly while in production, and fewer errors are to be expected.

The testing allows stakeholders to make sure they are technically capable of reporting and requesting data. When testing the APIs, the stakeholders can also ensure that their own systems and processes work in the appropriate manner. Each stakeholder is responsible for building their own APIs and for ensuring their conformity to law.

2 APIs and services to be tested and their addresses

The focus of stakeholder testing is on technical APIs used to report and request data. This chapter lists the APIs and services to be tested as well as the addresses of the APIs whose testing started on 2 May 2023.

The testing of data requesting will start on 1 September 2023. Authorities and credit information companies will receive the API addresses separately.

Reporting data:

• APIs for reporting data on loan contracts and their addresses (REST)
  • New loans: https://api-testi.positiivinenluottotietorekisteri.fi/AddLoans
  • Changes to loans: https://api-testi.positiivinenluottotietorekisteri.fi/UpdateLoans
  • Payment transactions: https://api-testi.positiivinenluottotietorekisteri.fi/Repayments
  • Delayed amounts: https://api-testi.positiivinenluottotietorekisteri.fi/DelayedRepayments
  • End of loan contract: https://api-testi.positiivinenluottotietorekisteri.fi/TerminateLoans
• Batch status inquiry (REST) https://api-testi.positiivinenluottotietorekisteri.fi/GetBatchStatus
• Checking loan data (REST) https://api-testi.positiivinenluottotietorekisteri.fi/GetLoan

Requesting data, lenders:

• API for requesting a credit register extract (REST)
  • A request for a credit register extract: https://api-testi.positiivinenluottotietorekisteri.fi/GetCreditRegisterExtract

Requesting data, authorities:

• Data requesting service 
  • a new request, a list of requests or terminating a request
• Batch distribution (SFTP)
  • Comprehensive picture of credit stock
    • All loans
    • New and ended loan contracts
  • Loan report flow
    • Reports on loan contracts
  • Targeted sampling
    • Borrower’s loans
    • Lender’s loans
    • Targeted reports on loan contracts
  • Requests for credit register extracts
    • Lender’s requests for credit register extracts
    • Requests for credit register extracts relating to a certain borrower
    • All requests for credit register extracts
  • Data flow of incomes payment reports
    • Incomes payment reports
  • Data flow of reports on credit bans
    • Reports on credit bans

Data requests, credit information companies:

• Data requesting service 
  • a new request, a list of requests or terminating a request
• Batch distribution (SFTP)
  • Data flow of reports on credit bans
    • Reports on credit bans

2.1 Limitations

The present stakeholder testing does not include

• testing of the Positive credit register’s e-services for private individuals and organisations
• testing of sending information on the lenders’ existing credit stock

3 Schedule

Sign-up

Sign-up for stakeholder testing: 1 March–30 April 2023 and 1 August–31 August 2023.

If the testing stakeholder is a data notifier or both a data notifier and a data user, the sign-up period is 1 March–30 April 2023.

If the testing stakeholder is only a data user (for example, authorities and credit information companies), the sign-up period is 1 August–31 August 2023.

Please note: You can sign up for testing even after the sign-up period has ended.

Testing

Stakeholder testing takes place in two stages, and each stakeholder participates in one or both, depending on its role:

• testing of reporting data on loan contracts 2 May–31 Oct. 2023
• testing of requesting information 1 Sept. 2023–31 Jan. 2024

The schedules were set so as to ensure that we can take the stakeholders’ observations into account and make any corrections needed before rollout to production. After the above testing periods, the testing environment will still be accessible to stakeholders and they can test the latest API version there.

Stakeholder events and testing meetings will be held before and during the testing so as to allow stakeholders to discuss issues arising during the testing with the project and with other stakeholders.

Figure 1. Schedule.

3.1 Early testing opportunity for authorities

As an exception to these schedules, authorities using the register’s data can test APIs as of 2 May 2023. In early testing, authorities can call APIs in the testing environment. At this stage, however, there is no test database in the testing environment so it is not yet possible to test the actual requesting of data. The requesting of data can be tested according to the original schedule as of 1 September 2023.

If the testing stakeholder is an authority using data, they can sign up for limited early testing before the actual testing begins.

• Early testing starts on 2 May 2023.
• Actual testing of data requests 1 September 2023–31 January 2024.

4 Enter portal

The Enter portal is available for communication. It is the primary channel for communication between the stakeholders and the project to establish a positive credit register in matters related to testing.

One person from the testing organisation registers for the portal as the organisation’s master user. After the registration, the Master User can add persons participating in the testing as users of the portal. It is also advisable to add as users all individuals participating in the testing and dealing with the project in situations such as troubleshooting.

Through the portal, the users can send questions about testing, their testing observations, suspected errors, etc. to the project. Responses will be sent to the portal, and the person who sent the question will receive a message to their email address. The master user can follow the status of their organisation's tickets and thereby see the overall picture of the organisation's testing observations, for example. Basic users can view only their own tickets.

The portal also contains other information related to testing, such as links to testing instructions. In addition, the portal can be used to communicate about topical issues related to the testing environment, such as observations or corrections of errors.

Read the instructions on the use of the Enter portal.

5 Progress of testing

The testing starts with sign-up. Stakeholders test the technical APIs and report any errors and other observations to the project during the scheduled testing phase.

The different stages of testing are discussed in greater detail later in these instructions.

Figure 2. Stages of testing.

6 Sign-up for testing

You must sign up for stakeholder testing by completing the Stakeholder testing start notification available in the Enter portal. The testing start notification is filled in by the master user. The stakeholder accepts the terms and conditions of testing when signing up. Before sign-up, the organisation's Master User must add at least the testing contact person and technical contact person to the portal.

When signing up, the stakeholder

• accepts the terms and conditions of stakeholder testing
• estimates the date when the organisation will start testing
• specifies both a testing contact person and a technical contact person
• can sign up to test both the reporting of data and the requesting of data.

The project will process the testing start notification within two weeks. After this, the master user who filled in the testing start notification will receive artificial personal identity codes and an artificial Business ID for use in testing. The information related to the testing certificate will be delivered to the technical contact person assigned to testing. If the stakeholder signs up to test both the reporting of data and the requesting of data, the project will first send information for the testing of reporting data and, before 1 September 2023, the corresponding information for the testing of requesting data or credit register extracts.

If the information submitted in connection with signing up changes in the course of testing (for example, the testing contact person or technical contact person changes), the stakeholder must report this in the Enter portal as soon as possible. For more detailed instructions, see the instructions on the use of the Enter portal.

When a stakeholder signs up for testing, we do not examine whether they are required to submit reports or have the right to use the register’s data. In other words, participation in testing does not guarantee the right to use data at the production stage, for example. Before the rollout of the register, stakeholders sign up to the register as data notifiers and apply for data permissions.

Read more

Signing up to the Positive credit register as a data notifier

Instructions for lenders on how to request a data permission

Sign-up for stakeholders that are both data notifiers and data users

• The sign-up period is from 1 March to 30 April 2023, but you can sign up even after this period.
  • Testing of reporting data on loan contracts 2 May–31 October 2023
  • Testing of requesting credit register extracts 1 September 2023–31 January 2024

Sign-up for stakeholders that are only data notifiers

• The sign-up period is from 1 March to 30 April 2023, but you can sign up even after this period.
  • Testing 2 May–31 October 2023

Sign-up for stakeholders that are only data users

• The sign-up period is 1 August–31 August 2023, but you can sign up for testing even after this period.
  • Testing 1 September 2023–31 January 2024

6.1 Testing start package

Once the stakeholder’s sign-up request has been processed, the master user who filled in the testing start notification and the technical contact person will receive the information needed to start testing.

Lenders

• Artificial personal IDs
  • 100 IDs for the stakeholder’s own use
  • 500 IDs for the use of all the testing stakeholders
• Artificial business ID and name of organisation
• The project will also request a testing certificate for the artificial business ID. The information needed to retrieve the certificate will be sent to the technical contact person.

Authorities

• Artificial business ID and name of organisation
• The project will also request a testing certificate for the artificial business ID. The information needed to retrieve the certificate will be sent to the technical contact person.
• Data access profile

Credit information companies

• Artificial personal IDs
• Artificial business ID and name of organisation
• The project will also request a testing certificate for the artificial business ID. The information needed to retrieve the certificate will be sent to the technical contact person.
• Data access profile

7 Testing certificate

Each stakeholder needs their own testing certificate for testing the API. There are separate certificates for data notifiers and data users. If the stakeholder intends to test both the reporting and the requesting of data, they need two different types of certificates.

See chapter 8 for instructions concerning the activation of the user IDs needed to retrieve authorities’ or credit information companies’ data.

After the stakeholder’s master user has filled in the stakeholder testing start notification in the Enter portal, the stakeholder receives a testing certificate and an artificial business ID for use in the testing. To retrieve the testing certificate, the stakeholder needs identifiers, which will be delivered to the stakeholder's technical contact person by secure email after the sign-up. The technical contact person receives a secure email message containing the identifiers needed for retrieving the certificate. The message is sent within two weeks after the testing start notification has been submitted. To open the secure email, the technical contact person receives a PIN code by text message. The certificate must be retrieved within 14 days from the receipt of the messages. In other words, the certificate must be retrieved before the actual testing period.

However, if the stakeholder fails to retrieve the certificate within 14 days, they can request a new certificate by filling in the contact form for testing in the Enter portal.

The testing certificate is used only in the stakeholder testing environment during the stakeholder testing. The certificate needed for production use is different.

Read the instructions on the testing certificate

7.1 Other situations

Requesting additional certificates

If stakeholders need more testing certificates, they can request additional certificates by filling in and sending the contact form for testing in the Enter portal.

Request to deactivate a certificate

If the stakeholder wants the testing certificate to be deactivated, it can request deactivation by filling in and sending the contact form for testing in the Enter portal. The serial number of the certificate must be stated on the form.

Certificate’s period of validity

The testing certificate is valid for two years.

8 SFTP credentials needed for retrieving data

Authorities and credit information companies retrieve data using file transfer. The retrieval is done by using SFTP. The user identifies with the SFTP account. To sign in to the account, you need a user ID and the organisation’s private key (SSH public key authentication). This chapter describes how an organisation testing the retrieval of authorities’ and credit information companies’ data can start using SFTP credentials.

 

1. The master user registered in the Enter portal fills in the stakeholder testing start notification.

See the instructions on how to use the Enter portal

Once the stakeholder’s sign-up request has been processed, the project’s official will send a secure email to the technical contact person named in the start notification. The official will ask the technical contact person for the public key that the organisation has generated specifically for SFTP use.

2. The technical contact person receives the official’s secure email and generates a 2048-bit key pair by the RSA algorithm. The key pair must be new and different from the key pair used in the testing certificate. The key pair generated for the testing certificate or its public part cannot be used in the SFTP credentials.

3. The technical contact person takes the key’s public part and converts it into Open SSH format. The technical contact person sends the public key to the project by responding to the official’s secure email message.
The official receives the public key and saves it in the organisation’s SFTP account. The official then sends the SFTP account’s user ID back to the technical contact person via secure email.

4. The technical contact person receives the user ID and saves it. The stakeholder can now be identified by their user ID and private key when they retrieve data in the SFTP service.

9 Testing on behalf of another party

A stakeholder can authorise another party to perform testing on their behalf. This is possible, for example, when the stakeholder has outsourced the technical reporting or the requesting of data to another operator. In that case, the stakeholder required to submit reports or using the data can themselves sign up for testing, or the operator performing testing can sign up on behalf of the stakeholder.

Before signing up, the organisation must check who in the testing organisation acts as the technical contact person and retrieves the certificate. In connection with signing up, the details of the testing organisation’s technical contact person are given. The technical contact person is sent the information related to the certificate and retrieves the certificate.

The Enter portal can also be used when the stakeholder has outsourced testing and another operator is performing the testing on behalf of the stakeholder. The persons performing the testing can be added to the portal for purposes of communication. These individuals can also use the portal to process the observation forms.

10 Testing

The purpose of testing is to ensure that

• the APIs provided for stakeholders work correctly
• the data generated by the stakeholder’s information system complies with the requirements, and the stakeholder can report the data to the Positive credit register and check its accuracy in the register
• the stakeholder receives correct processing responses to their reports
• the stakeholder’s own processes and systems will handle various situations, such as errors, in the desired manner
• credit register extracts can be requested and generated successfully
• data is shown correctly in the credit register extracts
• data requests sent by authorities and credit information companies are successful
• data requested from the register can be used in the stakeholder’s own systems.

Each stakeholder tests the APIs they intend to use during production. In testing, it is advisable to proceed from simple basic cases to more complex test cases, testing all the stages and situations of different processes. We recommend that stakeholders start testing even if their own implementation is still unfinished. Stakeholders can test APIs in phase with their own implementation.

The project tested the register’s APIs and services internally before the stakeholder testing started. We recommend that stakeholders test different variations regarding their products and operating models, depending on what is relevant to them.

Stakeholders do not need to carry out performance testing in the register’s APIs. If the stakeholder intends to carry out their own performance testing in the APIs, the project must be notified of this a week in advance. Submit the notification by filling in the contact form in the Enter portal. The performance of the testing environment is not equivalent to that of the production environment.

Stakeholders must create relevant test cases for different situations of reporting and of requesting a credit register extract, taking account of changes and errors, as well as their own processes.

10.1 Testing environment

Stakeholders can test the Positive credit register in the stakeholder testing environment. The stakeholder testing environment is available 24/7, with the exception of scheduled service breaks or error situations, which will be responded to during office hours.

The stakeholder testing environment is available for testing the reporting of data as of 2 May 2023 and for testing the requesting of data as of 1 September 2023. New versions and replacement releases will be made available in the stakeholder testing environment during the testing. When a new version is released, the stakeholders will be notified with a delivery report on new functionalities, corrections made and defects known.

The stakeholder testing environment is common to all the testing stakeholders, so joint testing between different stakeholders is also possible.

10.2 Version releases in the testing period

New versions will be released to the testing environment throughout the stakeholder testing. New versions are released every two weeks, and they can include changes or corrections. The release day is Tuesdays in odd weeks. During the release, there will be a break in the testing environment from 1 apm to 5 pm. The break may end sooner. During the break, a banner notifying of the break will be displayed in the Enter portal. When the break is over, the banner is removed.

There is not necessarily content to release on each scheduled date. In critical situations, changes can also be introduced into the environment outside the planned schedule.
A delivery report is compiled from release content. The report will be available on the register’s website. A link to the delivery report will also be available in the Enter portal. The delivery report contains descriptions of the changes that have been made, as well as known defects.

The dates and times of the breaks and the published delivery reports are available on the Releases and delivery reports page.

If changes are made to the API descriptions, information on these changes will be provided separately.

10.3 Deviating processing rules of the testing environment

Some of the settings (configurations) and processing rules used in the stakeholder testing environment deviate from those used in production. Testing is possible only with such artificial customer IDs that are saved in the register's stakeholder testing environment. Testing with other customer IDs is not possible because no matching information is available in the register.

There are no processing rules related to dates in the stakeholder testing environment that would differ from the production environment.

The date on which the loan contract was concluded (ContractDate) is a required element in the New loans API. This concerns loans that are reported on 1 April 2024 or later. The same date requirement will also be in place in the stakeholder testing environment starting 1 April 2024. This means that the date of conclusion is voluntary information in the stakeholder testing environment until 31 March 2024.

10.4 Test data

Testing is performed with artificial test customer data, which the stakeholder’s master user receives after signing up. The test customer data contains personal identity codes. In addition, artificial Business IDs are provided, which the stakeholder can use as reassignees when testing the transfer of credit.

The project creates a range of income and benefit information, loan information, credit bans, and disputes of information for some test customer IDs. This information is needed for purposes of testing the requesting of credit register extracts.

Some of the test customer IDs are assigned specifically to the stakeholder, while others are in shared use. After signing up for testing, the stakeholder receives a list of the test customer IDs and their properties.

All data delivered to the testing environment is available for other testers using the testing environment. Data submitted to the testing environment when the reporting of data is tested will be utilised when the requesting of data is tested. For example, authorities can request test data submitted by lenders.

When stakeholders submit data linked to an artificial personal identity code during testing to the testing environment, they must ensure that the data is artificial or anonymised in accordance with the requirements of the separate anonymisation instructions. The stakeholders are responsible for seeing that the test data they provide is artificial or anonymised. The anonymisation instructions will be published at a later date. See the instructions on the anonymisation of test data for more information.

10.5 Stakeholder’s own test IDs

The stakeholder can add a moderate amount of their own test customer data to the stakeholder testing environment. If necessary, the stakeholder can also provide the project with a foreign business ID for which a testing certificate can be ordered. The stakeholder is responsible for seeing that the IDs they provide cannot be connected to natural persons or their data. The project does not check or anonymise IDs submitted by stakeholders.

If the stakeholder wishes to submit their own test customer data or a foreign business ID, they must contact the project by filling in the contact form in the Enter portal. The project will give the stakeholder more detailed instructions for submitting data. Only IDs that the project has added to the testing environment can be used in testing.

If the test customer data is generated by using production data, the data must be anonymised in such a manner that it cannot be re-engineered. All personal data must be de-identified in such a way that the customer cannot be identified. See the instructions on the anonymisation of test data for more information.

Read more about legislation governing test data:

• Article 25 of the EU General Data Protection Regulation (gdprinfo.eu)
• Article 32 of the EU General Data Protection Regulation (gdprinfo.eu)

11 Testing observations and reporting

Stakeholders report on their observations through the Enter portal.

If the tester suspects an error, they can check the delivery report to see whether the error has already been reported.If the error has not been reported previously, you can fill in the observation form. Report the situation in which the error was detected as accurately as possible. You may also add screenshots or other necessary attachments to the form. The observation form contains fields for different types of information, so the form itself tells you what information you must give.

Read more about filling in the observation form in the instructions on the use of the Enter portal.

12 Communication and support during testing

Information about stakeholder testing is available on the register's website and in the Enter portal. During the testing, stakeholder events about testing will also be held.

During the testing, the project to establish a positive credit register will keep the stakeholders informed of the following topics, for example:

• API descriptions and their updates
• disruptions in the testing environment
• new versions of the testing environment
• additional fixes installed in the testing environment in addition to the scheduled version updates
• any downtime of the testing environment
• delivery reports
• upcoming stakeholder events
• other topics and news to be communicated.

The Enter portal is the primary channel for communication between the stakeholder and the project during the testing. The stakeholder sends the project questions and observations related to testing through the Enter portal and receives the project's answers in the portal.

When signing up for testing, the stakeholder must submit the contact information of the testing contact person. If necessary, the project may notify the contact person by email about testing-related situations.

13 Key terms

Anonymisation
Removal or irrevocable alteration of identification information in such a way that the parties cannot be identified.

Enter portal
The primary means of communication between the testing organisation and the project in matters related to testing. Instructions, bulletins and topical information related to stakeholder testing are published in the Enter portal. Stakeholders can also send their questions and testing observations through the portal.

Project
The project to establish a positive credit register answers for the development of the register. The project supports stakeholders in the stakeholder testing.

API
An access point according to certain definitions, used for sending data between an outside party and the register. The Positive credit register has API services for reporting data, requesting credit register extracts, and requesting and receiving data batches. In the definition of the API, the data transmission method (protocol) and the content and format of the data to be transmitted are specified.

Stakeholders
The Positive credit register’s stakeholders include all its users, such as parties required to submit reports, users of credit register extracts, credit information companies, authorities and individuals.

Technical contact person
A person to whom information for retrieving a certificate is sent. The person is specified by the testing organisation in a testing start notification.

Testing start notification
A testing start notification is submitted electronically through the Enter portal. In the notification, the stakeholder reports the information needed to start testing and the services to be tested to the Positive credit register, and accepts the terms and conditions of the testing environment.

Testing contact person
The testing organisation’s primary contact person in matters related to the testing of the Positive credit register. There may be one testing contact person. The project will contact the testing contact person, if needed, in matters related to testing.

Testing environment
The stakeholder testing environment for testing the Positive credit register.

Test customer
Artificial company or individual in the stakeholder testing environment with artificial customer ID.

Test data
Data batch used by the tester in the testing environment, containing data on artificial test customers.

Data users
Operators using the Positive credit register’s data and having a statutory right to obtain data from the register to perform their duties. Data users include lenders, credit information companies, and authorities using the registered data and supervising the operation of the register.

Data notifiers
Operators with a statutory obligation to send information to the Positive credit register. Notifiers include financial, payment and credit institutions, and Kela.

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

A test certificate is for the stakeholder testing environment. An access right to and a certificate 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.

More terminology in the Positive credit register’s glossary (suomi.fi).