For licensed mandators (no web form)
Embedded approach
When applicable?
If a bank interface has neither DECOUPLED_APPROACH
nor REDIRECT_APPROACH
properties.
Step | Request/response example |
---|---|
Step #1 Mandatory request fields
Explanation The client application loads a bank, chosen by the end-user. Then the application asks the end-user for credentials if they are required by the bank interface. Also, the application checks whether the chosen bank interface has | POST /api/v1/bankConnections/import HTTP/1.1 Content-Type: application/json Accept: application/json Authorization: Bearer <user's access token> { "bankId": 277672, "interface": "XS2A", "loginCredentials": [ { "label": "Onlinebanking-ID", "value": "idontexist" }, { "label": "PIN", "value": "1337" } ], "accountReferences": [ { "iban": "DE89370400440532013000" } ] } |
Step #2 How to recognise the step Field Mandatory response fields of
Explanation If the bank decides, it responses with a list of available two-step procedures (aka SCA methods - Strong Customer Authentication methods). And then the client application should ask the end-user to chose one of the offered two-step procedures. | HTTP/1.1 510 { "errors": [ { "message": "SCA method selection is required", "code": "ADDITIONAL_AUTHENTICATION_REQUIRED", "type": "BUSINESS", "multiStepAuthentication": { "hash": "112c3581b39fc95a1f979d0d73f14dfb", "status": "TWO_STEP_PROCEDURE_REQUIRED", "challengeMessage": null, "answerFieldLabel": null, "redirectUrl": null, "redirectContext": null, "redirectContextField": null, "twoStepProcedures": [ { "procedureId": "DEMO-TSP-01", "procedureName": "SMS", "procedureChallengeType": "TEXT", "implicitExecute": false }, { "procedureId": "DEMO-TSP-02", "procedureName": "PUSH", "procedureChallengeType": "TEXT", "implicitExecute": false } ], "photoTanMimeType": null, "photoTanData": null, "opticalData": null } } ], "date": "2019-11-27 08:13:32.155", "requestId": "selfgen-3c81395b-7e01-40d2-835e-300ba9af1399", "endpoint": "POST /api/v1/bankConnections/import", "authContext": "1/18", "bank": "00000000 - FinAPI Test Bank" } |
Step #3 Mandatory request fields
Explanation The client application asks the end-user to chose a two-step procedure and then submits it to the API. Value of | POST /api/v1/bankConnections/import HTTP/1.1 Content-Type: application/json Accept: application/json Authorization: Bearer <user's access token> { "bankId": 277672, "interface": "XS2A", "loginCredentials": [ { "label": "Onlinebanking-ID", "value": "idontexist" }, { "label": "PIN", "value": "1337" } ], "accountReferences": [ { "iban": "DE89370400440532013000" } ], "multiStepAuthentication": { "hash": "112c3581b39fc95a1f979d0d73f14dfb", "twoStepProcedureId": "DEMO-TSP-01" } } |
Step #4 How to recognise the step Field Mandatory response fields of
Explanation When the two-step procedure is chosen (either by the bank or by the end-user), the API responses with details for the end-user. The client application should show this info to the end-user and ask for an answer. | HTTP/1.1 510 { "errors": [ { "message": "Es ist eine zusätzliche Authentifizierung erforderlich. Bitte geben Sie folgenden Code an: demo", "code": "ADDITIONAL_AUTHENTICATION_REQUIRED", "type": "BUSINESS", "multiStepAuthentication": { "hash": "112c3581b39fc95a1f979d0d73f14dfb", "status": "CHALLENGE_RESPONSE_REQUIRED", "challengeMessage": "Es ist eine zusätzliche Authentifizierung erforderlich. Bitte geben Sie folgenden Code an: demo", "answerFieldLabel": "TEXT", "redirectUrl": null, "redirectContext": null, "redirectContextField": null, "twoStepProcedures": null, "photoTanMimeType": null, "photoTanData": null, "opticalData": null } } ], "date": "2019-11-27 08:19:23.957", "requestId": "selfgen-e5a38d80-bf99-47f2-b4f0-1e32717de72a", "endpoint": "POST /api/v1/bankConnections/import", "authContext": "1/18", "bank": "00000000 - FinAPI Test Bank" } |
Step #5 Mandatory request fields
Explanation The client application asks for the challenge reponse and submits it back to the API. Value of | POST /api/v1/bankConnections/import HTTP/1.1 Content-Type: application/json Accept: application/json Authorization: Bearer <user's access token> { "bankId": 277672, "interface": "XS2A", "loginCredentials": [ { "label": "Onlinebanking-ID", "value": "idontexist" }, { "label": "PIN", "value": "1337" } ], "accountReferences": [ { "iban": "DE89370400440532013000" } ], "multiStepAuthentication": { "hash": "112c3581b39fc95a1f979d0d73f14dfb", "twoStepProcedureId": "DEMO-TSP-01", "challengeResponse": "demo" } } |
Step #6 The API completes the import process and returns a bank connection resource. | HTTP/1.1 201 { "id": 21, "bankId": 277672, "name": null, "bankingUserId": null, "bankingCustomerId": null, "bankingPin": null, "type": "DEMO", "updateStatus": "IN_PROGRESS", "categorizationStatus": "READY", ... } |
Redirect approach
When applicable?
If a bank interface has REDIRECT_APPROACH
property.
Step | Request/response example |
---|---|
Step #1 Mandatory request fields
Explanation The client application loads a bank, chosen by the end-user. Then the application asks the end-user for credentials if they are required by the bank interface. Also, the application checks whether the chosen bank&interface has | POST /api/v1/bankConnections/import HTTP/1.1 Content-Type: application/json Accept: application/json Authorization: Bearer <user's access token> { "bankId": 280002, "interface": "XS2A", "redirectUrl": "https://customer.io", "loginCredentials": [ { "label": "Onlinebanking-ID", "value": "idontexist" } ], "accountReferences": [ { "iban": "DE89370400440532013000" } ] } |
Step #2 How to recognise the step Field Mandatory response fields of
Explanation The API builds a redirect URL that will route the end-user to a page on the bank side, where the user can complete the authentication process. On this step, the client’s application should store values from | HTTP/1.1 510 { "errors": [ { "message": null, "code": "ADDITIONAL_AUTHENTICATION_REQUIRED", "type": "BUSINESS", "multiStepAuthentication": { "hash": "288c0a78c6596e8f02f70a21e731d46a", "status": "REDIRECT_REQUIRED", "challengeMessage": null, "answerFieldLabel": null, "redirectUrl": "https://demobank.finapi.io?state=976641d2-c03f-4919-8dac-16ccfd24b4e0", "redirectContext": "976641d2-c03f-4919-8dac-16ccfd24b4e0", "redirectContextField": "state", "twoStepProcedures": null, "photoTanMimeType": null, "photoTanData": null, "opticalData": null } } ], "date": "2019-11-27 11:20:21.261", "requestId": "selfgen-fece3d6c-a0f0-43ea-a910-7e9ca7a7b1f6", "endpoint": "POST /api/v1/bankConnections/import", "authContext": "1/18", "bank": "DEMO0002 - finAPI Test Redirect Bank" } |
Step #3 The client application should redirect the end-user to the given redirectUrl. Example GET https://demobank.finapi.io?state=976641d2-c03f-4919-8dac-16ccfd24b4e0 HTTP/1.1 | |
Step #4 When the end-user successfully completes the authentication process on the bank’s side, he is redirected to the URL given on the step #1. Additionally, the bank adds some more data to the URL (as query parameters). But the most important part for the client application is this Example GET https://customer.io?state=976641d2-c03f-4919-8dac-16ccfd24b4e0&code=1e065516-0e9a-4f53-b5a6-140e69a3bf70 HTTP/1.1 | |
Step #5 Mandatory request fields
Explanation The client application submits a query string as a value of | POST /api/v1/bankConnections/import HTTP/1.1 Content-Type: application/json Accept: application/json Authorization: Bearer <user's access token> { "bankId": 280002, "interface": "XS2A", "redirectUrl": "https://customer.io", "loginCredentials": [ { "label": "Onlinebanking-ID", "value": "idontexist" } ], "accountReferences": [ { "iban": "DE89370400440532013000" } ], "multiStepAuthentication": { "hash": "288c0a78c6596e8f02f70a21e731d46a", "redirectCallback": "state=976641d2-c03f-4919-8dac-16ccfd24b4e0&code=1e065516-0e9a-4f53-b5a6-140e69a3bf70" } } |
Step #6 The API completes the import process and returns a bank connection resource. | HTTP/1.1 201 { "id": 46, "bankId": 280002, "name": null, "bankingUserId": null, "bankingCustomerId": null, "bankingPin": null, "type": "ONLINE", "updateStatus": "IN_PROGRESS", "categorizationStatus": "READY", ... } |
Decoupled approach
When applicable?
If a bank interface has DECOUPLED_APPROACH
property.
Step | Request/response example |
---|---|
Step #1 Mandatory request fields
Explanation The client application loads a bank, chosen by the end-user. Then the application asks the end-user for credentials if they are required by the bank interface. Also, the application checks whether the chosen bank interface has | POST /api/v1/bankConnections/import HTTP/1.1 Content-Type: application/json Accept: application/json Authorization: Bearer <user's access token> { "bankId": 277672, "interface": "XS2A", "loginCredentials": [ { "label": "Onlinebanking-ID", "value": "idontexist" }, { "label": "PIN", "value": "1337" } ], "accountReferences": [ { "iban": "DE89370400440532013000" } ] } |
Step #2 How to recognise the step Field Mandatory response fields of
Explanation If the bank decides, it responses with a list of available two-step procedures (aka SCA methods - Strong Customer Authentication methods). And then the client application should ask the end-user to chose one of the offered two-step procedures. | HTTP/1.1 510 { "errors": [ { "message": "SCA method selection is required", "code": "ADDITIONAL_AUTHENTICATION_REQUIRED", "type": "BUSINESS", "multiStepAuthentication": { "hash": "112c3581b39fc95a1f979d0d73f14dfb", "status": "TWO_STEP_PROCEDURE_REQUIRED", "challengeMessage": null, "answerFieldLabel": null, "redirectUrl": null, "redirectContext": null, "redirectContextField": null, "twoStepProcedures": [ { "procedureId": "DEMO-TSP-01", "procedureName": "SMS", "procedureChallengeType": "TEXT", "implicitExecute": false }, { "procedureId": "DEMO-TSP-02", "procedureName": "PUSH", "procedureChallengeType": "TEXT", "implicitExecute": false } ], "photoTanMimeType": null, "photoTanData": null, "opticalData": null } } ], "date": "2019-11-27 08:13:32.155", "requestId": "selfgen-3c81395b-7e01-40d2-835e-300ba9af1399", "endpoint": "POST /api/v1/bankConnections/import", "authContext": "1/18", "bank": "00000000 - FinAPI Test Bank" } |
Step #3 Mandatory request fields
Explanation The client application asks the end-user to chose a two-step procedure and then submits it to the API. Value of | POST /api/v1/bankConnections/import HTTP/1.1 Content-Type: application/json Accept: application/json Authorization: Bearer <user's access token> { "bankId": 277672, "interface": "XS2A", "loginCredentials": [ { "label": "Onlinebanking-ID", "value": "idontexist" }, { "label": "PIN", "value": "1337" } ], "accountReferences": [ { "iban": "DE89370400440532013000" } ], "multiStepAuthentication": { "hash": "112c3581b39fc95a1f979d0d73f14dfb", "twoStepProcedureId": "DEMO-TSP-01" } } |
Step #4 How to recognise the step Field Mandatory response fields of
Explanation If the chosen two-step procedure was of a decoupled type, the API responses with this error. The client application should notify the end-user that the bank will send a notification. | HTTP/1.1 510 { "errors": [ { "message": "Bitte bestätigen Sie auf ihrem externen Gerät die Anmeldung", "code": "ADDITIONAL_AUTHENTICATION_REQUIRED", "type": "BUSINESS", "multiStepAuthentication": { "hash": "8f3bb2a7a1c6fec906c62465562e1dba", "status": "DECOUPLED_AUTH_REQUIRED", "challengeMessage": "Bitte bestätigen Sie auf ihrem externen Gerät die Anmeldung", "answerFieldLabel": null, "redirectUrl": null, "redirectContext": null, "redirectContextField": null, "twoStepProcedures": null, "photoTanMimeType": null, "photoTanData": null, "opticalData": null } } ], "date": "2019-11-27 10:35:17.682", "requestId": "selfgen-9f035aca-d094-42d7-9285-a3eae9d5a4a9", "endpoint": "POST /api/v1/bankConnections/import", "authContext": "1/18", "bank": "DEMO0001 - finAPI Test Bank" } |
Step #5 Mandatory request fields
Explanation The client application asks the API to continue the authentication process and send a notification to the end-user. Value of | POST /api/v1/bankConnections/import HTTP/1.1 Content-Type: application/json Accept: application/json Authorization: Bearer <user's access token> { "bankId": 277672, "interface": "XS2A", "loginCredentials": [ { "label": "Onlinebanking-ID", "value": "idontexist" }, { "label": "PIN", "value": "1337" } ], "accountReferences": [ { "iban": "DE89370400440532013000" } ], "multiStepAuthentication": { "hash": "112c3581b39fc95a1f979d0d73f14dfb", "twoStepProcedureId": "DEMO-TSP-01", "decoupledCallback": true } } |
Step #6 How to recognise the step Field Mandatory response fields of
Explanation The API returns this error if the authentication is still not completed on the bank side. The client application should continue repeating a step #5 while the API returns this error. | HTTP/1.1 510 { "errors": [ { "message": "Bitte bestätigen Sie auf ihrem externen Gerät die Anmeldung", "code": "ADDITIONAL_AUTHENTICATION_REQUIRED", "type": "BUSINESS", "multiStepAuthentication": { "hash": "8f3bb2a7a1c6fec906c62465562e1dba", "status": "DECOUPLED_AUTH_IN_PROGRESS", "challengeMessage": "Bitte bestätigen Sie auf ihrem externen Gerät die Anmeldung", "answerFieldLabel": null, "redirectUrl": null, "redirectContext": null, "redirectContextField": null, "twoStepProcedures": null, "photoTanMimeType": null, "photoTanData": null, "opticalData": null } } ], "date": "2019-11-27 10:42:54.468", "requestId": "selfgen-5801b1be-0e09-4d2a-99a2-a748d7ee6d7e", "endpoint": "POST /api/v1/bankConnections/import", "authContext": "1/18", "bank": "DEMO0001 - finAPI Test Bank" } |
Step #7 Mandatory request fields
Explanation The client application asks the API to continue the authentication process and check the authentication status on the bank side. | POST /api/v1/bankConnections/import HTTP/1.1 Content-Type: application/json Accept: application/json Authorization: Bearer <user's access token> { "bankId": 277672, "interface": "XS2A", "loginCredentials": [ { "label": "Onlinebanking-ID", "value": "idontexist" }, { "label": "PIN", "value": "1337" } ], "accountReferences": [ { "iban": "DE89370400440532013000" } ], "multiStepAuthentication": { "hash": "112c3581b39fc95a1f979d0d73f14dfb", "twoStepProcedureId": "DEMO-TSP-01", "decoupledCallback": true } } |
Step #8 The API completes the import process and returns a bank connection resource. | HTTP/1.1 201 { "id": 46, "bankId": 280002, "name": null, "bankingUserId": null, "bankingCustomerId": null, "bankingPin": null, "type": "ONLINE", "updateStatus": "IN_PROGRESS", "categorizationStatus": "READY", ... } |
Possible combinations of approaches
Redirect + decoupled + decoupled (ErsteGroup/Sparkasse AT banks)
This example illustrates a case when a bank requires multiple SCAs to be confirmed by the end-user. The diagram below shows that the flow contains a few optional steps. That’s why the client application should always check a status returned by the API so that it can react accordingly.
Step | HTTP(S) message |
---|---|
Step #1 Mandatory request fields
Explanation The client application loads a bank, chosen by the end-user (“Erste Group Bank AG” in this particular case). Then the application asks the end-user for credentials if they are required by the bank interface (no login fields for this bank). Also, the application checks whether the chosen bank interface has | POST /api/v1/bankConnections/import HTTP/1.1 Content-Type: application/json Accept: application/json Authorization: Bearer <user's access token> { "bankId": 278985, "interface": "XS2A", "storeSecrets": true, "redirectUrl": "https://customer.io" } |
Step #2 How to recognise the step Field Mandatory response fields of
Explanation The API builds a redirect URL that will route the end-user to a page on the bank side, where the user can complete the authentication process. On this step, the client’s application should store values from | HTTP/1.1 510 { "errors": [ { "message": null, "code": "ADDITIONAL_AUTHENTICATION_REQUIRED", "type": "BUSINESS", "multiStepAuthentication": { "hash": "e5ac2c2d0112188b9b10a069ac1ae65c", "status": "REDIRECT_REQUIRED", "challengeMessage": null, "answerFieldLabel": null, "redirectUrl": "https://demobank.finapi.io?state=976641d2-c03f-4919-8dac-16ccfd24b4e0", "redirectContext": "976641d2-c03f-4919-8dac-16ccfd24b4e0", "redirectContextField": "state", "twoStepProcedures": null, "photoTanMimeType": null, "photoTanData": null, "opticalData": null } } ], "date": "2019-11-27 11:20:21.261", "requestId": "selfgen-fece3d6c-a0f0-43ea-a910-7e9ca7a7b1f6", "endpoint": "POST /api/v1/bankConnections/import", "authContext": "1/18", "bank": "20100 - Erste Group Bank AG" } |
Step #3 The client application should redirect the end-user to the given redirectUrl. Example GET https://demobank.finapi.io?state=976641d2-c03f-4919-8dac-16ccfd24b4e0 HTTP/1.1 | |
Step #4 When the end-user successfully completes the authentication process on the bank’s side, he is redirected to the URL given on the step #1. Additionally, the bank adds some more data to the URL (as query parameters). But the most important part for the client application is this Example GET https://customer.io?state=976641d2-c03f-4919-8dac-16ccfd24b4e0&code=1e065516-0e9a-4f53-b5a6-140e69a3bf70 HTTP/1.1 | |
Step #5 Mandatory request fields
Explanation The client application submits a query string as a value of | POST /api/v1/bankConnections/import HTTP/1.1 Content-Type: application/json Accept: application/json Authorization: Bearer <user's access token> { "bankId": 278985, "interface": "XS2A", "storeSecrets": true, "redirectUrl": "https://customer.io", "multiStepAuthentication": { "hash": "e5ac2c2d0112188b9b10a069ac1ae65c", "redirectCallback": "code=MtNH97ZTa2wNDOWOSswgqddbZAgFzyXee3DNFI0fvFu8qA5OHJgdLVcGL8nTmplj&state=976641d2-c03f-4919-8dac-16ccfd24b4e0" } } |
Step #6 How to recognize the step Field Mandatory response fields of
Explanation The bank doesn’t allow to chose any SCA methods, but asks for a decoupled authentication, and then the API responses with this error. The client application should notify the end-user that the bank will send a notification. | HTTP/1.1 510 { "errors": [ { "message": "Bitte bestätigen Sie auf ihrem externen Gerät die Anmeldung", "code": "ADDITIONAL_AUTHENTICATION_REQUIRED", "type": "BUSINESS", "multiStepAuthentication": { "hash": "e5ac2c2d0112188b9b10a069ac1ae65c", "status": "DECOUPLED_AUTH_REQUIRED", "challengeMessage": "Bitte bestätigen Sie auf ihrem externen Gerät die Anmeldung", "answerFieldLabel": null, "redirectUrl": null, "redirectContext": null, "redirectContextField": null, "twoStepProcedures": null, "photoTanMimeType": null, "photoTanData": null, "opticalData": null } } ], "date": "2019-11-27 10:35:17.682", "requestId": "selfgen-9f035aca-d094-42d7-9285-a3eae9d5a4a9", "endpoint": "POST /api/v1/bankConnections/import", "authContext": "1/18", "bank": "20100 - Erste Group Bank AG" } |
Step #7 Mandatory request fields
Explanation The client application asks the API to continue the authentication process and send a notification to the end-user. Value of | POST /api/v1/bankConnections/import HTTP/1.1 Content-Type: application/json Accept: application/json Authorization: Bearer <user's access token> { "bankId": 278985, "interface": "XS2A", "storeSecrets": true, "redirectUrl": "https://customer.io", "multiStepAuthentication": { "hash": "e5ac2c2d0112188b9b10a069ac1ae65c", "redirectCallback": "code=MtNH97ZTa2wNDOWOSswgqddbZAgFzyXee3DNFI0fvFu8qA5OHJgdLVcGL8nTmplj&state=976641d2-c03f-4919-8dac-16ccfd24b4e0", "decoupledCallback": true } } |
Step #8 How to recognize the step Field Mandatory response fields of
Explanation The API returns this error if the authentication is still not completed on the bank side. The client application should continue repeating a step #7 while the API returns this error. | HTTP/1.1 510 { "errors": [ { "message": null, "code": "ADDITIONAL_AUTHENTICATION_REQUIRED", "type": "BUSINESS", "multiStepAuthentication": { "hash": "e5ac2c2d0112188b9b10a069ac1ae65c", "status": "DECOUPLED_AUTH_IN_PROGRESS", "challengeMessage": null, "answerFieldLabel": null, "redirectUrl": null, "redirectContext": null, "redirectContextField": null, "twoStepProcedures": null, "photoTanMimeType": null, "photoTanData": null, "opticalData": null } } ], "date": "2019-11-28 14:07:07.134", "requestId": "selfgen-71a9c52c-7c94-495a-831c-09b8e2f71d12", "endpoint": "POST /api/v1/bankConnections/import", "authContext": "2068/1610639", "bank": "20100 - Erste Group Bank AG" } |
Step #9 Mandatory request fields
Explanation The client application asks the API to continue the authentication process and send a notification to the end-user. Value of | POST /api/v1/bankConnections/import HTTP/1.1 Content-Type: application/json Accept: application/json Authorization: Bearer <user's access token> { "bankId": 278985, "interface": "XS2A", "storeSecrets": true, "redirectUrl": "https://customer.io", "multiStepAuthentication": { "hash": "e5ac2c2d0112188b9b10a069ac1ae65c", "redirectCallback": "code=MtNH97ZTa2wNDOWOSswgqddbZAgFzyXee3DNFI0fvFu8qA5OHJgdLVcGL8nTmplj&state=976641d2-c03f-4919-8dac-16ccfd24b4e0", "decoupledCallback": true } } |
Step #10 How to recognize the step Field Mandatory response fields of
Explanation The bank requires the decoupled authnencation two times. The client application should notify the end-user that the bank will send a notification. | HTTP/1.1 510 { "errors": [ { "message": null, "code": "ADDITIONAL_AUTHENTICATION_REQUIRED", "type": "BUSINESS", "multiStepAuthentication": { "hash": "e5ac2c2d0112188b9b10a069ac1ae65c", "status": "DECOUPLED_AUTH_REQUIRED", "challengeMessage": null, "answerFieldLabel": null, "redirectUrl": null, "redirectContext": null, "redirectContextField": null, "twoStepProcedures": null, "photoTanMimeType": null, "photoTanData": null, "opticalData": null } } ], "date": "2019-11-28 14:08:06.450", "requestId": "selfgen-c8fc6cef-9018-4b7e-ae60-8441ad372af8", "endpoint": "POST /api/v1/bankConnections/import", "authContext": "2068/1610639", "bank": "20100 - Erste Group Bank AG" } |
Step #11 Mandatory request fields
Explanation The client application asks the API to continue the authentication process and send a notification to the end-user. Value of | POST /api/v1/bankConnections/import HTTP/1.1 Content-Type: application/json Accept: application/json Authorization: Bearer <user's access token> { "bankId": 278985, "interface": "XS2A", "storeSecrets": true, "redirectUrl": "https://customer.io", "multiStepAuthentication": { "hash": "e5ac2c2d0112188b9b10a069ac1ae65c", "redirectCallback": "code=MtNH97ZTa2wNDOWOSswgqddbZAgFzyXee3DNFI0fvFu8qA5OHJgdLVcGL8nTmplj&state=976641d2-c03f-4919-8dac-16ccfd24b4e0", "decoupledCallback": true } } |
Step #12 How to recognize the step Field Mandatory response fields of
Explanation The API returns this error if the authentication is still not completed on the bank side. The client application should continue repeating a step #11 while the API returns this error. | HTTP/1.1 510 { "errors": [ { "message": null, "code": "ADDITIONAL_AUTHENTICATION_REQUIRED", "type": "BUSINESS", "multiStepAuthentication": { "hash": "e5ac2c2d0112188b9b10a069ac1ae65c", "status": "DECOUPLED_AUTH_IN_PROGRESS", "challengeMessage": null, "answerFieldLabel": null, "redirectUrl": null, "redirectContext": null, "redirectContextField": null, "twoStepProcedures": null, "photoTanMimeType": null, "photoTanData": null, "opticalData": null } } ], "date": "2019-11-28 14:08:05.753", "requestId": "selfgen-230b3bf1-c33f-4867-ab2b-1cc06ee6a00a", "endpoint": "POST /api/v1/bankConnections/import", "authContext": "2068/1610639", "bank": "20100 - Erste Group Bank AG" } |
Step #13 Mandatory request fields
Explanation The client application asks the API to continue the authentication process and send a notification to the end-user. Value of | POST /api/v1/bankConnections/import HTTP/1.1 Content-Type: application/json Accept: application/json Authorization: Bearer <user's access token> { "bankId": 278985, "interface": "XS2A", "storeSecrets": true, "redirectUrl": "https://customer.io", "multiStepAuthentication": { "hash": "e5ac2c2d0112188b9b10a069ac1ae65c", "redirectCallback": "code=MtNH97ZTa2wNDOWOSswgqddbZAgFzyXee3DNFI0fvFu8qA5OHJgdLVcGL8nTmplj&state=976641d2-c03f-4919-8dac-16ccfd24b4e0", "decoupledCallback": true } } |
Step #14 The API completes the import process and returns a bank connection resource. | { "id": 3160933, "bankId": 278985, "name": null, "bankingUserId": null, "bankingCustomerId": null, "bankingPin": null, "type": "ONLINE", "updateStatus": "IN_PROGRESS", "categorizationStatus": "READY", ... } |
For unlicensed mandators (web form)
Embedded approach
When applicable?
If a bank interface has neither DECOUPLED_APPROACH
nor REDIRECT_APPROACH
properties.
Step | HTTP(S) request |
---|---|
Step #1 Mandatory request fields
Explanation The client application loads a bank, chosen by the end-user, and then triggers a request to “Import a bank connection” REST service. | POST /api/v1/bankConnections/import HTTP/1.1 Content-Type: application/json Accept: application/json Authorization: Bearer <user's access token> { "bankId": 277672, "interface": "XS2A" } |
Step #2 How to recognize the step
Mandatory response fields:
Explanation According to the license type of a mandator, the client application cannot handle user’s credentials by itself. That’s why the web form will handle the whole process of the import. The client application should store the web form ID (field | HTTP/1.1 451 Location: https://finapi.host.io/webForm/xihSWhdao5iVttO_zIUsfZ_adzt4fRlyr7lNfEuPLTy4obC5a6R3oAPK4p5yYE6FX4mniQVW3IOe0bmAcdekpLP6eJkrrWv0J6TlU3aUuzLTyFiy8nZ2MRx9KP8K0Lni { "errors": [ { "message": "3", "code": "WEB_FORM_REQUIRED", "type": "BUSINESS", "multiStepAuthentication": null } ], "date": "2019-11-27 08:39:49.343", "requestId": "selfgen-cb26cd43-a4ef-4352-a003-400c20e6b8af", "endpoint": "POST /api/v1/bankConnections/import", "authContext": "1/18", "bank": "00000000 - FinAPI Test Bank" } |
Step #3 Optional parameters:
Explanation The end-user should open the web-form in order to continue the import process. This process might include a few steps: entering user’s credentials and account references (IBAN’s), selecting an SCA method and providing a challenge response. Example GET https://finapi.host.io/webForm/xihSWhdao5iVttO_zIUsfZ_adzt4fRlyr7lNfEuPLTy4obC5a6R3oAPK4p5yYE6FX4mniQVW3IOe0bmAcdekpLP6eJkrrWv0J6TlU3aUuzLTyFiy8nZ2MRx9KP8K0Lni?redirectUrl=https://customer.io HTTP/1.1 | |
Step #4 When the end-user successfully completes the authentication process on the web-form, he is either redirected back to the client's application (if the . GET https://customer.io HTTP/1.1 | |
Step #5 Mandatory request fields
Explanation As the web-form will never show any error messages to the end-user, you might want to check whether the import was successful or not. | GET /api/v1/webForms/3 HTTP/1.1 Accept: application/json Authorization: Bearer <user's access token> |
Step #6 Explanation The response includes the actual service response code/body. | HTTP/1.1 200 { "id": 3, "token": "eJUCOGccI9DRMyXNpN0_gOE8Ddhm5dtRQtY76T04ir4vvKoMSv1j6t7oQEBeZP9gI88fQCQzfqm02g8t71qZYTA9_RRvAVR8o0FvoPlegEVmKKw4XqrBQtsNX6pzwPGk", "status": "COMPLETED", "serviceResponseCode": 201, "serviceResponseBody": "{\n \"id\": 25,\n \"bankId\": 277672,\n \"name\": \"MSA\",\n \"bankingUserId\": null,\n \"bankingCustomerId\": null,\n \"bankingPin\": null,\n \"type\": \"DEMO\",\n \"updateStatus\": \"IN_PROGRESS\",\n \"categorizationStatus\": \"READY\",\n \"lastManualUpdate\": null,\n \"lastAutoUpdate\": null,\n \"ibanOnlyMoneyTransferSupported\": false,\n \"ibanOnlyDirectDebitSupported\": false,\n \"collectiveMoneyTransferSupported\": false,\n \"defaultTwoStepProcedureId\": null,\n \"twoStepProcedures\": [],\n \"interfaces\": [\n {\n \"interface\": \"XS2A\",\n \"loginCredentials\": [\n {\n \"label\": \"Onlinebanking-ID\",\n \"value\": \"XXXXX\"\n },\n {\n \"label\": \"PIN\",\n \"value\": null\n }\n ],\n \"defaultTwoStepProcedureId\": null,\n \"twoStepProcedures\": [\n {\n \"procedureId\": \"DEMO-TSP-01\",\n \"procedureName\": \"SMS\",\n \"procedureChallengeType\": \"TEXT\",\n \"implicitExecute\": false\n },\n {\n \"procedureId\": \"DEMO-TSP-02\",\n \"procedureName\": \"PUSH\",\n \"procedureChallengeType\": \"TEXT\",\n \"implicitExecute\": false\n }\n ],\n \"aisConsent\": {\n \"status\": \"PRESENT\",\n \"expiresAt\": \"2019-11-27 09:29:51.000\"\n },\n \"lastManualUpdate\": null,\n \"lastAutoUpdate\": null\n }\n ],\n \"accountIds\": [\n 2\n ],\n \"owners\": null,\n \"furtherLoginNotRecommended\": false,\n \"bank\": {\n \"id\": 277672,\n \"name\": \"FinAPI Test Bank\",\n \"loginHint\": null,\n \"bic\": null,\n \"blzs\": [\n \"00000000\"\n ],\n \"blz\": \"00000000\",\n \"location\": null,\n \"city\": null,\n \"isSupported\": true,\n \"isTestBank\": true,\n \"popularity\": 1,\n \"health\": 100,\n \"loginFieldUserId\": \"Onlinebanking-ID\",\n \"loginFieldCustomerId\": null,\n \"loginFieldPin\": \"PIN\",\n \"pinsAreVolatile\": false,\n \"isCustomerIdPassword\": false,\n \"supportedDataSources\": [\n \"FINTS_SERVER\"\n ],\n \"interfaces\": [\n {\n \"interface\": \"XS2A\",\n \"tppAuthenticationGroup\": null,\n \"loginCredentials\": [\n {\n \"label\": \"Onlinebanking-ID\",\n \"isSecret\": false,\n \"isVolatile\": false\n },\n {\n \"label\": \"PIN\",\n \"isSecret\": true,\n \"isVolatile\": false\n }\n ],\n \"properties\": [],\n \"loginHint\": null,\n \"health\": 100,\n \"lastCommunicationAttempt\": \"2019-11-27 09:09:51.000\",\n \"lastSuccessfulCommunication\": \"2019-11-27 09:09:51.000\"\n },\n {\n \"interface\": \"FINTS_SERVER\",\n \"tppAuthenticationGroup\": null,\n \"loginCredentials\": [\n {\n \"label\": \"Onlinebanking-ID\",\n \"isSecret\": false,\n \"isVolatile\": false\n },\n {\n \"label\": \"PIN\",\n \"isSecret\": true,\n \"isVolatile\": false\n }\n ],\n \"properties\": [],\n \"loginHint\": null,\n \"health\": 100,\n \"lastCommunicationAttempt\": null,\n \"lastSuccessfulCommunication\": null\n }\n ],\n \"lastCommunicationAttempt\": null,\n \"lastSuccessfulCommunication\": null\n }\n}" } |
Redirect approach
When applicable?
If a bank interface has REDIRECT_APPROACH
property.
Step | HTTP(S) message |
---|---|
Step #1 Mandatory request fields
Explanation The client application loads a bank, chosen by the end-user. Then the application should forward the end-user to a given web-form in order to proceed with further authentication. If the bank requires to prompt the credentials and/or account references, the end-user must provide them in the web-form. | POST /api/v1/bankConnections/import HTTP/1.1 Content-Type: application/json Accept: application/json Authorization: Bearer <user's access token> { "bankId": 277672, "interface": "XS2A" } |
How to recognize the step
Mandatory response fields:
Explanation According to the license type of a mandator, the client application cannot handle user’s credentials by itself. That’s why the web form will handle the whole process of the import. The client application should store the web form ID (field message) and just redirect the end-user to the URL given in the Location header. | HTTP/1.1 451 Location: https://finapi.host.io/webForm/xihSWhdao5iVttO_zIUsfZ_adzt4fRlyr7lNfEuPLTy4obC5a6R3oAPK4p5yYE6FX4mniQVW3IOe0bmAcdekpLP6eJkrrWv0J6TlU3aUuzLTyFiy8nZ2MRx9KP8K0Lni { "errors": [ { "message": "3", "code": "WEB_FORM_REQUIRED", "type": "BUSINESS", "multiStepAuthentication": null } ], "date": "2019-11-27 08:39:49.343", "requestId": "selfgen-cb26cd43-a4ef-4352-a003-400c20e6b8af", "endpoint": "POST /api/v1/bankConnections/import", "authContext": "1/18", "bank": "00000000 - FinAPI Test Bank" } |
Step #3 Optional parameters:
Explanation The end-user should open the web-form in order to continue the import process. This process includes redirecting to the bank’s website and completing the authentication challenge. Example GET https://finapi.host.io/webForm/xihSWhdao5iVttO_zIUsfZ_adzt4fRlyr7lNfEuPLTy4obC5a6R3oAPK4p5yYE6FX4mniQVW3IOe0bmAcdekpLP6eJkrrWv0J6TlU3aUuzLTyFiy8nZ2MRx9KP8K0Lni?redirectUrl=https://customer.io HTTP/1.1 | |
Step #4 The web-form automatically redirects the end-user to the bank’s website. | |
Step #5 When the end-user successfully completes the authentication process on the bank’s side, he is redirected back to the web-form. | |
Step #6 When the end-user successfully completes the authentication process on the web-form, he is redirected back to the client's application. GET https://customer.io HTTP/1.1 | |
Step #7 Mandatory request fields
Explanation As the web-form will never show any error messages to the end-user, you might want to check whether the import was successful or not. | GET /api/v1/webForms/3 HTTP/1.1 Accept: application/json Authorization: Bearer <user's access token> |
Step #8 Explanation The response includes the actual service response code/body. | HTTP/1.1 200 Date:Wed, 27 Nov 2019 12:14:32 GMT { "id": 3, "token": "xihSWhdao5iVttO_zIUsfZ_adzt4fRlyr7lNfEuPLTy4obC5a6R3oAPK4p5yYE6FX4mniQVW3IOe0bmAcdekpLP6eJkrrWv0J6TlU3aUuzLTyFiy8nZ2MRx9KP8K0Lni", "status": "COMPLETED", "serviceResponseCode": 201, "serviceResponseBody": "{\n \"id\": 25,\n \"bankId\": 277672,\n \"name\": \"MSA\",\n \"bankingUserId\": null,\n \"bankingCustomerId\": null,\n \"bankingPin\": null,\n \"type\": \"DEMO\",\n \"updateStatus\": \"IN_PROGRESS\",\n \"categorizationStatus\": \"READY\",\n \"lastManualUpdate\": null,\n \"lastAutoUpdate\": null,\n \"ibanOnlyMoneyTransferSupported\": false,\n \"ibanOnlyDirectDebitSupported\": false,\n \"collectiveMoneyTransferSupported\": false,\n \"defaultTwoStepProcedureId\": null,\n \"twoStepProcedures\": [],\n \"interfaces\": [\n {\n \"interface\": \"XS2A\",\n \"loginCredentials\": [\n {\n \"label\": \"Onlinebanking-ID\",\n \"value\": \"XXXXX\"\n },\n {\n \"label\": \"PIN\",\n \"value\": null\n }\n ],\n \"defaultTwoStepProcedureId\": null,\n \"twoStepProcedures\": [\n {\n \"procedureId\": \"DEMO-TSP-01\",\n \"procedureName\": \"SMS\",\n \"procedureChallengeType\": \"TEXT\",\n \"implicitExecute\": false\n },\n {\n \"procedureId\": \"DEMO-TSP-02\",\n \"procedureName\": \"PUSH\",\n \"procedureChallengeType\": \"TEXT\",\n \"implicitExecute\": false\n }\n ],\n \"aisConsent\": {\n \"status\": \"PRESENT\",\n \"expiresAt\": \"2019-11-27 09:29:51.000\"\n },\n \"lastManualUpdate\": null,\n \"lastAutoUpdate\": null\n }\n ],\n \"accountIds\": [\n 2\n ],\n \"owners\": null,\n \"furtherLoginNotRecommended\": false,\n \"bank\": {\n \"id\": 277672,\n \"name\": \"FinAPI Test Bank\",\n \"loginHint\": null,\n \"bic\": null,\n \"blzs\": [\n \"00000000\"\n ],\n \"blz\": \"00000000\",\n \"location\": null,\n \"city\": null,\n \"isSupported\": true,\n \"isTestBank\": true,\n \"popularity\": 1,\n \"health\": 100,\n \"loginFieldUserId\": \"Onlinebanking-ID\",\n \"loginFieldCustomerId\": null,\n \"loginFieldPin\": \"PIN\",\n \"pinsAreVolatile\": false,\n \"isCustomerIdPassword\": false,\n \"supportedDataSources\": [\n \"FINTS_SERVER\"\n ],\n \"interfaces\": [\n {\n \"interface\": \"XS2A\",\n \"tppAuthenticationGroup\": null,\n \"loginCredentials\": [\n {\n \"label\": \"Onlinebanking-ID\",\n \"isSecret\": false,\n \"isVolatile\": false\n },\n {\n \"label\": \"PIN\",\n \"isSecret\": true,\n \"isVolatile\": false\n }\n ],\n \"properties\": [],\n \"loginHint\": null,\n \"health\": 100,\n \"lastCommunicationAttempt\": \"2019-11-27 09:09:51.000\",\n \"lastSuccessfulCommunication\": \"2019-11-27 09:09:51.000\"\n },\n {\n \"interface\": \"FINTS_SERVER\",\n \"tppAuthenticationGroup\": null,\n \"loginCredentials\": [\n {\n \"label\": \"Onlinebanking-ID\",\n \"isSecret\": false,\n \"isVolatile\": false\n },\n {\n \"label\": \"PIN\",\n \"isSecret\": true,\n \"isVolatile\": false\n }\n ],\n \"properties\": [],\n \"loginHint\": null,\n \"health\": 100,\n \"lastCommunicationAttempt\": null,\n \"lastSuccessfulCommunication\": null\n }\n ],\n \"lastCommunicationAttempt\": null,\n \"lastSuccessfulCommunication\": null\n }\n}" } |
Decoupled approach
When applicable?
If a bank interface has DECOUPLED_APPROACH
property.
Step | HTTP(S) message |
---|---|
Step #1 Mandatory request fields
Explanation The client application loads a bank, chosen by the end-user. Then the application should forward the end-user to a given web-form in order to proceed with further authentication. If the bank requires to prompt the credentials and/or account references, the end-user must provide them in the web-form. | POST /api/v1/bankConnections/import HTTP/1.1 Content-Type: application/json Accept: application/json Authorization: Bearer <user's access token> { "bankId": 277672, "interface": "XS2A" } |
How to recognize the step
Mandatory response fields:
Explanation According to the license type of a mandator, the client application cannot handle user’s credentials by itself. That’s why the web form will handle the whole process of the import. The client application should store the web form ID (field message) and just redirect the end-user to the URL given in the Location header. | HTTP/1.1 451 Location: https://finapi.host.io/webForm/xihSWhdao5iVttO_zIUsfZ_adzt4fRlyr7lNfEuPLTy4obC5a6R3oAPK4p5yYE6FX4mniQVW3IOe0bmAcdekpLP6eJkrrWv0J6TlU3aUuzLTyFiy8nZ2MRx9KP8K0Lni { "errors": [ { "message": "3", "code": "WEB_FORM_REQUIRED", "type": "BUSINESS", "multiStepAuthentication": null } ], "date": "2019-11-27 08:39:49.343", "requestId": "selfgen-cb26cd43-a4ef-4352-a003-400c20e6b8af", "endpoint": "POST /api/v1/bankConnections/import", "authContext": "1/18", "bank": "00000000 - FinAPI Test Bank" } |
Step #3 Optional parameters:
Explanation The end-user should open the web-form in order to continue the import process. This process might include a few steps: entering user’s credentials and account references (IBAN’s), selecting an SCA method and providing a challenge response. Example GET https://finapi.host.io/webForm/xihSWhdao5iVttO_zIUsfZ_adzt4fRlyr7lNfEuPLTy4obC5a6R3oAPK4p5yYE6FX4mniQVW3IOe0bmAcdekpLP6eJkrrWv0J6TlU3aUuzLTyFiy8nZ2MRx9KP8K0Lni?redirectUrl=https://customer.io HTTP/1.1 | |
Step #4 When the end-user successfully completes the authentication process on the web-form, he is redirected back to the client's application. GET https://customer.io HTTP/1.1 | |
Step #5 Mandatory request fields
Explanation As the web-form will never show any error messages to the end-user, you might want to check whether the import was successful or not. | GET /api/v1/webForms/3 HTTP/1.1 Accept: application/json Authorization: Bearer <user's access token> |
Step #6 Explanation The response includes the actual service response code/body. | HTTP/1.1 200 Date:Wed, 27 Nov 2019 12:14:32 GMT { "id": 3, "token": "xihSWhdao5iVttO_zIUsfZ_adzt4fRlyr7lNfEuPLTy4obC5a6R3oAPK4p5yYE6FX4mniQVW3IOe0bmAcdekpLP6eJkrrWv0J6TlU3aUuzLTyFiy8nZ2MRx9KP8K0Lni", "status": "COMPLETED", "serviceResponseCode": 201, "serviceResponseBody": "{\n \"id\": 25,\n \"bankId\": 277672,\n \"name\": \"MSA\",\n \"bankingUserId\": null,\n \"bankingCustomerId\": null,\n \"bankingPin\": null,\n \"type\": \"DEMO\",\n \"updateStatus\": \"IN_PROGRESS\",\n \"categorizationStatus\": \"READY\",\n \"lastManualUpdate\": null,\n \"lastAutoUpdate\": null,\n \"ibanOnlyMoneyTransferSupported\": false,\n \"ibanOnlyDirectDebitSupported\": false,\n \"collectiveMoneyTransferSupported\": false,\n \"defaultTwoStepProcedureId\": null,\n \"twoStepProcedures\": [],\n \"interfaces\": [\n {\n \"interface\": \"XS2A\",\n \"loginCredentials\": [\n {\n \"label\": \"Onlinebanking-ID\",\n \"value\": \"XXXXX\"\n },\n {\n \"label\": \"PIN\",\n \"value\": null\n }\n ],\n \"defaultTwoStepProcedureId\": null,\n \"twoStepProcedures\": [\n {\n \"procedureId\": \"DEMO-TSP-01\",\n \"procedureName\": \"SMS\",\n \"procedureChallengeType\": \"TEXT\",\n \"implicitExecute\": false\n },\n {\n \"procedureId\": \"DEMO-TSP-02\",\n \"procedureName\": \"PUSH\",\n \"procedureChallengeType\": \"TEXT\",\n \"implicitExecute\": false\n }\n ],\n \"aisConsent\": {\n \"status\": \"PRESENT\",\n \"expiresAt\": \"2019-11-27 09:29:51.000\"\n },\n \"lastManualUpdate\": null,\n \"lastAutoUpdate\": null\n }\n ],\n \"accountIds\": [\n 2\n ],\n \"owners\": null,\n \"furtherLoginNotRecommended\": false,\n \"bank\": {\n \"id\": 277672,\n \"name\": \"FinAPI Test Bank\",\n \"loginHint\": null,\n \"bic\": null,\n \"blzs\": [\n \"00000000\"\n ],\n \"blz\": \"00000000\",\n \"location\": null,\n \"city\": null,\n \"isSupported\": true,\n \"isTestBank\": true,\n \"popularity\": 1,\n \"health\": 100,\n \"loginFieldUserId\": \"Onlinebanking-ID\",\n \"loginFieldCustomerId\": null,\n \"loginFieldPin\": \"PIN\",\n \"pinsAreVolatile\": false,\n \"isCustomerIdPassword\": false,\n \"supportedDataSources\": [\n \"FINTS_SERVER\"\n ],\n \"interfaces\": [\n {\n \"interface\": \"XS2A\",\n \"tppAuthenticationGroup\": null,\n \"loginCredentials\": [\n {\n \"label\": \"Onlinebanking-ID\",\n \"isSecret\": false,\n \"isVolatile\": false\n },\n {\n \"label\": \"PIN\",\n \"isSecret\": true,\n \"isVolatile\": false\n }\n ],\n \"properties\": [],\n \"loginHint\": null,\n \"health\": 100,\n \"lastCommunicationAttempt\": \"2019-11-27 09:09:51.000\",\n \"lastSuccessfulCommunication\": \"2019-11-27 09:09:51.000\"\n },\n {\n \"interface\": \"FINTS_SERVER\",\n \"tppAuthenticationGroup\": null,\n \"loginCredentials\": [\n {\n \"label\": \"Onlinebanking-ID\",\n \"isSecret\": false,\n \"isVolatile\": false\n },\n {\n \"label\": \"PIN\",\n \"isSecret\": true,\n \"isVolatile\": false\n }\n ],\n \"properties\": [],\n \"loginHint\": null,\n \"health\": 100,\n \"lastCommunicationAttempt\": null,\n \"lastSuccessfulCommunication\": null\n }\n ],\n \"lastCommunicationAttempt\": null,\n \"lastSuccessfulCommunication\": null\n }\n}" } |