Integration Hints

GiroIdent integrates multiple SCHUFA services. SCHUFA traditionally provides information, rather than decisions.

An application which integrates GiroIdent will have to implement a decision logic based on the specific customer use case and their risk appetite. The following sections provide best practice proposals on how to implement the decision logic.

What is a Successful Check?

Input values (example) and possible results for the positive and negative verdict(s).

GiroIdent Basis

Recommendation for a check to be considered as successful:

• status = COMPLETED

• name-equality = true

GiroIdent Plus

Recommendation for a check to be considered as successful:

• status = COMPLETED

• name-equality = true

• schufa-identity-check != 0.0

GiroIdent GwG

Recommendation for a check to be considered as successful:

• status = COMPLETED

• name-equality = true

• gi-iban-verification-score = true

and either

• schufa-bank-account-check-plus-iban-p = p01

• schufa-bank-account-check-plus-iban-s = s01

or

• schufa-identity-check != 0

• schufa-proven-identity = true

When to give the User the Option to Retry the Check

Humans are prone to errors; the user may enter faulty data during the identity check process, like

• misspelt names, addresses, ZIP codes,

• wrong banking credentials,

• invalid second-factor code,

• use a login to a bank, where he has no checking account.

As a consequence, either the bank login may fail, or one of the SCHUFA services may return a result, that is not acceptable.

Failures in the bank login process are indicated to the user by the finAPI web form, potential issues have a wide variety, thus GiroIdent does not return error codes, but only an error string for debugging purposes - not intended to be shown to the user, as he is informed via web form GUI.

After successful login, the name validation will be performed, additionally, the result of the SCHUFA services is gathered. GiroIdent does not disclose personal information, therefore details or hints related to which information is not accepted will not be provided on the API / to the user.

We recommend for your application allow the user (at least) one more attempt. It should the user’s choice to retry, as he received human-readable information either on the finAPI web form or on his bank's login page in case of a redirect. There are no reasonably suitable or meaningful criteria to conditionally allow such an attempt.

Understanding Error Messages

As mentioned above, the error message returned by the GiroIdent API is only debugging information, no application logic shall be implemented based on it, and it shall not be printed on the UI.

Some typical error messages are:

• if the user has not finished the web form, the message may contain error codes like INTERRUPTED, EXPIRED, or ABORTED,

• if the user has entered the wrong credentials or a wrong TAN, the code BANK_SERVER_REJECTION,

• other errors (and codes) are technical errors, related due to the wrong configuration (typically during integration) or temporary issues of a web service at finAPI, SCHUFA or the bank side.

Validation

In general, validation constraints are defined in the GiroIdent API specification.

Additional Validation of Input Parameter for GiroIdent Plus and GWG Variants

Plus and GWG variants integrate web services provided by the SCHUFA. These APIs have strict constraints for input parameters for user name and address.

Allowed characters for the SCHUFA web services:

• A-Z a-z

• ß

• äöü ÄÖÜ

• 0-9

• /:(),'.-

finAPI APIs implements special character mappings and filters non-compliant characters to improve the robustness of the software; nevertheless, it is the customer’s responsibility to validate the details provided by the user (e.g. in a GUI), to achieve the best possible user experience.

Further constraints:

For validation-related details please refer to the official SCHUFA API documentation. The following details are provided for reference only, finAPI does not guarantee completeness or up-to-dateness.

In case you require more information regarding the SCHUFA validation errors, support is available directly from Schufa at: vp-anbindung@schufa.de.

Reference Documents (to be received together with the SCHUFA contracts):

• SCHUFA Verfahrenshandbuch Online

• SCHUFA Mapping Special Characters

Timeouts and Retries for API Calls

Recommended timeout for API calls is 10 seconds (both POST and GET).

API GET Calls

GET calls are waiting/blocking for a final check status at a maximum of 5 seconds. If a final status is not available within this time, a status IN_PROGRESS will be returned as part of the response object.

The calling party shall retry the GET call in this case.

For GET calls, the recommended number of at least 3 retries.