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.03
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. |
| 1.02 | 25.4.2024 | Clarification to chapter 2 that status API returns COMP also when no hits were found. |
| 1.03 | 4.4.2025 | Added description for using PART response code in chapter 2. |
Table of contents
- Introduction
- Query for bank and payment account information from the aggregating application
- Information security
- 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
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.
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:
- The Client sends a query message to the Query Endpoint.
- The Query Endpoint returns a key as a response (ResultKey).
- The Client waits for a while (see POLLING_INTERVAL) and sends a status query containing the key to the Status Endpoint.
- The Status Endpoint returns a response code (StatusResponseCode). The code is either
a. NRES if there are no ready results yet,
b. PART if some but not all results are ready, or
c. COMP if all results are ready. - If the query produced any hits (PART or COMP response), a list of keys (ResultKey) for retrieving the responses is also returned.
- If the code is
a. NRES, the Client returns to step 3, or the process ends. b. COMP and hits were found, the client sends a search result query to the Result Endpoint using one of the keys received in step 5.
c. COMP but no hits, the process ends.
d. PART, the Client chooses to either- Wait for more responses to be ready (return to step 3) or
- Retrieve the responses that are ready, if hits were found (steps 6.c. and 6.d.)
- The Result Endpoint returns the search result message corresponding to the key that was sent.
- If there still are search results waiting for retrieval, the process will return to step 6.c. to repeat the search using the next key.
- If the code returned by Status Endpoint was PART,
a. The Client returns to step 3 to query if new responses (new ResultKeys) are ready, or
b. If further queries are not needed or feasible, the process ends. - If all search results have been retrieved, the process ends.
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 query has been completely processed, all data sources have responded and possible results are available. |
| NRES | NoResponseYet | Response not provided yet. | The data sources have not yet responded to the query, make a new query later. |
| PART | PartialResponse | Response is partially provided. | The query is partially processed, response from at least one data source is still expected. Possible results from responses so far are available. |
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:
- If a query is not yet complete, NRES will be returned as the status code in the Auth.002 schema’s RspnSts field.
- If a query is complete, COMP will be returned as the status code in the Auth.002 schema’s RspnSts field along with the identifier used in the status query in the fin.021 submessage and a list of identifiers using which results can be retrieved from the result API.
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:
- datasourceOrganisationId: Business id or VAT id of the datasource
- errorCode: in case of error, either the error code returned from the datasource or one generated by Aggregating application, see 4.8 Error management
| 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: