GiroIdent 2.0 Service

GiroIdent is designed to rely on the finAPI OAuth 2.0 Standard for authorizing applications and users. The GiroIdent services can only be used with a valid Access user token. To learn more about authentication and obtaining such a token please refer to the the “Getting Started (pre-requisites)” section in this documentation.

GiroIdent is implemented as an asynchronous service, it is mandatory for the customer application to wait for the final result of the check, before deleting the user (-identity).

Introduction

The GiroIdent Service is based on a set of Checks. As a partner application, the recommended integration of these checks is as follows:

Partner application calls GiroIdent service Create Check with the relevant parameters. GiroIdent returns a GiroIdent Redirect URL.
Partner application sends (redirects) the user to “Web Form Redirect URL".
The user follows GiroIdent UI and grants GiroIdent access to her bank account.
The GiroIdent UI will optionally redirect the user to a result URL if configured by the partner application (via query parameters appended to the Redirect URL).
The partner application checks the GiroIdent result using the Get Check service and displays the result.

Variants and Features

	Basis	Plus	GwG (§14)	GwG Total (§12)
Successful bank account login by the user	x	x	x	x
Matching user name with account holder name(s)	x	x	x	x
SCHUFA Identity Check: matching user name, address, birthday with persons know to SCHUFA		x	x	x
SCHUFA proven Identity (2): user details match a person known to SCHUFA with verified identity.			x (1)	x (1)
IBAN verification: user IBAN matches the account the user logged in.			x	x
SCHUFA Account Check: User details and IBAN are matching account details known to SCHUFA.			x (1)	x (1)
Successful micro-payment from the user account				x

(1): SCHUFA Account check results are provided by default, the SCHUFA proven-identity_evaluation is only provided if the Account Check was not successful.

(2): GiroIdent Plus uses SCHUFA Identity Check variant “Standard”, and does not return “proven identity” information; GwG and GwG Total use the variant “Premium”, which includes “proven identity”.

Using Callbacks or Polling for Result Reception

The KYC process in GiroIdent is executed asynchronously after creating a new check.

The result of the check can be retrieved in two different ways:

by implementing polling to the “GET" endpoint of the selected KYC flow,
or by registering a callback-URL added to the parameters of the “POST" call that creates the check. All POST endpoints optionally allow to set a callback URL and a handle, that will be included in the callback.

Managing Authentication: User vs. Process

As described in chapterGetting started - Authorization and Creation of a User Identity, an authorization token (as the pre-requisite to access the GiroIdent API) can be obtained either by starting a process (with the finAPI Process Controller - recommended for KYC stand-alone use cases) or by creating a user (identity) in finAPI Access (for use cases involving multiple of the finAPI web services).

Example Flows for Integrating GiroIdent

An integration of GiroIdent may combine user vs. process creation and polling vs. callbacks for the result in any possible way. Two variants are described in more detail in the sequence charts below.

Stand Alone Use Case, KYC Check Result via Callback

GiroIdent executes a callback with the final (successful or unsuccessful) result if a URL is provided in the API call to POST <GI_URL>/api/v2/checks.

Combined With Other finAPI Services, Polling for KYC Result

Errors in the finAPI web form front end executed in the user’s web browser may not necessary imply a failure in the bank login or a failed GiroIdent KYC check!

The client-application shall not bind it’s execution flow to the re-direct of the finAPI web-form front end (respectively the Javascript result callback events for the web-form web component).

The final KYC verdict shall be received from the GiroIdent API (or via a callback registered with the API) in any case (even for an error in the web from frontend execution), to ensure the best possible conversion rate for the KYC check.

In case of an error, that affected the KYC process, details are provided by the GiroIdent API!

GiroIdent Predefined Identity Check (KYC) Flows

GiroIdent Basis

Variants:

if the user has not provided an IBAN or BLZ on the API, he will be asked to select a bank in the web form.
If the user already created for using finAPI Access or DI, step 1 and 5 are not relevant. If additionally a bank import has been executed in the scope of Access, no redirect URL will be provided, and step 3 will be skipped.

Initiate a new GiroIdent Basis check

Validates the user identity based on the provided first- and last name, by performing the following steps:

First and last names are provided. Optionally IBAN, BLZ.
A user performs a bank login, after being redirected by the client application to the URL provided by GiroIdent. GiroIdent retrieves bank account details.
Using an advanced SCHUFA algorithm, GiroIdent calculates the similarity between the name provided and bank account information.

GiroIdent Basis check result

For the given check (-id), the status for the check process, and results for the user name validation are provided.

GiroIdent Plus

Initiate a new GiroIdent Plus check

Validates the user identity based on the provided user details by performing the following steps

First user details are provided. Optionally IBAN, BLZ.
A user performs bank login, after being redirected by the client application to the URL provided by GiroIdent. GiroIdent retrieves bank account details.
Using an advanced SCHUFA algorithm, GiroIdent calculates the similarity between the name provided and bank account information.
The SCHUFA Identity Check (Basic variant) validates the provided user details.

GiroIdent Plus check-result

For the given check (-id), status for the check process, and results for the user name and identity validation is provided.

GiroIdent GwG (§ 14 GwG - Vereinfachte Sorgfaltspflichten)

Initiate a new GiroIdent GwG check

Validates the user identity based on the provided user details incl. an IBAN by performing the following steps:

First user details are provided. Optionally IBAN, BLZ.
A user performs bank login, after being redirected by the client application to the URL provided by GiroIdent. GiroIdent retrieves bank account details.
Using an advanced SCHUFA algorithm, GiroIdent calculates the similarity between the name provided and bank account information.
The provided IBAN is validated against the received account information.
The SCHUFA Bank Account Check plus IBAN is used to validate the user input.
Only if the Account Check was not positive: The SCHUFA Identity Check (Plus variant) validates the provided user details.

GiroIdent GWG check result

For the given check (-id), status for the check process, and results for the user name and identity validation is provided.

GiroIdent GwG Total (§ 12 GwG), i.e. SCHUFA MyConnect

For more information on the SCHUFA MyConnect flow, please reach out to us via support@finapi.io or https://www.schufa.de/lp/myconnect/.