Getting Started - KreditCheckFDE API Integration

Introduction

In addition to the normal data analysis, KreditCheck FDE contains further rules that make it possible to carry out a simple evaluation using a traffic light model.
Extended documents can also be downloaded for documentation purposes.

Please read the documentation about the flow for KreditCheck.

Prerequisites

• The major prerequisite is to have a valid set of client credentials: client_id and client_secret.

• User Management with Process Controller: Obtain Authorization via Process Controller

Used Endpoints

To use the KreditCheck Flow, at least the following endpoints are required:

cURL Example

Translated into cURL it looks like the following:

Step 1 - Import Data from Bank

After the creation of a Process Token and the exchange to an access token, we can start with the Bank import:

curl --location "https://di-processctl-finapi-general-sandbox.finapi.io/api/v1/dataImports/<processToken>" \
 --header 'Content-Type: application/json' \
 --header 'Authorization: Bearer <access_token>' \
 --data '{
   "search":"finAPI demo bank",
   "iban":"DE77533700080111111100",
   "loadOwnerData":false,
   "maxDaysForDownload":200,
   "webFormProfile":"default",
   "accountTypes":["CHECKING"],
   "callbackUrl":"https://domain.tld/callback/dataImport"
}'

The response looks like this:

{
  "webFormId": "f6381acb-d670-4467-8f50-6df32adbeb81",
  "webFormUrl": "https://webform-sandbox.finapi.io/wf/f6381acb-d670-4467-8f50-6df32adbeb81",
  "importId": "1916ec9e-13e0-4000-88fe-8a57ade79280"
}

This response now provides a WebForm URL, which must be displayed to the customer in a WebView. The customer can use it to log in to the bank and synchronize their accounts.

After the user has logged in and the data has been retrieved from the bank, finAPI calls the callbackUrl as a POST request.
A request similar to this one is sent for this purpose:

{
  "processToken": "<processToken>",
  "importId": "1916ec9e-13e0-4000-88fe-8a57ade79280",
  "result": {
    "status": "SUCCESSFUL",
    "accounts": [
      {
        "bank": "Test Bank",
        "iban": "DE77533700080111111100",
        "accountId": "123456",
        "accountHolder": "Max Musterman",
        "accountNumber": "1111111",
        "accountName": [
          "Girokonto",
          "VISA Kreditkarte"
        ],
        "accountCurrency": "EUR",
        "accountType": "CHECKING"
      }
    ]
  }
}

Step 2 - Finalize the Bank Import

To complete the import, the system must be informed that all accounts are ready.

This step does not allow any further imports of bank accounts and must always be carried out after importing all accounts from all Banks.
If only one account is imported, this endpoint is called up after this import.
This is done by the “finalize” endpoint:

Größe des Code-Auszugs ändern

curl --location --request POST 'https://di-processctl-finapi-general-sandbox.finapi.io/api/v1/dataImports/<processToken>/finalize' \
 --header 'Content-Type: application/json' \
 --header 'Authorization: Bearer <access_token>'

If the result is 204 (No Content), this call was successful.

After the import has been finalized, no additional accounts can be added to this process.

Step 3 - Create KreditCheck FDE

After the bank import has been completed, the KreditCheck FDE assessment can be started.

KreditCheck FDE

curl --location --request POST \
'https://di-solutions-finapi-general-sandbox.finapi.io/api/v1/fde/b2c/<processToken>/accountAssessment' \ 
--header 'Content-Type: application/json' \ 
--header 'Authorization: Bearer <access_token>' \ 
--data '{ 
  "callbackUrl": "https://domain.tld/callback/fde", 
  "callbackHandle": "<callbackHandle>", 
  "clientReference": "<clientReference>"
  }'

The request starts the Financial Decision Engine account assessment.

A successful response contains the unique fdeId of the assessment

{ "fdeId": "<fdeId>", 
  "status": "CREATED"
}

The fdeId is required for retrieving the assessment result and downloading the corresponding PDF.

Step 4 - Get KreditCheck FDE Result

The current status and result of the assessment can be retrieved using the fdeId.

curl --location 'https://di-processctl-finapi-general-sandbox.finapi.io/api/v1/checks/<processToken>/kreditcheck/<kreditCheckId>/analysis/dacForLoan/zip' \
--header 'Accept: application/zip' \
--header 'Authorization: Bearer <access_token>'

Once processing has been completed successfully, the response contains the result of the KreditCheck FDE assessment.

{ 
  "fdeId": "<fdeId>",
  "status": "SUCCESSFUL",
  "clientReference": "<clientReference>"
}

The FDE processes the imported account data asynchronously. The result should therefore only be retrieved after the assessment has been completed. If a callbackUrl was provided when creating the assessment, the callback can be used to determine when processing has finished.

Step 5 - Download KreditCheck FDE PDF

After the assessment has been completed successfully, the KreditCheck FDE result can also be downloaded as a PDF document.

curl --location \ 
 'https://di-solutions-finapi-general-sandbox.finapi.io/api/v1/fde/b2c/<processToken>/kreditcheck/<fdeId>/pdf' \ 
 --header 'Accept: application/pdf' \ 
 --header 'Authorization: Bearer <access_token>'

The response contains the KreditCheck FDE PDF as binary data.

Process Overview

The complete KreditCheck FDE API flow consists of the following steps:

1. Create a Process Token and obtain an Access Token.

2. Import the customer's bank account data.

3. Finalize the bank data import.

4. Start the KreditCheck FDE account assessment.

5. Wait until the assessment has been completed.

6. Retrieve the KreditCheck FDE result.

7. Download the KreditCheck FDE PDF if required.

For detailed request and response models, available parameters and error responses, see the Financial Decision Engine section of the finAPI API Documentation.