Table of Contents

For licensed mandators (no web form)

Embedded approach

Info

When applicable?

If a bank interface has neither DECOUPLED_APPROACH nor REDIRECT_APPROACH properties.

...

Step

...

Request/response example

...

Step #1
Import a new bank connection

Mandatory request fields

bankId
interface
loginCredentials
- if the chosen bank interface has any items in
loginCredentials field
accountReferences
- if the chosen bank interface has
DETAILED_CONSENT property

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 DETAILED_CONSENT property: if it’s presented, the app asks the end-user for a list of IBANs he wants to import. And finally the application triggers the “Import a new bank connection” REST service.

...

Code Block

language	json

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
Receive a list of two step procedures
(an optional step)

How to recognise the step

Field errors.multiStepAuthentication.status has TWO_STEP_PROCEDURE_REQUIRED value.

Mandatory response fields of multiStepAuthentication object:

hash
status
twoStepProcedures

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.

Code Block

language	json

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
Import a new bank connection
(an optional step)

Mandatory request fields

all fields from the previous request
multiStepAuthentication.hash
- the value should be taken from the response on step #2
twoStepProcedureId
- field
procedureId of the chosen two-step procedure

Explanation

The client application asks the end-user to chose a two-step procedure and then submits it to the API. Value of hash field points to the original request.

Code Block

language	json

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
Receive an MSA challenge message

How to recognise the step

Field errors.multiStepAuthentication.status has CHALLENGE_RESPONSE_REQUIRED value.

Mandatory response fields of multiStepAuthentication object:

hash
status
the following fields are presented depending on the two-step procedure type:
- for type = TEXT:
  - challengeMessage
- for type = PHOTO:
  - photoTanMimeType
  - photoTanData
- for type = FLICKER_CODE:
  - opticalData

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.

Code Block

language	json

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
Import a new bank connection

Mandatory request fields

all fields from the previous request
challengeResponse
- the answer from the end-user

Explanation

The client application asks for the challenge reponse and submits it back to the API. Value of hash field points to the original request.

...

Code Block

language	json

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
Bank connection

The API completes the import process and returns a bank connection resource.

...

Code Block

language	json

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

Info

When applicable?

If a bank interface has REDIRECT_APPROACH property.

...

Step

...

Request/response example

...

Step #1
Import a new bank connection.

Mandatory request fields

bankId
interface
redirectUrl
- URL of the client’s endpoint that handles a redirect from the bank
loginCredentials
- if the chosen bank interface has any items in
loginCredentials field
accountReferences
- if the chosen bank interface has
DETAILED_CONSENT property

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 DETAILED_CONSENT property: if it’s presented, the app asks the end-user for a list of IBANs he wants to import. And finally the application triggers the “Import a new bank connection” REST service.

...

Code Block

language	json

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
Receive a redirect URL

How to recognise the step

Field errors.multiStepAuthentication.status has REDIRECT_REQUIRED value.

Mandatory response fields of multiStepAuthentication object:

hash
status
redirectUrl
redirectContext
redirectContextField

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 redirectContext and redirectContextField fields internally, as they will be required on the subsequent steps.

...

Code Block

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
Redirect to bank

The client application should redirect the end-user to the given redirectUrl.

Example

Code Block
GET https://demobank.finapi.io?state=976641d2-c03f-4919-8dac-16ccfd24b4e0 HTTP/1.1

...

Step #4
Redirect back

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 state parameter (generally speaking, the name of parameter is provided on a step #2 as a value of redirectContextField field): the client application can use its value to recognize the end-user that was redirected by the bank - the value should match the one given on a step #2 in redirectContext field.

Example

Code Block
GET https://customer.io?state=976641d2-c03f-4919-8dac-16ccfd24b4e0&code=1e065516-0e9a-4f53-b5a6-140e69a3bf70 HTTP/1.1

Step #5
Import a bank connection

Mandatory request fields

all fields from the previous request
hash
redirectCallback
- the whole query string received on a step #4

Explanation

The client application submits a query string as a value of redirectCallback field. The API processes the given string, extracts required data and continues the authentication process.

...

Code Block

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
Bank connection

The API completes the import process and returns a bank connection resource.

...

Code Block

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

Info

When applicable?

If a bank interface has DECOUPLED_APPROACH property.

...

Step

...

Request/response example

...

Step #1
Import a new bank connection

Mandatory request fields

bankId
interface
loginCredentials
- if the chosen bank interface has any items in
loginCredentials field
accountReferences
- if the chosen bank interface has
DETAILED_CONSENT property

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 DETAILED_CONSENT property: if it’s presented, the app asks the end-user for a list of IBANs he wants to import. And finally the application triggers the “Import a new bank connection” REST service.

...

Code Block

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
Receive a list of two step procedures
(an optional step)

How to recognise the step

Field errors.multiStepAuthentication.status has TWO_STEP_PROCEDURE_REQUIRED value.

Mandatory response fields of multiStepAuthentication object:

hash
status
twoStepProcedures

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.

...

Code Block

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
Import a new bank connection
(an optional step)

Mandatory request fields

all fields from the previous request
multiStepAuthentication.hash
- the value should be taken from the response on step #2
twoStepProcedureId
- field
procedureId of the chosen two-step procedure

Explanation

The client application asks the end-user to chose a two-step procedure and then submits it to the API. Value of hash field points to the original request.

...

Code Block

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
Receive an error message that the decoupled approach is required

How to recognise the step

Field errors.multiStepAuthentication.status has DECOUPLED_AUTH_REQUIRED value.

Mandatory response fields of multiStepAuthentication object:

hash
status
challengeMessage
- if any message was provided by the bank

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.

...

Code Block

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
Import a new bank connection

Mandatory request fields

all fields from the previous request
decoupledCallback
- this is a simple boolean field that signals to the API that it can now ask the bank to send a notifciation to the end-user.

Explanation

The client application asks the API to continue the authentication process and send a notification to the end-user. Value of hash field points to the original request.

...

Code Block

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
Receive an error message that the decoupled authentication is still in progress
(an optional step)

How to recognise the step

Field errors.multiStepAuthentication.status has DECOUPLED_AUTH_IN_PROGRESS value.

Mandatory response fields of multiStepAuthentication object:

hash
status

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.

...

Code Block

language	json

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
Import a bank connection
(an optional step)

Mandatory request fields

all fields from the previous request
decoupledCallback
- this is a simple boolean field that signals to the API that it can now ask the bank to send a notifciation to the end-user.

Explanation

The client application asks the API to continue the authentication process and check the authentication status on the bank side.

...

Code Block

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
Bank connection

The API completes the import process and returns a bank connection resource.

...

Code Block

language	json

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)

Info
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
Import a new bank connection

Mandatory request fields

bankId
interface
loginCredentials
- if the chosen bank interface has any items in
loginCredentials field
accountReferences
- if the chosen bank interface has
DETAILED_CONSENT property

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 DETAILED_CONSENT property (this bank doesn’t have it): if it’s presented, the app asks the end-user for a list of IBANs he wants to import. And finally the application triggers the “Import a new bank connection” REST service.

Code Block

language	json

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
Receive a redirect URL

How to recognise the step

Field errors.multiStepAuthentication.status has REDIRECT_REQUIRED value.

Mandatory response fields of multiStepAuthentication object:

hash
status
redirectUrl
redirectContext
redirectContextField

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 redirectContext and redirectContextField fields internally, as they will be required on the subsequent steps.

...

Code Block

language	json

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
Redirect to bank

The client application should redirect the end-user to the given redirectUrl.

Example

Code Block
GET https://demobank.finapi.io?state=976641d2-c03f-4919-8dac-16ccfd24b4e0 HTTP/1.1

...

Step #4
Redirect back

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 state parameter (generally speaking, the name of parameter is provided on a step #2 as a value of redirectContextField field): the client application can use its value to recognize the end-user that was redirected by the bank - the value should match the one given on a step #2 in redirectContext field.

Example

Code Block
GET https://customer.io?state=976641d2-c03f-4919-8dac-16ccfd24b4e0&code=1e065516-0e9a-4f53-b5a6-140e69a3bf70 HTTP/1.1

Step #5
Import a bank connection

Mandatory request fields

all fields from the previous request
hash
redirectCallback
- the whole query string received on a step #4

Explanation

The client application submits a query string as a value of redirectCallback field. The API processes the given string, extracts required data and continues the authentication process.

...

Code Block

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
Receive an error message that the decoupled approach is required

How to recognize the step

Field errors.multiStepAuthentication.status has DECOUPLED_AUTH_REQUIRED value.

Mandatory response fields of multiStepAuthentication object:

hash
status
challengeMessage
- if any message was provided by the bank

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.

...

Code Block

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
Import a new bank connection

Mandatory request fields

all fields from the previous request
decoupledCallback
- this is a simple boolean field that signals to the API that it can now ask the bank to send a notification to the end-user.

Explanation

The client application asks the API to continue the authentication process and send a notification to the end-user. Value of hash field points to the original request.

...

Code Block

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
Receive an error message that the decoupled authentication is still in progress
(an optional step)

How to recognize the step

Field errors.multiStepAuthentication.status has DECOUPLED_AUTH_IN_PROGRESS value.

Mandatory response fields of multiStepAuthentication object:

hash
status

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.

...

Code Block

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
Import a new bank connection

Mandatory request fields

all fields from the previous request

Explanation

The client application asks the API to continue the authentication process and send a notification to the end-user. Value of hash field points to the original request.

Code Block

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
Receive an error message that the decoupled approach is required

How to recognize the step

Field errors.multiStepAuthentication.status has DECOUPLED_AUTH_REQUIRED value.

Mandatory response fields of multiStepAuthentication object:

hash
status
challengeMessage
- if any message was provided by the bank

Explanation

The bank requires the decoupled authnencation two times. The client application should notify the end-user that the bank will send a notification.

Code Block

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
Import a new bank connection

Mandatory request fields

all fields from the previous request

Explanation

The client application asks the API to continue the authentication process and send a notification to the end-user. Value of hash field points to the original request.

...

Code Block

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
Receive an error message that the decoupled authentication is still in progress
(an optional step)

How to recognize the step

Field errors.multiStepAuthentication.status has DECOUPLED_AUTH_IN_PROGRESS value.

Mandatory response fields of multiStepAuthentication object:

hash
status

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.

Code Block

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
Import a new bank connection

Mandatory request fields

all fields from the previous request

Explanation

The client application asks the API to continue the authentication process and send a notification to the end-user. Value of hash field points to the original request.

Code Block

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
Bank connection

The API completes the import process and returns a bank connection resource.

Code Block

{
  "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

Info

When applicable?

If a bank interface has neither DECOUPLED_APPROACH nor REDIRECT_APPROACH properties.

...

Step

...

HTTP(S) request

...

Step #1
Import a new bank connection

Mandatory request fields

bankId
interface

Explanation

The client application loads a bank, chosen by the end-user, and then triggers a request to “Import a bank connection” REST service.

...

Code Block

language	json

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
Receive an error message with a web-form link

How to recognize the step

HTTP status code is 451
Field errors.code has WEB_FORM_REQUIRED value.

Mandatory response fields:

Location header with the web-form link.
message contains an indentifier of the web form

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.

Code Block

language	json

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
Redirect the end-user to the web-form

Optional parameters:

redirectUrl - an URL where the end-user will be redirected to when the process is completed (find more details in the web form’s documentation)
callbackUrl - an URL which will be triggered once the import process is completed (find more details in the web form’s documentation)

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

Code Block

GET https://finapi.host.io/webForm/xihSWhdao5iVttO_zIUsfZ_adzt4fRlyr7lNfEuPLTy4obC5a6R3oAPK4p5yYE6FX4mniQVW3IOe0bmAcdekpLP6eJkrrWv0J6TlU3aUuzLTyFiy8nZ2MRx9KP8K0Lni?redirectUrl=https://customer.io HTTP/1.1

...

Step #4
Redirect back to the client’s application

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 .

Code Block
GET https://customer.io HTTP/1.1

...

Step #5
Get the web-form status with the actual API response.

Mandatory request fields

id
- identifer of the web form given on step #2

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.

...

Code Block

language	json

GET /api/v1/webForms/3 HTTP/1.1
Accept: application/json
Authorization: Bearer <user's access token>

...

Step #6
Receive a web-form resource.

Explanation

The response includes the actual service response code/body.

...

Code Block

language	json

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

Info

When applicable?

If a bank interface has REDIRECT_APPROACH property.

...

Step

...

HTTP(S) message

...

Step #1
Import a new bank connection

Mandatory request fields

bankId
interface

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.

...

Code Block

language	json

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

HTTP status code is 451
Field errors.code has WEB_FORM_REQUIRED value.

Mandatory response fields:

Location header with the web-form link.
message contains an indentifier of the web form

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.

Code Block

language	json

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
Redirect the end-user to the web-form

Optional parameters:

redirectUrl - an URL where the end-user will be redirected to when the process is completed (find more details in the web form’s documentation)
callbackUrl - an URL which will be triggered once the import process is completed (find more details in the web form’s documentation)

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

Code Block

GET https://finapi.host.io/webForm/xihSWhdao5iVttO_zIUsfZ_adzt4fRlyr7lNfEuPLTy4obC5a6R3oAPK4p5yYE6FX4mniQVW3IOe0bmAcdekpLP6eJkrrWv0J6TlU3aUuzLTyFiy8nZ2MRx9KP8K0Lni?redirectUrl=https://customer.io HTTP/1.1

...

Step #4
Redirect to bank

The web-form automatically redirects the end-user to the bank’s website.

...

Step #5
Redirect back

When the end-user successfully completes the authentication process on the bank’s side, he is redirected back to the web-form.

...

Step #6
Redirect back to the client’s application

When the end-user successfully completes the authentication process on the web-form, he is redirected back to the client's application.

Code Block
GET https://customer.io HTTP/1.1

...

Step #7
Get the web-form status with the actual API response.

Mandatory request fields

id
- identifer of the web form given on step #2

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.

...

Code Block

language	json

GET /api/v1/webForms/3 HTTP/1.1
Accept: application/json
Authorization: Bearer <user's access token>

...

Step #8
Receive a web-form resource.

Explanation

The response includes the actual service response code/body.

...

Code Block

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

Info

When applicable?

If a bank interface has DECOUPLED_APPROACH property.

...

Step

...

HTTP(S) message

...

Step #1
Import a new bank connection

Mandatory request fields

bankId
interface

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.

...

Code Block

language	json

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

HTTP status code is 451
Field errors.code has WEB_FORM_REQUIRED value.

Mandatory response fields:

Location header with the web-form link.
message contains an indentifier of the web form

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.

...

Code Block

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
Redirect the end-user to the web-form

Optional parameters:

redirectUrl - an URL where the end-user will be redirected to when the process is completed (find more details in the web form’s documentation)
callbackUrl - an URL which will be triggered once the import process is completed (find more details in the web form’s documentation)

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

Code Block

GET https://finapi.host.io/webForm/xihSWhdao5iVttO_zIUsfZ_adzt4fRlyr7lNfEuPLTy4obC5a6R3oAPK4p5yYE6FX4mniQVW3IOe0bmAcdekpLP6eJkrrWv0J6TlU3aUuzLTyFiy8nZ2MRx9KP8K0Lni?redirectUrl=https://customer.io HTTP/1.1

...

Step #4
Redirect back to the client’s application

When the end-user successfully completes the authentication process on the web-form, he is redirected back to the client's application.

Code Block
GET https://customer.io HTTP/1.1

...

Step #5
Get the web-form status with the actual API response.

Mandatory request fields

id
- identifer of the web form given on step #2

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.

...

Code Block

language	json

GET /api/v1/webForms/3 HTTP/1.1
Accept: application/json
Authorization: Bearer <user's access token>

...

Step #6
Receive a web-form resource.

Explanation

The response includes the actual service response code/body.

...

Note

This page 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.

Versions Compared

Old Version 9

New Version Current

Key

For licensed mandators (no web form)

Embedded approach

Redirect approach

Decoupled approach

Possible combinations of approaches

Redirect + decoupled + decoupled (ErsteGroup/Sparkasse AT banks)

For unlicensed mandators (web form)

Embedded approach

Redirect approach

Decoupled approach

Page Comparison

Versions Compared

Old Version 9

New Version Current

Key

For licensed mandators (no web form)

Embedded approach

Redirect approach

Decoupled approach

Possible combinations of approaches

Redirect + decoupled + decoupled (ErsteGroup/Sparkasse AT banks)

For unlicensed mandators (web form)

Embedded approach

Redirect approach

Decoupled approach