For the setup of UAT and Production environments, you can refer to the common page: Start guide for developers

Clients have two main options to simulate different banking scenarios:

• Real Banks: Clients can use their own real bank accounts to test a specific bank. This method enables testing the actual authentication process of the bank. However, it may not cover all testing needs, such as evaluating multiple scenarios or varying KPIs.
• Sandbox Banks:
  • Sandboxes provided by real banks: These sandboxes are maintained by the banks themselves. While they allow some level of testing, they often face limitations such as frequent maintenance, incomplete account information and inconsistent replication of real authentication processes.
  • NEOS Fake Bank Solution (BankEmu): NEOS offers its own sandbox solution, called BankEmu, which we highly recommend. This solution is designed to address the limitations of other sandboxes and provide a reliable and user-friendly testing environment.

Why Choose the NEOS BankEmu Solution?

NEOS developed BankEmu to overcome key challenges, including:

• Enabling realistic testing without the need for a real bank account.
• Providing a robust and reliable solution for testing multiple scenarios efficiently.

With BankEmu, Client can:

• Simulate common Strong Customer Authentication scenarios, including both redirect and embedded flows.
• Access test environments enriched with detailed, up-to-date bank account information that closely mimics real financial situations.

How to connect BankEmu banks

To test BankEmu banks it will be necessary to provide the “XF” countryCodes as a parameter in the POST /widget/connect method:

    { 
        … 
        "subjectId": 817306,
        "countryCodes": [“XF”],
        … 
    }

Currently, there are 7 mock banks available with transactions in English, allowing the Client to test different scenarios. In the future, this number might vary, increasing the number mock banks available expanding the range of test cases.

The following banks are designed to allow the Client to simulate a realistic strong customer authentication process:

• NEOS - EN - Redirect Scenario: this mock bank simulates a redirect bank, redirecting the user to a page that emulates a real strong customer authentication process that occurs on the bank site. Clients must enter a username and password to log in.
• NEOS - EN - Embedded Scenario: this mock bank replicates a real embedded banking experience. Users interact with a widget page where they must provide a username and password to log in.

The banks listed below are designed to replicate different test scenarios, enabling the Client to verify how the solution's KPIs vary depending on the scenario:

• NEOS - EN - Business Low Risk: this mock bank represents the account of a business user with low credit risk, mirroring typical account behavior and financial status.
• NEOS - EN - Business High Risk: this mock bank emulates the account of a business user with high credit risk, reflecting associated financial patterns and constraints.
• NEOS - EN - Consumer Low Risk: this mock bank replicates the account of a consumer with low credit risk, demonstrating stable financial activity.
• NEOS - EN - Consumer Multi-Account: this mock bank simulates the account of a consumer managing multiple accounts, showcasing complex financial interactions.
• NEOS - EN - Consumer High Risk: this mock bank mimics the account of a consumer with high credit risk, illustrating financial challenges and associated behaviors.

The Client has to set the returnTo field, in the POST /widget/connect, with its own web page. The returnTo URL is the landing page at the end of the widget flow, for example https://www.client.com/landing_page .
The Client can enrich this url with its own query parameters, for example https://www.client.com/landing_page?myOwnId=7.
The Client should rely on this redirect event on its own web page (returnTo) to understand when the widget is completed.

The Client can use the returnConnectionId, in the POST /widget/connect, to identify the connectionIds created by the widget and their status.

The returnConnectionId is a boolean, with value:

• false: (default value)
• true: append query parameter connectionId to returnTo URL. Multiple connectionIds are supported. The value is composed by the id of the connection and the status of the SCA, in the following format id,(ok|fail|new). Example of the final URL is: https://www.client.com/landing_page?connectionId=354,ok&connectionId=355,fail

The Client should exploit the query parameters to show to the subject a happy/unhappy page depending on the SCA status.

The Client can also use the returnWidgetIdError, in the POST /widget/connect, to identify the widget's status in case of error. The returnWidgetIdError is a boolean, with value:

• false: (default value)
• true: append query parameter widgetId to returnTo URL. The value is composed by the id of the widget and its status, in the following format: widgetId,(notFound|expired|tooManyOpenings). Example of the final URL is: https://www.client.com/landing_page?widgetId=1234456,tooManyOpenings

The status of the widget errors means:

• notFound when the widget doesn't exist, in this case the widgetId is set to 0. The final URL will be https://www.client.com/landing_page?widgetId=0,notFound.
• tooManyOpenings when the subject has opened the widget more than the maximum specified number of times.
• expired when the subject has opened the widget after the expiredAt.

The Client should exploit the query parameters to manage correctly the user experience flow, i.e.: in case of expired the client should contact again the subject to create a new URL.

Please take into consideration the Subject can close the main window of the browser while navigating the widget. In these cases the redirect to the returnTo URL won't happen, and you will miss the widget completion event.

The consentStatus defines the status of the SCA of a connection.

The consentStatus can have 3 different values:

• new: when the SCA process is not completed. Therefore the Subject interrupts the SCA before the process was completed. In this scenario the connections can be ignored or, if needed, they can be recovered.
  In case of "NEOS with Widget" the Client can call the POST /widget/reconnect to start another SCA process on the same connection. Otherwise the Client can delete the current connection with DELETE /connections/{id} and create again a new connection using POST /widget/connect.
• ok: when the SCA process is completed with success or there is no evidence of errors.
  In the moment the SCA becomes ok:
  • NEOS starts data fetching from the provider.
  • the consentValidUntil is filled with the proper date depending on one time/recurring.
• fail: when the SCA is completed without success because of a non-recoverable error. The Client can proceed with the same step described in the "new" scenario.

This value is available in:

• GET /connections/{connectionId}/consents as status
• GET /connections and GET /connections/{connectionId} as lastConsentStatus
• the returnTo url as a query parameter (when the returnConnectionId = true).

Data availability is strictly related to the validity of the consent. Therefore only in case the SCA process ended with success (consentStatus = ok) a Client must expect the data to be fetched.

The "data fetch" is the NEOS procedure that retrieves data from the providers and store them in the database. The fetching data process is asynchronous, it means that NEOS retrieves data from the providers in the background. Then NEOS can communicate the end of the data fetch sending callbacks (push notifications) to the Client or the Client has to poll the connections status for understanding when data fetch is completed.

It is strictly recommended to not call methods for retrieving data or KPIs before a successful fetch. Please consider that this process could last just few seconds or minutes depending on the amount of data.

Callbacks are recommended because promptly inform the Client, without any delay, but the Client must publish two REST endpoints.
During the onboarding process the Client must provide two URLs (one for success and one for failure scenario) which NEOS use to notify about the end of fetching process.

NEOS sends a successful or failure callback to predefined Client URLs in case the data fetch end with success or failure.

The callback always contains:

• the connectionId
• the callbackFields

The callbackFields can help the Client identifying to whom the incoming callback refers. For example the Client can send in callbackFields its own subject identificators for which they are calling the POST /widget/connect, this help to know for which Subject they are receiving the callback.

The callbackFields can be filled with a maximum of 10 key-value pairs.
This value can be defined in input in each method that trigger a callbacks:

• POST /widget/connect and POST /widget/reconnect, if you choose the integration with the widget. E.g.:

    { 
        ...
        
        "subjectId": 817306,
        "callbackFields": { 
            "clientInternalId": "FILE-123",
            "clientSessionToken": "324-234",
            "otherUsefulData": "ExampleValue"
        }, 
        
        ... 
        
    }

• POST /connections/{connectionId}/refetch
• POST /connections, if you choose the integration without the widget

The callbackFields are returned in the output body of callbacks, e.g.:

    { 
        "connectionId": 786,
        "callbackFields": { 
            "clientInternalId ": " FILE-123",
            "clientSessionToken": "324-234", 
            "otherUsefulData": "ExampleValue" 
        }
    }
    

For further details and technical specifications refer to the POST /connections/{connectionId}/refetch method in "API reference".

The Client can use the following way to secure callback endpoints:

• Without any authentication
• Through Mutual TLS authentication that ensures traffic is both secure and trusted in both directions between the Client and Neos
• Through client credentials (oauth2) authentication
• Using IP filtering on the source address of the callback
• The URLs for the callbacks can be enriched with query parameters. They can be configured with a static secret/password recognized by the Client's endpoints. For example Client can define in NEOS a URL like this https://www.myhostname.com/neos-callback-endpoint?secret=12345678 the server exposing this endpoint allow connections only when the secret is correct

These points can be used as an alternative or together to strengthen the security.

Polling

In case the callbacks are not enabled, the Client can call (or poll) the method GET /connections/{connectionId} to check if there are new data available for the input connection.

The conditions that have to be verified are:

• the subject has completed the SCA procedure correctly and without error and therefore
• the consent status is ok the consent has not yet expired, i.e. it is still valid
• the most recent data download from the provider is today's
• if the most recent data download is also a successful one then the data fetch from the provider is finished with success. Otherwise the fetch from provider is failed.

It is suggested to implement the polling as fallback method also when the callbacks are enabled. The polling can be performed when a callback is expected but not received after a proper timeout.

Whether you have implemented callback or polling methods in order to understand data availability, there is the possibility that the fetch process ended with error.

In this case the problem is highlighted in two ways:

• with a failure callback
• checking the GET /connections​/{connectionId} the lastFetchAt is available but is not available the lastSuccessfulFetchAt

The reasons could be different and could be verified checking GET​/connections​/{connectionId}​/fetches. Some errors can be recovered, refer to point: "When a connection needs a reconnect"

The lastTransactionId is the identifier of a transaction related to the requested accountId. Using this parameter in input the method GET /transactions returns only the transactions that are newer than this one. This parameter can help the Client in downloading each time only new transactions for a specific account. It is not mandatory, so in the first time that the Client calls this method it is not required to fill it. From the second time on, if the Client wants to download only new transactions, it fills the lastTransactionId with the last transactionId received. In this way, it will receive in output only the transactions that are newer than this one.

This value is available in:

• GET /transactions: as input parameterData

There are some fields that help Client in understanding when a connection could be recovered with a reconnect.

• flagErrorRecoverable
• consentValidUntil
• consentStatus

For more details on how to determine the consent status of connections, refer to the point: "How to know connections consent status?".

flagErrorRecoverable

The flagErrorRecoverable defines when a connection for which the fetch ended with error it is probably recoverable with a reconnect process. Therefore we suggest to ask to the Subject for a reconnect.

The flagErrorRecoverable is a boolean, with value:

• true if the fetch of a connection ends with error due to a consent problem (e.g. consent expired, consent in status new or fail)
• false if the fetch ends with error for problems not related to the consent (e.g. a temporary problem on provider side). Probably a refetch is a first option or a deletion followed by a new connection is another option. If the error persists, get in touch with NEOS team

This value is available in:

• GET /connections/{connectionId}/fetches
• in the body of failure callback

consentValidUntil

The consentValidUntil defines expiration date of the consent for a specific connection. This value is filled only in case the consentStatus = ok. In case the consentStatus = ok but the consentValidUntil is in the past, means that the consent is expired and in order to continue downloading data a reconnect is needed.

This value is available in:

• GET /connections and GET /connections/{connectionId}: as expiration date of the most recent consent of a connection
• GET /connections/{connectionId}/consent: as expiration date of a specific consent for the requested connectionId

Having data available in NEOS is related to these steps of pre-conditions that must be satisfied.
In case there are no data available the Client has to verify all the following points:

1. In case the widget has been used, whether the subject opened it before the expiration date You can check the GET /widget/statistics for the specific subjectId to get all the detail of the widget navigation. If the widget has not been opened or is opened but closed before the end of the SCA process, you can contact the Subject to find out why.
2. The subject correctly connected a provider, i.e. consentStatus=ok. You can check the Consent Status to verify the connections done by the subject and their status. Refer to point "How to know connections consent status?" for more details.
3. The fetch ended without any error. You can check data availability, monitoring callbacks or, in case you do not have activated them, you can check the GET /connections/{connectionId}/fetches output. Refer to point "When data are available in NEOS?" for more information.

In case you are a Client with a recurring access data are automatically refreshed every day.

Data are correctly refreshed only in case:

• Consent is still valid, so checking in GET /connections/{connectionId}/consents, fields: status = ok and consentValidUntil < today

if the above condition is not satisfied connections cannot be refreshed and a reconnect is probably needed. Refer to the point "When a connection needs a reconnect?" for more information.

The methods GET /subjects/{subjectId}/analytics and GET /subjects/{subjectId}/reports could return a response http 202 status code with an outputUri in the response body.

This option allows to manage responses also in asynchronous mode, obtaining the result without exceeding timeout or transactional limits.

In order to manage the 202 response and retrieve the result you need to download the file within the expiredAt date by integrating the Storage API and calling the method GET on the URL returned in the response body, so GET /outputUri.

The NEOS 2.0 Score Model has a wide range of applications and different actors, from banks to alternative lenders, lending platforms, insurances and companies can benefit from it.

Below the main areas of usage transactional data and Neos Score:

• Scoring System:The model can work as a standalone credit scoring solution, but it reaches its best performances when integrated with a complementary scoring model based on Credit Bureau data and Internal data. The resulting score can prove to be of remarkable importance for financial institutions and their decision-making processes. This is true for the following major reasons:
  • Information available in Credit Bureau on liabilities is perfectly complemented by the asset side provided by Open Banking data. Score Neos model evaluations are orthogonal to current sources of data, helping remove the typical asymmetry of lending information.
  • Material improvement in sample coverage, with an increase in Hit rate to 100%.
• Monitoring System: Current Account data is fundamental with Credit Bureau data when faced with managing credit risk of different portfolios. As such, this model can be a tool to help risk managers allocate resources more effectively at the right moment. Neos Score is not a point in time evaluation, but rather an ongoing score updating itself with every new transaction available in current accounts. This always updated picture allows to alert lenders when risk profiles change, eventually triggering repricing of financial products.
• Credit Score: As a measure of credit risk, the output of the model is to be interpreted as a proxy for an applicant’s robustness and resilience. Lenders can truly improve applicant’s lives stability by allowing them to have easier and more transparent relationships with external actors minimising uncertainty and informational asymmetries.

The NEOS 2.0 Score is a predictive indicator. It belongs to a new generation of CRIF Scores based on current account information and on the CRIF proprietary A.I. Categorization Engine of banking transactions contained therein.

What does the NEOS 2.0 Score predict/estimate?

Transactional data are fundamental to analyzing financial health in short and medium term: in fact, benefits of using transactional data in predicting defaults have been widely acknowledged.

The NEOS 2.0 Score enables a credit risk estimate through the aggregation of the information contained in all the current accounts available to the subject. Thanks to the careful selection of behavioral bank account factors but also due to the high frequency of the input data, the NEOS 2.0 Score promptly captures changes in a subject’s creditworthiness.

The NEOS 2.0 Score is computed at counterparty level and predicts the probability that it will default in repaying its obligation during the following 12 months.

Is there a unique model available of the NEOS 2.0 Score?

There are dedicated models segmented by subject type.

In order to maximize available current accounts information and the peculiar payment and earning behaviors, 2 dedicated models were developed, one for Individual/Consumer/Sole Traders and one for Legal entities/Business.

Does the NEOS Score 2.0 also work without Credit Line/Overdraft data?

The NEOS Score 2.0 introduces an evaluation of any account overdrafts available on the current accounts.

The NEOS Score 2.0 can be calculated even without the Credit line/Overdraft information and manages to maintain satisfactory risk discriminating capabilities.

As always, the completeness of information is a requirement to improve the creditworthiness assessment, for Consumers and, above all, for Businesses subjects.

Does the NEOS Score 2.0 also work without categorization and if so what are the differences?

The NEOS 2.0 Score is entirely based on current account data, leveraging both on more “traditional” features (e.g. cash flow information,...) as well on features build on categorised transactional data:

• 55% of Consumer model’s features are based on categorised transactional data,
• for the Business model the rate of features based on categorised transactional data is about 40%.

The NEOS Score 2.0 can be calculated even without such features based on categorized transactions and it manages to maintain quite satisfactory risk discriminating capabilities.

Obviously the "complete" model (which also weighs the information deriving from categorized data) is more performing: simulations on the development sample have proven that features based on categorised transaction can improve the model accuracy by 7.5% on Consumer segment and 10.5% on Business segment.

If with all suggestions above you are still in trouble in integrating with NEOS or you are facing some issue, please get in contact with NEOS team to find out how to resolve issues.
When reporting an issue remember to share with NEOS team as much information you have:

• the environment in which the problem occurs
• at least the requestId or groupId (refer to the next section) of the request that gives problem or, if the problem is not related to a method, the subjectId or connectionId

As a guideline remember that NEOS data and KPIs are strictly related to providers data availability. Therefore if you are facing issue for specific missing data (e.g. transactions description, account owner) it is possible that the provider itself is not sending this value to NEOS.

The requestId and groupId must be filled by the NEOS Client. The purpose of these two fields is to easily track the data traffic between the Client and NEOS.

The requestId: is a unique identifier of the call. Each call has a different requestId and it is defined by the client as a UUID (e.g. 004c5fae-83fe-4d4f-946a-bb4482dc92db)
This value is mandatory for each call.

The groupId: is a unique identifier of a group of calls. Each group of calls has a different groupId, but each call inside a group of call has the same groupId. The definition of the "group" is Client specific because it depends on the flow defined by the Client. For example a group of calls could be the quick start "NEOS w/ Widget".
In this way the calls belonging to the same "customer journey" have the same groupId value. This value is not mandatory but it is strongly suggested to be used.

Write to neos_core_team@crif.com.

In case of issues, changes on configuration, analysis on data, etc, please open us a ticket.