europace/kex-market-engine-api

API zur Anbindung von Produktanbietern im Ratenkreditgeschäft.

KEX Market Engine API

⚠️ You'll find German domain-specific terms in the documentation, for translations and further explanations please refer to our glossary

This API enables product provider within consumer loans to connect their loan offering to the Europace platform via services with standardized interfaces.

⚠️ This API is continuously developed. Therefore we expect all users to align with the "Tolerant Reader Pattern", which requires clients to be tolerant towards compatible API changes when reading and processing the data. This means:

1. unknown properties must not result in errors

2. Strings with a restricted set of values (Enums) must support new unknown values

3. sensible usage of HTTP status codes, even if they are not explicitly documented

API version

The version of the API is based on Semantic Versioning and has the format

MAJOR.MINOR.PATCH

and is part of the Swagger Definition (info.version).

1. The MAJOR version is incremented in case of API incompatible changes (e.g. new mandatory data)
2. The MINOR version is incremented for backward compatible API changes (e.g. new optional specifications)
3. The PATCH version is incremented if the API remains the same, but the Swagger definition is adapted (e.g. extension or adaptation of descriptions in the API)

You will find the current version of the API within the Releases.

API specification

Requests and responses are defined in the Swagger Definition.

Acceptance

In a KreditSmart case, offers are first calculated by Europace. In the process, the general feasibility is pre-checked, adjustments to the request are made if necessary, 2/3 - conditions are calculated and the completeness of the case is ensured.

If all the necessary data is available and the preliminary check was successful, the case can be accepted via the KEX Market Engine API. In this process, the customer's request, i.e. the provided data of the Finanzierungswunsch, as well as the applicant data are transmitted to the product provider.

The product provider should then, in turn, carry out all steps necessary for accepting the offer:

Adaptation of the customer's request

• If it is not possible to issue an offer on the desired financing criteria, an adjustment should be made to generate a feasible offer
• The following specifications can be adjusted
  • Duration specification
  • Monthly payment specification
  • Loan amount specification
  • Insurance combinations
  • Commission
• An adjustment message must be generated for each adjustment to inform the agent of the adjustment.
• See fields status.angepasst and meldungen

Credit assessment of the applicant

• Including an overview of the accounted income and expenses and the calculated surplus/shortfall
• See field bonitaetscheck

Calculation of final conditions

• Including repayment plan
• See fields kredit and tilgungsplan

Vote on the feasibility of the application

• Including consideration of the scores of external providers e.g. Schufa
• In case of rejection, generating a message with the reason for rejection
• See fields status and meldungen

Identification of documents to be submitted

• See field unterlagen

Creation of the contract documents

• See field dokumente

Providing links for the digital identification of the Antragsteller

• Video legitimation
• QES
• See field identifikation

Integration of the KEX Market Engine API in Europace

The KEX Market Engine API will be implemented by the product provider. With support of the KEX Market Engine service Europace can integrate the products of the product provider via API into KreditSmart.

API reference

The implemented interface accepts data with content-type application/json.

Request

Services that implement the API expect a POST request with a JSON document as request body.

During the offer calculation, it is already ensured that the application data is complete. Nevertheless, the service must be able to deal with missing data. This should not lead to a technical error.

Response

The response will be expected as JSON within the response body.

Generally - no matter if the offer is MACHBAR or NICHT_MACHBAR - a response with a complete offer and HTTP status code 200 SUCCESS is expected. If the offer is MACHBAR, at least one document is expected. In case of a technical error a response with HTTP status code 500 is expected. The response does not need to contain an offer, but should give an indication of the cause of the error as supportMeldung.

Handling incomplete requests

A complete offer without document(s) is expected. The feasibility status is NICHT_MACHBAR. Completeness messages, that point out the missing data, must be available.

If conditions of an offer are not available due to missing/incomplete response of the backend-system, the field kredit could be left empty (null). The offer will be automatically marked as NICHT_MACHBAR.

Handling shortfall in the Haushaltsrechnung

If the application is not feasible due to a shortfall in the Haushaltsrechnung, ideally the duration will be extended. If this is not possible, a downselling of the loan amount can take place.

If a downselling results in a feasible offer, this is marked as "angepasst": true and contains appropriate adjustment messages to inform the agent of the adjustment.

If a downselling is not possible, an offer without document(s) with the status NICHT_MACHBAR and at least one corresponding feasibility message is expected. Duration and loan amount should in this case correspond to the original request.

Messages

Messages are generated to provide guidance to the agent about the execution and feasibility of the application. The following categories are distinguished.

Message category	Description	machbarkeitsstatus	angepasst
MACHBARKEIT	The application will be rejected.	NICHT_MACHBAR	no influence
VOLLSTAENDIGKEIT	The application is incomplete and must be completed with missing data.	NICHT_MACHBAR	no influence
HINWEIS	Note to the agent.	no influence	no influence
ANPASSUNG	Information about adjustments of the customer's request, e.g. monthly payment, loan amount oder insurance.	MACHBAR	true

Status

Feasibility status	Description
MACHBAR	The application is accepted.
MACHBAR_UNTER_VORBEHALT_PRODUKTANBIETER	The application could not be examined conclusively. Product provider and agent need to renegotiate.
NICHT_MACHBAR	The application is rejected.

Account statements in requests

The API offers the possibility to provide an applicant's account statements. These are included only if the chosen product is an instant loan, meaning that a definitive decision whether to accept or reject the loan application is made instantly without human interaction. Also, the applicant has to permit the use of her or his data via a separate process.

Authentication

The method of authentication has to be coordinated between the Produktanbieter and Europace.

Performance

We expect the Annahme-response on average within 30s. If the response time is significantly higher, the functionality of our platform deteriorates for other partners, e.g. agents.

Example

• Successful Accepting
• Accepting with missing data
• Accepting with shortfall
• Accepting with downselling
• Accepting with account statements
• Accepting with technical error

Terms of use

The APIs are made available under the following Terms of Use.