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
• 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.

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.