finAPI PSD2 Integration
Concept
Version 4.0, Stand: 2020-03-20
Content
| Table of Contents | ||
|---|---|---|
|
Glossary
...
Term
...
Description
...
PSD2
...
Payment Service Directive 2 of the European parliament and of the council
...
MFA
MSA
SCA
...
Multi Factor Authentication
Multi Step Authentication
Strong Customer Authentication
A second factor is needed for authentication towards the bank.
...
Interface
...
New Object in finAPI to select, which technical interface should be used to connect to a bank.
Values:
- XS2A (new API with the PSD2-standard)
- FINTS_SERVER
- WEB_SCRAPER
...
Capabilities
...
Defines the provided capabilities of each interface for an account. Currently in finAPI named "supportedOrders".
...
Detailed Consent
...
The bank requires the IBANs of the accounts, for which data shall be downloaded. The IBANs must be submitted
Version History
...
Version
...
Description
...
Published
...
1.0
"Concept PSD2 Integration (AIS)"
...
Introduces the overall changes made to finAPI's service, including newly introduced service in regards of the PSD2.0 and the Embedded SCA-Approach.
...
23rd of May, 2019
...
2.0
"Concept PSD2 Integration (AIS)"
...
Added changes in the service specific to the usage of the Redirect SCA-Approach and Detailed Consent.
- Chapter 1 a
- Chapter 2, Bulletpoints 7, 8, 9
- Chapter 5, Bulletpoints 5, 6, 7
- Chapter 6, Bulletpoints 3, 4, 5, 6
- Chapter 7, Bulletpoints 3, 4, 5
- Chapter 9 b
- Chapter 10 b
- Chapter Breaking Changes on Go-Live, 2
...
7th of June, 2019
...
Chapter Breaking Changes on Go-Live, 3
...
11th of June, 2019
...
3.0 "Concept PSD2 Integration (AIS + PIS)
...
Added changes in the service specific to the usage of the PIS-Services in the different approaches
- Chapter 4, Bulletpoint 6
- Chapter 5, Bulletpoints 3 and 4 – multiStepAuthentication
- Chapter 6 – multiStepAuthentication
- Chapter 7 – multiStepAuthentication
- Chapter 12 b
- Chapter 13
- Chapter 14 a - d
- Chapter Breaking Changes on Go-Live, 3
...
8th of July, 2019
...
Chapter 14 d – Bulletpoints 3 – 5 are not relevant for WebForm-Users
...
29th of July, 2019
...
- Chapter 8 - "finTSProductRegistrationNumber" was added
- Additional Information was changed
...
30th of July, 2019
...
| Note |
|---|
...
Color
...
Description
...
Red
...
Deprecated and to be removed
...
...
Changes introduced regarding the PSD2
...
Blue
...
Elaboration of the comment/changes
...
Purple
...
Elaboration of the comment/changes
1. General note about bank connection import/update:
After the PSD2 version of the finAPI REST API goes live, the import of all data for a bank connection will require connecting to different technical interfaces (XS2A, FinTS and Webscraping), that may require different login methods with different credentials and multi-factor-authentications, and that provide different sets of data. The different interfaces will require separate authentication to be performed by the user. The fact that the existence of separate interface cannot be hidden from the user is reflected in finAPI's service structure. Rather than hiding the different interfaces below the service layer, the interface object shows up in finAPI's services and has to be dealt with explicitly.
finAPI allows you to collect all data of a certain bank connection within one bank connection resource, with a shared list of accounts. But all other information, e.g. about the login to the interfaces or the capabilities of the accounts, will be explicitly split by interfaces. Thus, with the PSD2 integration and the explicit separation of the different interfaces, the general approach to import a user's bank connection in the future will be to first let a user select the preferred initial interface and trigger the import, and then iterate sequentially over all further supported interfaces of the bank and use the "Connect interface" service for each of those interfaces. Similarly, when updating existing bank connections, the client should iterate all connected interfaces and trigger the "Update bank connection" service for each interface sequentially; this will also be how finAPI's automatic batch update works in future.
a. Redirect Approach & Detailed Consent
...
- XS2A Redirect Approach – this means that for the bank login, the user must be directed to a website that is provided by the bank and in which one has to enter one's credentials. After the user has entered one's credentials on this website, the user will be redirected back to a callback URL that the client needs to provide. The callback includes the authorization data that the client then needs to forward to finAPI, which allows finAPI to complete the user login and access the user's data.
- Detailed Consent – this means that for the bank login, the client must ask the user for a set of IBANs which the client needs to pass to finAPI together with the user's credentials. finAPI will be able to download data only for those accounts that have been specified.
NOTE: The API changes for both the Redirect Approach and the Detailed Consent only affect customers that have their own regulatory license and do not use finAPI's Web Form. Customers that use the Web Form do not have to deal with these API changes, because the Web Form will be handling the Redirect and Detailed Consent itself.
NOTE: If a bank offers more than one approach, finAPI chooses automatically the approach which we think is best. In the most cases this will be the embedded or redirect approach.
b. Decoupled Approach
As the PSD2 and the Berlin Group specifications define three different approaches - Embedded, Redirect and Decoupled - this document contains now an explanation of how the Decoupled Approach is implemented in the finAPI. The decoupled approach is essentially a modified version of the embedded approach: the end-user still must provide his bank credentials to the API, and then he might be asked to select a preferred strong customer authentication (SCA) method. And then - depending on the chosen SCA method and/or on the bank’s preferences - the embedded or decoupled approach will be used to complete the authentication process. And here is the difference between embedded and decoupled approaches: in case of a decoupled approach, an authentication process is completed by direct communication between the end-user and the bank. Neither the client application nor finAPI itself are involved into this process, and the only a way to know that the authentication is completed, is to periodically check its status.
2. Changes to Resource Bank
...
Old
...
New
...
{
"id": 277672,
"name": "FinAPI Test Bank",
"loginHint": "...",
"bic": "TESTBANKING",
"blz": "00000000",
"blzs": [],
"loginFieldUserId": "Onlinebanking-ID",
"loginFieldCustomerId": "Kunden-ID",
"loginFieldPin": "PIN",
"isCustomerIdPassword": true,
"isSupported": true,
"supportedDataSources": [
"FINTS_SERVER",
"WEB_SCRAPER"
],
"pinsAreVolatile": true,
"location": "DE",
"city": "München",
"isTestBank": true,
"popularity": 95,
"health": 100,
"lastCommunicationAttempt": "",
"lastSuccessfulCommunication": ""
}
...
{
"id": 277672,
"name": "FinAPI Test Bank",
"bic": "TESTBANKING",
"blz": "00000000",
"isSupported": true,
"location": "DE",
"city": "München",
"isTestBank": true,
"popularity": 95,
"health": 100,
"interfaces": [
{
"interface": "FINTS_SERVER",
"tppAuthenticationGroup": null,
"loginCredentials": [
{
"label": "Onlinebanking-ID",
"isSecret": false,
"isVolatile": false
},
{
"label": "PIN",
"isSecret": true,
"isVolatile": false
}
],
"properties": [],
"loginHint": "..."
},
{
"interface": "XS2A",
"tppAuthenticationGroup": {
"id": 1,
"name": "AirBank XS2A CZ"
},
"loginCredentials": [],
"properties": [
"REDIRECT_APPROACH",
"DETAILED_CONSENT",
"DECOUPLED_APPROACH"
],
"loginHint" : "...",
"health" : 100,
"lastCommunicationAttempt" : "...",
"lastSuccessfulCommunication" : "...",
}
],
"lastCommunicationAttempt": "",
"lastSuccessfulCommunication": ""
}
- "supportedDataSources" have been only informational so far. This will change: We will make the different sources (now known as "interfaces") more explicit in the API, because both clients and users will have to understand the differences between the interfaces. The interface will have to be used explicitly and independent of each other (see other services below).
- Aside from the previously existing interfaces "FINTS_SERVER" and "WEB_SCRAPER", we will add a new interface "XS2A" in the "interfaces" set, which reflects the PSD2 interface. The XS2A interface will for most banks have the limitation to return only data for payment accounts (=checking accounts and in rare cases certain credit cards).
- We will move the login fields and login hint into the respective interfaces, because different interfaces might require different login data
- While moving the login fields into the interfaces, we also refactor it to a more dynamic data structure. Instead of a set of pre-defined login fields (bankingUserId, bankingCustomerId, bankingPin), each interface can now have an arbitrary set of login fields, where each field is labeled for identification, and flagged with further informational fields like "isPassword" etc
- Note that the loginCredentials might be empty, as some interfaces may not even provide any login through our API (for example, in Berlin Group Redirect Approach, the user will be directed to the bank website to enter his credentials)
- The fields which are marked red will be flagged deprecated and removed at some later point after the go-live of PSD2 integration. As long as they exist, they will be still used for the current logic (when not using the new fields)
- "tppAuthenticationGroup" is a new field. Some banks in order to improve security of the communication require authorization not only of the end-user but also of the application that interacts with the bank API. This authorization is performed by sending additional data (clientId & client secret or just API key - depending on the bank's requirements) in the body of every request to the API. Since this requirement of the additional authorization varies from bank to bank, the presence of the TPP authentication group in the interface defines such a requirement for a specific bank. Also, some banks can share the same set of credentials, and this fact is represented in our API: those banks will be connected to the same TPP authentication group. So that you upload TPP credentials once only and they can be used for all connected banks.
- The new "properties" field is a part of the bank interface definition.
- It may be empty, and will in fact be left empty for all FINTS_SERVER or WEB_SCRAPER interfaces.
- For the XS2A interfaces, the field may contain a set of one or more specifics that apply to the XS2A interface for the particular bank, and that provide information that is required for the client to know how to execute certain finAPI services.
- Currently, the properties set can contain the following constants:
- REDIRECT_APPROACH – this means that the client needs to pass a redirectUrl when calling a service that connects to the bank's XS2A interface (see service changes below)
- DETAILED_CONSENT – this means that the client needs to pass a set of accountReferences (IBANs) when calling a service that connects to the bank's XS2A interface (see service changes below)
- DECOUPLED_APPROACH – this means that the bank supports decoupled SCA methods and the client should expect an appropriate response from the API (see service changes below)
- The "health" field moved from bank level to interface level and gives now the status of the interface of the bank. This is a value between 0 and 100, depicting the percentage of successful communication attempts with the bank via this interface. Successful means in this context we did not receive a technical error trying to establish a communication with the bank.
- The "lastCommunicationAttempt" field moved from bank level to interface level and gives the time of the last communication attempt with this interface during an import, update or connect interface.
- The field "lastSuccessfulCommunication" moved from bank level to interface level and gives the time of the last successful communication with this bank during a bank connection import, update or connect interface.
...
- The request params "supportedDataSources" and "isSupported" will be flagged deprecated and be removed at some later point after the go-live of PSD2 integration. Until then, there will not be a change in the list of returned banks (e.g.: Banks that will support only new XS2A interface will not be returned when searching for "isSupported").
- A new field "supportedInterfaces" will be added, which also regards XS2A, but which will work slightly different (the current supportedDataSources is an AND-join of the given values, while the new supportedInterfaces will be an OR-join).
- The field "pinsAreVolatile" will be flagged deprecated and removed at some later point after the go-live of PSD2 integration, because in future, the volatile fields may depend on the interface. If it is a required feature for a client to filter banks that have volatile fields, the client must do this filtering on its side.
4. Changes to Resource Bank Connection
...
Old
...
New
...
{
"id": 1,
"bankId": 277672,
"bank": {
"id": 277672,
"other fields": "are removed for brevity (see Resource Bank)"
},
"name": "Bank Connection",
"bankingUserId": "XXXXX",
"bankingCustomerId": "XXXXX",
"bankingPin": "XXXXX",
"type": "DEMO",
"updateStatus": "READY",
"categorizationStatus": "READY",
"lastManualUpdate": {
"result": "INTERNAL_SERVER_ERROR",
"errorMessage": "Internal server error",
"errorType": "TECHNICAL",
"timestamp": "2018-01-01 00:00:00.000"
},
"lastAutoUpdate": {
"result": "INTERNAL_SERVER_ERROR",
"errorMessage": "Internal server error",
"errorType": "TECHNICAL",
"timestamp": "2018-01-01 00:00:00.000"
},
"twoStepProcedures": [
{
"procedureId": "955",
"procedureName": "mobileTAN",
"procedureChallengeType": "TEXT",
"implicitExecute": true
}
],
"ibanOnlyMoneyTransferSupported": true,
"ibanOnlyDirectDebitSupported": true,
"collectiveMoneyTransferSupported": true,
"defaultTwoStepProcedureId": "955",
"accountIds": [],
"owners": [],
"furtherLoginNotRecommended": true
}
...
{
"id": 1,
"bank": {
"id": 277672,
"other fields": "are removed for brevity (see Resource Bank)"
},
"name": "Bank Connection",
"type": "DEMO",
"updateStatus": "READY",
"categorizationStatus": "READY",
"interfaces": [
{
"interface": "FINTS_SERVER",
"loginCredentials": [ ** in suggested order*
{
"label": "Onlinebanking-ID",
"value": "XXXXX"
}
],
"defaultTwoStepProcedureId": "955",
"twoStepProcedures": [
{
"procedureId": "955",
"procedureName": "mobileTAN",
"procedureChallengeType": "TEXT",
"implicitExecute": false * whether follow-up call is required or not (in case of import/update bank connection: retry with challengeResponse)
}
],
"lastManualUpdate": {
"result": "INTERNAL_SERVER_ERROR",
"errorMessage": "Internal server error",
"errorType": "TECHNICAL",
"timestamp": "2018-01-01 00:00:00.000"
},
"lastAutoUpdate": {
"result": "INTERNAL_SERVER_ERROR",
"errorMessage": "Internal server error",
"errorType": "TECHNICAL",
"timestamp": "2018-01-01 00:00:00.000"
},
"aisConsent": {
"status": "PRESENT",
"expiresAt": "2019-07-20 09:05:10.546"
}
}
],
"accountIds": [],
"owners": [],
"furtherLoginNotRecommended": true
}
- Similar to the banks, the bank connections will have integrated the different interfaces more explicitly. The "interfaces" list will contain the set of connected interfaces for the bank connection, each providing the following data:
- the stored login credentials for that interface. Non-secret fields will always be stored implicitly (same as the "bankingUserId" currently).
- the set of two-step procedures that the interface supplies, and the stored default two-step procedure for the interface.
- information about the last manual or automatic update that was performed with the respective interface.
- information about the current consent stored for the respective interface.
- An interface gets "connected" (i.e. added) to a bank connection on the initial import, as well as via the new service "Connect interface".
- An interface gets "disconnected" (i.e. removed) from a bank connection via the new service "Disconnect interface".
- The fields which are marked red will be flagged deprecated and removed at some point after go-live of PSD2 integration. As long as they exist, they will be still used for the current logic (when not using the new fields).
- The fields about money transfer/direct debit support will also be marked as deprecated because they will be replaced by new capabilities of the account resource (see below).
- "aisConsent": If this field is set, it means that this interface is handing out a consent to finAPI in exchange for the login credentials. finAPI needs to use this consent to get access to the account list and account data (i.e. Account Information Services, AIS). If this field is not set, it means that this interface does not use such consents. The status can be PRESENT or NOT_PRESENT. Once the consent is issued, it's automatically stored in the finAPI storage regardless of the "storeSecrets" flag (see below).
- defaultTwoStepProcedureId moved to interfaces. To reduce user-involvement and MultiStepAuthentication errors, we have implemented a feature that allows to reuse the same twoStepProcedureId in bank connection update calls. Once a user has successfully imported a bank connection, we recommend to store the used two step procedure ID as default procedure for future updates or payments. (see Edit bank connection)
5. Changes to Service "Import a new bank connection"
...
Old
...
New
...
{
"bankId": 277672,
"bankingUserId": "123456",
"bankingCustomerId": "123456",
"bankingPin": "123456",
"storePin": true,
"name": "Bank connection",
"skipPositionsDownload": false,
"loadOwnerData": false,
"maxDaysForDownload": 365,
"accountTypeIds": […]
"challengeResponse": "0123",
"multiStepAuthentication": {
"hash": "c7af602c031117458affd825305fb56d",
"challengeResponse": "0123"
}
}
...
{
"bankId": 277672,
"interface": "FINTS_SERVER",
"loginCredentials": [
{
"label": "Onlinebanking-ID",
"value": "myID"
},
{
"label": "PIN",
"value": "myPIN"
}
],
"storeSecrets": true,
"name": "Bank connection",
"skipPositionsDownload": false,
"loadOwnerData": false,
"maxDaysForDownload": 365,
"accountTypes: [
"Checking"
],
"redirectUrl": "...",
"accountReferences": [
{
"iban": "..."
}
],
"multiStepAuthentication": {
"hash": "c7af602c031117458affd825305fb56d",
"challengeResponse": "0123",
"twoStepProcedureId": "955",
"redirectCallback": "bankParam1=X&bankParam2=Y",
"decoupledCallback": true
}
}
- When importing a bank connection, the interface that should be used must be declared, together with the login credentials (if any required). Temporarily, though, the "interface" field will be optional, in order to avoid breaking changes. It is important, to import the "XS2A" interface first (if supported by the bank), then the "FINTS_SERVER" interface (if supported by the bank) and at last the "WEB_SCRAPER" interface.
- The "storePin" field will be changed to "storeSecrets field, because there can be multiple password fields in the set of credentials.
- The "challengeResponse" field will be moved out from top-level into a new complex field "multiStepAuthentication". This new field will also contain two other new fields "twoStepProcedureId", "redirectCallback" and "decoupledCallback".
- The twoStepProcedureId must be used when multi-step-authentication (MSA) is required and the user must select a two-step-procedure. It works very similar to the already existing "challengeResponse" field, which is also used for MSA context. For more information about this, see changes in the chapter "Changes to ErrorMessage" below.
- The fields which are marked red will be flagged deprecated and removed at some point after go-live of PSD2 integration. As long as they exist, they will be still used for the current logic (when not using the new fields).
- redirectUrl: In case the service is called with interface = XS2A, and the interface has the property REDIRECT_APPROACH, then the client must pass a URL here to which the user will be redirected from the bank's website after he has entered his credentials. The redirectUrl must have the HTTPS protocol. When the Redirect Approach is used, the services will return with HTTP Code 510 and an ErrorMessage entity, as described further below in this document. This field is only mandatory if the web form flow is not used, otherwise the web form itself will take care of the whole redirect flow.
- redirectCallback: This field must be passed when the service is re-triggered by the client after the user has entered his credentials on the bank's website and the bank has performed the redirect back to the client. It must contain the query parameter list that the bank has added to the client's redirectUrl when performing the redirect. finAPI will process the parameter list and extract the embedded authentication data to complete the login
- accountReferences: In case the service is called with interface = XS2A, and the interface has the property DETAILED_CONSENT, then the client might have to pass a list of IBANs to the service. finAPI requires the IBAN list to perform a user login and will be able to download only those accounts that are included in the given list. Note that when the XS2A interface has already been connected to a bank connection, an update of the connection can be performed without specifying this field, in which case finAPI will internally create the IBAN list based on the currently imported accounts.
- decoupledCallback: In case the service is called with interface = XS2A, and the interface has the property DECOUPLED_APPROACH, then the client should expect an error message that decoupled authentication is required. In that case, the client should re-trigger the service with the "decoupledCallback" field set to true, which signals to our API that it can poll the bank side for the status of the authentication.
6. Changes to Service "Update a bank connection"
...
Old
...
New
...
{
"bankConnectionId": 1,
"bankingPin": "123456",
"storePin": true,
"importNewAccounts": false,
"skipPositionsDownload": false,
"loadOwnerData": false,
"challengeResponse": "0123",
"multiStepAuthentication": {
"hash": "c7af602c031117458affd825305fb56d",
"challengeResponse": "0123"
}
}
...
{
"bankConnectionId": 1,
"interface": "FINTS_SERVER",
"loginCredentials": [
{
"label": "PIN",
"value": "myPIN"
}
],
"storeSecrets": true,
"importNewAccounts": false,
"skipPositionsDownload": false,
"loadOwnerData": false,
"accountReferences": [
{
"iban": "..."
}
],
"multiStepAuthentication": {
"hash": "c7af602c031117458affd825305fb56d",
"challengeResponse": "0123",
"twoStepProcedureId": "955",
"redirectCallback": "bankParam1=X&bankParam2=Y",
"decoupledCallback": true
},
"redirectUrl": "...",
}
- Analogue to the import service
- Please be aware, that in case of an invalid/expired consent, you have to offer a frontend workflow for your customer
- Please be aware, that if you trigger the update service for an interface, where no account with the capability "DATA_DOWNLOAD" is included, the customer will get a 2FA but only data like capabilities will updated.
- redirectUrl: In case the service is called with interface = XS2A, and the interface has the property REDIRECT_APPROACH, then the client must pass a URL here to which the user will be redirected from the bank's website after he has entered his credentials. The redirectUrl must have the HTTPS protocol. When the Redirect Approach is used, the services will return with HTTP Code 510 and an ErrorMessage entity, as described further below in this document.
- redirectCallback: This field must be passed when the service is re-triggered by the client after the user has entered his credentials on the bank's website and the bank has performed the redirect back to the client. It must contain the query parameter list that the bank has added to the client's redirectUrl when performing the redirect. finAPI will process the parameter list and extract the embedded authentication data to complete the login
- accountReferences: In case the service is called with interface = XS2A, and the interface has the property DETAILED_CONSENT, then the client might have to pass a list of IBANs to the service. finAPI requires the IBAN list to perform a user login and will be able to download only those accounts that are included in the given list. Note that this field is optional for the service: if it's not passed, the API will internally initialise this list based on the currently imported accounts.
- decoupledCallback: In case the service is called with interface = XS2A, and the interface has the property DECOUPLED_APPROACH, then the client should expect an error message that decoupled authentication is required. In that case, the client should re-trigger the service with the "decoupledCallback" field set to true, which signals to our API that it can poll the bank side for the status of the authentication.
- If the bank connection has several interfaces and some of its accounts was previously imported or updated via an interface which have higher priority than the interface used in the current update, then balances and transactions will not be downloaded for such accounts. The XS2A interface has the highest priority, followed by FINTS_SERVER and finally WEB_SCRAPER.
7. New Service "Connect a new interface" (POST /api/v1/bankConnections/connectInterface)
...
Old
...
New
...
{
"bankConnectionId": 1
"interface": "FINTS_SERVER",
"loginCredentials": [
{
"label": "Onlinebanking-ID",
"value": "myID"
},
{
"label": "PIN",
"value": "myPIN"
}
],
"storeSecrets": true,
"twoStepProcedureId": "911",
"accountReferences": [
{
"iban": "..."
}
],
"multiStepAuthentication": {
"hash": "c7af602c031117458affd825305fb56d",
"challengeResponse": "0123",
"twoStepProcedureId": "955",
"redirectCallback": "bankParam1=X&bankParam2=Y",
"decoupledCallback": true
},
"redirectUrl": "..."
}
- Connect a new interface to an existing bank connection
- Semantically, this service behaves almost identical to the "Import a new bank connection" service, just with the difference that it does not create a new bank connection but extends an existing bank connection with new data from the chosen interface. The possible responses of the service are the same as for the "Import a new bank connection" service, with the difference that it returns HTTP code 200 instead of 201 in case of success.
- interface: Required field with possible Values "FINTS_SERVER","WEB_SCRAPER","XS2A"
- redirectUrl: In case the service is called with interface = XS2A, and the interface has the property REDIRECT_APPROACH, then the client must pass a URL here to which the user will be redirected from the bank's website after he has entered his credentials. The redirectUrl must have the HTTPS protocol. When the Redirect Approach is used, the services will return with HTTP Code 510 and an ErrorMessage entity, as described further below in this document.
- redirectCallback: This field must be passed when the service is re-triggered by the client after the user has entered his credentials on the bank's website and the bank has performed the redirect back to the client. It must contain the query parameter list that the bank has added to the client's redirectUrl when performing the redirect. finAPI will process the parameter list and extract the embedded authentication data to complete the login
- accountReferences: In case the service is called with interface = XS2A, and the interface has the property DETAILED_CONSENT, then the client might have to pass a list of IBANs to the service. finAPI requires the IBAN list to perform a user login and will be able to download only those accounts that are included in the given list. Note that when the XS2A interface has already been connected to a bank connection, an update of the connection can be performed without specifying this field, in which case finAPI will internally create the IBAN list based on the currently imported accounts.
- decoupledCallback: In case the service is called with interface = XS2A, and the interface has the property DECOUPLED_APPROACH, then the client should expect an error message that decoupled authentication is required. In that case, the client should re-trigger the service with the "decoupledCallback" field set to true, which signals to our API that it can poll the bank side for the status of the authentication.
8. Changes to Resource Client Configuration and Service "Edit Client Configuration"
...
Old
...
New
...
{
"isAutomaticBatchUpdateEnabled": true,
"userNotificationCallbackUrl": "...",
"userSynchronizationCallbackUrl": "...",
"refreshTokensValidityPeriod": 3600,
"userAccessTokensValidityPeriod": 3600,
"clientAccessTokensValidityPeriod": 3600,
"maxUserLoginAttempts": 3,
"isUserAutoVerificationEnabled": true,
"isMandatorAdmin": true,
"isWebScrapingEnabled": true,
"availableBankGroups": [],
"applicationName": "My App",
"finTSProductRegistrationNumber": null,
"pinStorageAvailableInWebForm": true,
"paymentsEnabled": true
}
...
{
"isAutomaticBatchUpdateEnabled": true,
"userNotificationCallbackUrl": "...",
"userSynchronizationCallbackUrl": "...",
"refreshTokensValidityPeriod": 3600,
"userAccessTokensValidityPeriod": 3600,
"clientAccessTokensValidityPeriod": 3600,
"maxUserLoginAttempts": 3,
"isUserAutoVerificationEnabled": true,
"isMandatorAdmin": true,
"isWebScrapingEnabled": true,
"isXs2aEnabled": true,
"availableBankGroups": [],
"applicationName": "My App",
"finTSProductRegistrationNumber": null,
"storeSecretsAvailableInWebForm": true,
"paymentsEnabled": true
}
- The field "pinStorageAvailableInWebForm" will be duplicated by a new field "storeSecretsAvailableInWebForm", to be consistent to the other changes in this document. The old field will be marked deprecated and removed at some point.
- The field "isXs2aEnabled" defines whether the mandator can use any XS2A interface. If this flag is set to "false", all services will throw an error in response to a request for "XS2A" interface.
- The "Edit Client Configuration" Service will be adjusted similarly: The param "isPinStorageAvailableInWebForm" will be duplicated and replaced by a new param "isStoreSecretsAvailableInWebForm" at some point.
9. Changes to ErrorMessage
...
Old
...
New
...
{
"errors": [
{
"message": "string",
"code": "string",
"type": "string"
}
],
"date": "string",
"requestId": "string",
"endpoint": "string",
"authContext": "string",
"bank": "string"
}
...
{
"errors": [
{
"message": "An unexpected error occurred",
"code": "UNEXPECTED_ERROR",
"type": "TECHNICAL",
"multiStepAuthentication": {
"hash": "c7af602c031117458affd825305fb56d",
"status": "CHALLENGE_RESPONSE_REQUIRED",
"challengeMessage": "...",
"answerFieldLabel": "TAN-Nummer",
"redirectUrl": "https://user-login.bank.de/",
"redirectContext": "12345",
"redirectContextField": "state",
"twoStepProcedures": [
{
"procedureId": "955",
"procedureName": "mobileTAN",
"procedureChallengeType": "TEXT",
"implicitExecute": true
}
],
"opticalData": "11048813833205002812775114302C30315D",
"photoTanMimeType": "image/svg+xml",
"photoTanData": "..."
}
}
],
"date": "2018-01-01 00:00:00.000",
"requestId": "request-id-01234567890123456789",
"endpoint": "https://finapi.localhost",
"authContext": "1/2",
"bank": "00000000"
}
a. In case of the embedded approach
- The "multiStepAuthentication.status" field can be one of:
- TWO_STEP_PROCEDURE_REQUIRED – in this case you have to process/forward the fields which are marked blue and re-do the service call with passing the "multiStepAuthentication.twoStepProcedureId" field with the selection that the user has made.
- CHALLENGE_RESPONSE_REQUIRED – in this case you have to process/forward the fields which are marked purple and re-do the service call with passing the "multiStepAuthentication.challengeResponse" field with the user's answer.
b. In case of the redirect approach
In case of the redirect approach, finAPI will return an ErrorMessage with the following fields in the multiStepAuthentication data:
...
{
…
"multiStepAuthentication": {
"status": "REDIRECT_REQUIRED",
"redirectUrl": "https://auth.bank.de?redirectUrl=...",
"redirectContextField": "state",
"redirectContext": "1234"
}
}
- a new status constant "REDIRECT_REQUIRED" will be introduced
- new fields "redirectUrl", "redirectContext" and "redirectContextField" will be added and will have a value in case of status = REDIRECT_REQUIRED
- the client must direct the user to the given redirectUrl. This URL will in itself contain the redirectUrl that was initially passed to the service by the client, and which the bank will use as a redirect back to the client.
- the redirectContextField tells the client what query parameter he has to process within the callback that he receives from the bank after the user has entered his credentials, to be able to identify to which context/user the callback relates.
- the redirectContext field contains the actual value that the client must expect when processing the callback from the bank, to be able to identify to which context/user the callback relates.
c. In case of the decoupled approach
In case of the decoupled approach, finAPI will return the following ErrorMessage:
...
- A new status "DECOUPLED_AUTH_REQUIRED" will be introduced.
- When the client receives this status, it should notify the end-user about the necessity to complete the decoupled authentication.
- When the end-user read/accepted the notification, the client can start polling the API to get a status of the decoupled authentication. In that case, the client must submit a new field "decoupledCallback" set to "true".
- Until the decoupled authentication is not completed, the API will return a newly introduced status "DECOUPLED_AUTH_IN_PROGRESS".
- The client should continue polling the API until it gets BankConnectionResource (with HTTP status code equals to 200).
10. Typical XS2A interface imports
a. Embedded approach
A typical XS2A import might work as follows:
- Import Service returns 510 with status "TWO_STEP_PROCEDURE_REQUIRED". The client forwards the list of methods to the user and retries the service, passing the user's selection in the "multiStepAuthentication.twoStepProcedureId" field
- The second call of the service might again return 510, this time with status "CHALLENGE_RESPONSE_REQUIRED". The client forwards the challenge to the user, and then calls the service a third time, this time passing the "multiStepAuthentication.challengeResponse" field.
Follow-up updates using the XS2A interface might not require MSA, depending on whether you are passing the "storeSecrets" field, and on the validity of a consent/access_token on the bank side.
Note that the steps above just describe one possible scenario – different steps might be omitted depending on the specific bank interface.
After importing a payment account by XS2A interface, you might go on importing further accounts with the Connect Interface Service.
b. Redirect approach
Example of a Bank Connection Import with Redirect Approach:
...
The finAPI Service responds with HTTP Code 510 and the following ErrorMessage:
...
{
…
"multiStepAuthenticaton": {
"status": "REDIRECT_REQUIRED",
"redirectUrl": "https://bank.de?redirectUrl=https%3A%2F%2Fmyclient.de%2Fcallback",
"redirectContextField": "state",
"redirectContext": "1234"
}
}
...
c. Decoupled approach
Example of a Bank Connection Import with the Decoupled approach:
- Client calls finAPI's "Import a new bank connection" service with interface = XS2A, for a bank whose XS2A interface has the DECOUPLED_APPROACH property.
- The finAPI Service responds with HTTP code 510 and "multiStepAuthentication" status set to "DECOUPLED_AUTH_REQUIRED".
- The client notifies the end-user about the necessity to complete the decoupled authentication.
- The end-user completes the authentication using e.g. the bank's mobile app.
- The client repeats the call to finAPI's "Import a new bank connection", now with "decoupledCallback" set to "true".
- The finAPI Service responds with HTTP code 510 and "multiStepAuthentication" status set to "DECOUPLED_AUTH_IN_PROGRESS".
- The client repeats the call until the finAPI Service responds with HTTP code 201 and the Bank Connection resource in the response body.
d. Combined approaches
Some banks require using multiple approaches (e.g. first complete the redirect approach and then proceed with the decoupled). That's why error codes produced by the API not necessary belong to a single approach, but can be from different ones.
11. Changes to Service Edit Bank Connection
...
Old
...
New
...
{
"bankingUserId": "123456",
"bankingCustomerId": "123456",
"bankingPin": "123456",
"defaultTwoStepProcedureId": "955",
"name": "Bank Connection"
}
...
- When editing credentials or the default two-step-procedure, the target interface must be specified. Temporarily, the "interface" field will be optional though to avoid breaking changes.
- You can use the service "Edit a bank connection" and pass the defaultTwoStepProcedureId parameter with the respective value to store/update this value. By defining the defaultTwoStepProcedureId in the bank connection interface, the user will not be bothered anymore to select this procedure every time he wants to update his accounts. Also ONLY IF the given security function really requires a strong customer authentication, user involvement will be required.
12. Changes to Resource Account
...
Old
...
New
...
{
"id": 1,
"bankConnectionId": 1,
"accountName": "Testaccount",
"accountNumber": "12345678",
"subAccountNumber": "1234",
"iban": "DE89370400440532013000",
"accountHolderName": "Herr Max Mustermann",
"accountHolderId": "XXXXX",
"accountCurrency": "EUR",
"accountTypeId": 1,
"accountTypeName": "Checking",
"balance": 99.99,
"overdraft": 99.99,
"overdraftLimit": 99.99,
"availableFunds": 99.99,
"lastSuccessfulUpdate": "",
"lastUpdateAttempt": "",
"status": "UPDATED",
"isNew": true,
"supportedOrders": [
"SEPA_MONEY_TRANSFER",
"SEPA_COLLECTIVE_MONEY_TRANSFER",
"SEPA_BASIC_DIRECT_DEBIT",
"SEPA_BASIC_COLLECTIVE_DIRECT_DEBIT",
"SEPA_B2B_DIRECT_DEBIT",
],
"clearingAccounts": [ … ]
}
...
{
…,
"interfaces": [
{
"interface": "FINTS_SERVER",
"capabilities": [
"SEPA_DIRECT_DEBIT"
],
"lastUpdateAttempt": "",
"lastSuccessfulUpdate": "",
"status": "UPDATED"
},
{
"interface": "XS2A",
"capabilities": [
"DATA_DOWNLOAD",
"SEPA_MONEY_TRANSFER",
"IBAN_ONLY_SEPA_MONEY_TRANSFER"
],
"lastUpdateAttempt": "",
"lastSuccessfulUpdate": "",
"status": "UPDATED"
},
]
}
- Each account will have a set of interfaces. Interfaces will be added during import or update of a bank connection whenever an interface returns this account for the first time
- Each interface contains the account status from this interface's point of view, last update timestamps, and also defines the set of "capabilities" (currently: "supportedOrders") that it provides for this account.
- The following new capabilities will be added in additional to the already existing capabilities:
- DATA_DOWNLOAD means this interface can be used to load the balance and transactions/securities for this account
- IBAN_ONLY_SEPA_MONEY_TRANSFER / IBAN_ONLY_SEPA_DIRECT_DEBIT = these new capabilities will be replacing the previously existing fields in the bank connection resource "ibanOnlyMoneyTransferSupported" and "ibanOnlyDirectDebitSupported"
a. Note about account capabilities:
It is important to understand the dependencies of the account capabilities to the interfaces and their two-step-procedures. If a user wants to trigger a certain action for an account, e.g. a money transfer, the client should iterate the account capabilities and collect all interfaces that supply this capability for the account, together with the interface two-step-procedures. The user must then select the desired interface and two-step-procedure.
b. New changes in AccountResource
...
Old
...
New
...
{
…
"accountTypeId": 1,
"accountTypeName": "Checking",
…
}
...
{
…,
"accountType": "Checking"
}
13. Changes to Service Get and search all accounts
- The request params "accountTypeIds" will be flagged deprecated and be removed at some later point after the go-live of PSD2 integration. Until then, there parameter will still work as it did until now.
- A new field "accountTypes" will be added, which will work as accountTypeIds, but instead of the id, it will use the name of the accountType (CHECKING, SAVINGS, CREDITCARD, SECURITY, LOAN, POCKET, MEMBERSHIP, BAUSPAREN). As this is a request parameter that is passed in the URL, it will be case-insensitive.
14. Payments
a. New Service to create money transfer(s)
...
POST /payments/moneyTransfers
...
{
"accountId": 1,
"singleBooking": true,
"executionDate": "",
"moneyTransfers": [
{
"counterpartName": "",
"counterpartIban": "",
"counterpartBic": "",
"amount": 1,
"purpose": "",
"sepaPurposeCode": ""
}
]
}
b. New Service to create direct debit(s)
...
POST /payments/directDebits
...
{
"accountId": 1,
"singleBooking": true,
"executionDate": "",
"sequenceType:": "",
"type": "B2B",
"directDebits": [
{
"counterpartName": "",
"counterpartIban": "",
"counterpartBic": "",
"amount": 1,
"purpose": "",
"sepaPurposeCode": "",
"mandateId": "1",
"mandateDate": "2018-01-01",
"creditorId": "Creditor",
"endToEndId": "001100550526"
}
]
}
c. Payment resource
Both services return a Payment Resource:
...
{
"id": 1,
"accountId": 1,
"requestDate": null,
"executionDate": null,
"type": "MONEY_TRANSFER",
"status": "OPEN",
"bankMessage": "string",
"amount": 99.99,
"orderCount": 1
}
- The "status" field of the Payment resource will be extended by a new status "OPEN". This is the status that any payment initially has that was created via the POST /payments/ services. The OPEN status means that the payment was just created in finAPI as a resource, but not yet submitted to the bank.
- The requestDate and executionDate will initially be null. They will be set during payment submission (see below)
- Money Transfers/Direct Debits that are initiated with the old services (requestSepaMoneyTransfer/requestSepaDirectDebit) will still create the same Payment resources as they did before. The services will be flagged as DEPRECATED though and will be removed some time after the go-live of the PSD version.
d. New service to submit a payment
...
POST /payments/submit
...
{
"paymentId": 1,
"interface":"",
"loginCredentials": [],
"redirectUrl": "",
"multiStepAuthentication": {
"challengeResponse": "",
"twoStepProcedureId":""
"redirectCallback": ""
}
}
- This service can be used to submit a payment. The service might work only for payments that have been created with the new create payment services. Payments that are initiated by the old requestSepaXXX services may still need to be submitted via the executeSepaXXX services.
- The interface field is required
- The loginCredentials field is optional and may not be required in case the credentials are stored in the interface, or if the user needs to enter the credentials in finAPI's web form.
Number 3 – 5 of this chapter are not relevant for WebForm-Users. - The service may return HTTP code 510 in case of multi-step-authentication. The service must then be re-triggered passing the required fields in the multiStepAuthentication field (same how it works for other services like import bank connection, connect interface etc)
- The service may return HTTP code 451 with a Web form location in case the client has no PIS license
- Note that parallel payments even for the same account are possible in XS2A. The "DISCARDED" status will only be set for XSA2 payments if the bank rejects the payment
15. XS2A Sandboxes
...
Additional information
If you are a licensed TPP by a national regulator, you will need different certificates (QWAC and QSeal) to use the XS2A-interfaces from the bank. These certificates are issued by a national trusted authority, in Germany it´s Bundesdruckerei or Bankverlag in Austria A-Trust. Please take care of that.
Customers, which are using the finAPI WebForm do not need these certificates.
Additional changes for further (Berlin Group) PSD2 approaches
Concepts and changes will be published at finAPIs Wiki at https://teaminvest.jira.com/wiki/spaces/ACCDOC/pages/560955393/20190523+Concept+PSD2+Integration+AIS
and at finAPIs Dev Portal: https://finapi.zendesk.com/hc/en-us/articles/360028386632-PSD2-XS2A-Changes-in-finAPI
Please subscribe to get informed for any changes there.
Further changes (unrelated to PSD2)
Aside from the PSD2-related changes, the following unrelated changes might be made as well, some time (at least three months) after the PSD2 go-live:
• Service "Get multiple banks" will get removed
• Service "Get multiple bank connections" will get removed
• Service "Get multiple accounts" will get removed
• Service "Get multiple transactions" will get removed
• Service "Edit multiple transactions (DEPRECATED)" will get removed
• Service "Get multiple securities" will get removed
• Service "Get multiple categories" will get removed
• Service "Get multiple labels" will get removed
• Service "Check categorization" will be moved from the "Mocks and Tests" section to the "Transactions" section
• Transaction.paypalData field (and its related type "PaypalTransactionData") will get removed
• Sending the access_tokens as request parameter instead of as a header will be prohibited
• accountTypeIds (in Account Resource and in Service importBankConnection) will be removed. Instead, a newfield accountTypes will be added Which will contain the names of account types
• account type "Pocket" will be removed
• The deprecated response 422 – COLLECTIVE_MONEY_TRANSFER_NOT_SUPPORTED will be removed from the documentation
IMPORTANT CHANGES ON GO-LIVE:
There will be the following change that will immediately take effect when we will go live with the PSD2 integration
...
This space is now deprecated. We urge you to check out our new Access Public Documentation that we recently published instead, which covers all state-of-the-art information of our products. Note: due to overall restructuring for our new Access Public Documentation, there might not be a corresponding page with the exact same content like this deprecated page in our new documentation. However, we make sure to already cover all information you need, including this content, in our new documentation. |