View on GitHub

account-register-aggregating-application

Tiedon hyödyntäjien käyttöönoton ja ylläpidon ohje, koostava sovellus
Koostavan sovelluksen rajapintakuvaus
Deployment and maintenance instructions for data users, Aggregating Application
Instruktioner för uppgiftsanvändare om ibruktagande och underhåll, sammanställningsprogrammet
Beskrivning av sammanställningsprogrammets frågegränssnitt

Description of the aggregating application’s query API

Document version 1.01

Version history

Version Date Description
1.0 7.2.2023 Version 1.0
1.01 29.6.2023 Added schema for fin.012 and a new example message. Updated chapter 4.2 with two new data elements. One is used to aim the query to specific datasource(s), the other to mark that the query is related to an international/cross-border information request. Also updated chapter 4.7 with use of InvstgtnSts NOAP in response messages.

Table of contents

  1. Introduction
  2. Query for bank and payment account information from the aggregating application
  3. Information security
  4. Query API of the aggregating application
    4.1 Message structure of the SOAP operations of the query API
    4.2 Query API
    4.3 Status API
    4.4 Result API
    4.5 Message extension Fin020 (QueryResultRequest)
    4.6 Message extension Fin021 (QueryResultResponse)
    4.7 Use of the ReturnIndicator1 element
    4.8 Error management
    4.9 Example messages

1. Introduction

1.1 Terms and abbreviations

Abbreviation or term Definition
Interface A standard practice or connection point that allows the transfer of information between devices, programmes and the user.
WS (Web Service) Software operating in a network server, providing services for use by applications through standardised internet connection practices. The data retrieval system provides information queries as a service.
Endpoint An interface service available at a certain network address.
WSDL (Web Service Description Language) A structural description language describing the functionalities provided by the web service.

1.2 Purpose and scope of the document

This document supplements the regulation issued by Finnish Customs on the Bank and Payment Accounts Control System. The purpose of this document is to issue instructions for the query API of the aggregating application. This document is supplemented by the deployment and maintenance instructions for data users.

1.3 References

Data retrieval system WSDL

fin.020.001.01

fin.021.001.03

fin.012.001.03

Guidelines on the information security of e-services

1.4 General description

Finnish Customs has established an Account Register Project to implement the bank and payment account monitoring system, based on Finnish legislation and implementing EU Directive 2018/843.

This document describes the aggregating application’s APIs.

2. Query for bank and payment account information from the aggregating application

This chapter describes the query of bank and payment account information from the aggregating application.

Figure 2.1 presents the query process as a flow diagram.

Query for information from the aggregating application
Figure 2.1. Query for information from the aggregating application

Table 2.2 presents the meaning of different variables in the flow diagram.

Table 2.1. Variables in the flow diagram

Muuttuja Kuvaus
POLLING_INTERVAL Polling interval; the time the client has to wait before the next query is 1 minute. If a client’s polling interval is too short, the server may reject transaction processing (error code 3, see Table 4.12.1).
POLLING_TIME_LIMIT The permitted time limit for polling, after which it will be stopped. If no response is still received, a new query must be made or the case must be transferred to manual processing.

The flow of the query is as follows:

  1. The client sends a query message to the query API.
  2. The query API returns a key as a response (resultKey).
  3. The client waits for a while (see POLLING_INTERVAL) and sends a status query containing the key to the status API.
  4. The status API either
    a. returns code NRES if the results are not yet ready, or
    b. returns code COMP and a list of keys.
  5. If the code is NRES, the client returns to step 3.
  6. If the code is COMP, the client sends a search result query to the result API using one of the keys received in step 4 b.
  7. The result API returns a search result message corresponding to the key that was sent.
  8. If there still are search results waiting for retrieval, the process will return to step 6 to repeat the search using the next key.
  9. If all search results have been received, the process will end.

The codes to be returned are defined in ISO code set StatusResponse1Code, and the use of its values is described in Table 2.2.

Table 2.2. Use of StatusResponse1Code values

Code Name Definition Description
COMP CompleteResponse Response is complete. The response message includes the retrieval results.
NRES NoResponseYet Response not provided yet. The response message does not include retrieval results; make a new query later.
PART PartialResponse Response is partially provided. Not used.

Result retention time in the aggregating application

Results are deleted once they have been retrieved. Complete results are retained for at most 24 hours after their completion, during which the results must be retrieved.

3. Information security

Information security practices follow the same principles described in the specification of the query API of the data retrieval system.

4. Aggregating application API

The API will be implemented as a SOAP/XML web service, whose WSDL has been published in conjunction with the query API description of the data retrieval system.

SOAP protocol version 1.1 will be used.

ISO 20022 code set references will be used in the messages. The code sets are available on the ISO 20022 page External Code Sets.

The aggregating application API consists of three endpoints:

4.1 Message structure of the SOAP operations of the query API

The message structure used in the API is identical at the main level to the specification of the query API of the data retrieval system published by Finnish Customs. In addition, the fin.020 and fin.021 submessages have been defined for the API to transmit the identifiers required to check the retrieval status and retrieve results.

4.2 Query API

Messages sent to the query API are similar to the messages used in the query API of the data retrieval system. Message extension fin012 has two additional elements that are not used in data retrieval systems’ messages: RequestedDataSources and InternationalRequest. RequestedDataSources element is used to aim the query to one or several data sources (data retrieval systems and account register). The query with RequestedDataSources element is only forwarded to data source(s) specified in the element. InternationalRequest element is used to mark that the query is related to an international/cross-border information request based on the directive on using financial information ((EU) 2019/1153) article 19 and national anti-money laundering act (444/2017) 4 § in chapter 2.

Response messages also follow the same structure, while the fin.021 message is used as a submessage in the auth.002 message to indicate the identifier of the received query. This identifier is used to check the query status in the status API. In status API, other submessages return status NFOU, which is insignificant in this case.

4.2.1 Message extension InformationRequestFIN012

The submessage schema is defined in the fin.012 file. The message extension is appended to the Xpath location of the ISO 20022 message listed in the table.

Name [min..max] Type Description Liitetään sanomaan XPath
InformationRequestFIN012       auth.001 /Document/InfReqOpng/SplmtryData/Envlp
    AuthorityInquiry [1..1] AuthorityInquirySet Authority details associated with the query    
    AdditionalSearchCriteria [0..*]   Used for the search by safety-deposit box ID.    
    RequestedDataSources [0..1] RequestedDataSources Datasource or datasources that will receive the query. If the element is missing from the message, the query is sent to all datasources.    
    InternationalRequest [0..1] boolean Value “true” is used if the query is related to an international information request.    

AuthorityInquirySet

Name Type In use Description
AuthorityInquirySet      
    OfficialId Max140Text Yes Identifier of the official that is making the query
    OfficialSuperiorId Max140Text Yes Identifier of the official’s superior

RequestedDataSources

Name [min..max] Type Description
RequestedDataSources      
    DataSourceOrgId [1..*] Max35Text Datasource’s business identity code

4.3 Status API

Messages sent to the status API consist of the same message content as queries. In addition, the identifier received as the query API’s response is transmitted through the fin.020 submessage.

Response messages are identical to the query API’s responses, plus:

4.4 Result API

Messages sent to the result API consist of the same message content as queries. In addition, the identifiers received as the status API’s response are transmitted one-by-one through the fin.020 submessage.

Response messages are identical to the response messages of the data retrieval system’s query API, containing actual search results in accordance with the schema. In addition, the result identifier is returned in the fin.021 submessage and the business ID of the data retrieval system that returned the result is returned in the datasourceIdentifier attribute.

4.5 Message extension Fin020 (QueryResultRequest)

The submessage schema is defined in the fin.020 file. The message extension is appended to the Xpath location of the ISO 20022 message listed in the table.

Name [min..max] Type Description Appended to message XPath
QueryResultRequest       auth.001 /Document/InfReqOpng/SplmtryData/Envlp
    ResultKeyList [1..1] ResultKeyList A list of the identifiers of returned information    
Name [min..max] Type Description Notes
ResultKeyList        
    ResultKey [1..n] Max256Text UUID of the query or result Only one value at a time is supported for now

4.6 Message extension Fin021 (QueryResultResponse)

The submessage schema is defined in the fin.021 file. The submessage is returned in the data retrieval system’s response message in the ReturnIndicator1 element similarly to other submessages.

The following data is returned as attributes of the ResultKeyList element:

Name [min..max] Type Description Appended to message XPath
QueryResultResponse       auth.002 /Document/InfReqRspn/RtrInd/InvstgtnRslt/Rslt
    QueryKeyList [0..1] QueryKeyList A list of the identifiers used in query    
    ResultKeyList [0..1] ResultKeyList A list of the identifiers of returned information    
Name [min..max] Type Description Notes
QueryKeyList        
    ResultKey [1..n] Max256Text UUID of the result  
ResultKeyList        
    ResultKey [1..n] Max256TextAllowedEmpty UUID of the result or empty in case of a query error Optional attributes: datasourceOrganisationId and errorCode

4.7 Use of the ReturnIndicator1 element

ReturnIndicator1 includes the presence of a single type of search result as in the response messages of the data retrieval system’s query API. The fin.021 submessage is returned in this element similarly to other submessages returned in the query.

XPath Type Description
RtrInd/AuthrtyReqTp/MsgNmId Max35Text Includes the message ID of the message extension (fin.021.001.03))
RtrInd/InvstgtnRslt InvestigationResult1Choice Returning Rslt element type SupplementaryDataEnvelope1, which includes one of the submessages (fin.021, supl.027, fin.013 or fin.002) or the InvstgtnSts element. InvstgtnSts is returned using code NFOU, if no information can be found using the identifier used in the query. InvstgtnSts is returned using code NOAP in case a query with the name of a natural or legal person has multiple hits in one party’s data in account register.

4.8 Error management

Error management and returned codes follow the specifications of the WS message traffic scenarios in the query API chapter for the data retrieval system’s query API, where applicable.

The response from Status API can be an empty ResultKey along with an errorCode to indicate that something has gone wrong with the query. No datasources have been queried at this point and there won’t be any results to fetch. Currently “TIMEOUT” is the only produced errorCode in this case.

The responses from Status and Result APIs include also information of possible errors concerning certain datasources. This information is returned in errorCode attribute of the ResultKey element.

It is not possible to query information concerning time period before September 1st 2020 from the aggregating application. The query API rejects queries where investigation period (InvstgtnPrd) is before that.

4.9 Example messages

Examples of each query message and their responses are available in the examples folder: