Refresh Event

What is a REFRESH Event?

The event REFRESH refers to notifications that are sent during the stages of the add account and update account processes triggered by users in the FastLink application.

Notifications will be sent while customers edit credentials, add, or refresh/update accounts for the latest information using FastLink. The refresh webhooks notification let customers know:

  • The provider site has requested MFA information to log in for aggregating data.
  • The Yodlee system has successfully logged in to the provider site.
  • The Yodlee system has successfully retrieved the account summary information from the provider site.

Note: Customers using FastLink 2.0 cannot subscribe to REFRESH notifications.

Types of REFRESH Event

There are two refresh-related events for which notifications will be sent to customers.

Interim Progress

The two interim progress events follow:

  • Login Success: This notifies customers that the login action has successfully completed in the provider site.
  • Account Summary: This notifies customers that the account summary information has been successfully retrieved from the provider site. This event is provider site-specific and will be provided to the customer as applicable.

Process Completed

This notifies customers that the process of adding or updating an account has completed.

Event Payload Information

The payload sent to the customer-provided URL has a common structure whereas the data attribute within the structure varies for every notification. The following JSON payload will be sent to the callback URL and the content type will be application/json:

{
   "event":{
      "info":"REFRESH.PROCESS_COMPLETED",
      "loginName":"fri21",
      "data":{
         "providerAccount":[
            {
               "id":10995860,
               "providerId":16441,
               "isManual":false,
               "createdDate":"2017-12-22T05:47:35Z",
               "aggregationSource":"USER",
               "status":"SUCCESS",
               "requestId":"NSyMGo+R4dktywIu3hBIkc3PgWA=",
               "dataset":[
                  {
                     "name":"BASIC_AGG_DATA",
                     "additionalStatus":"AVAILABLE_DATA_RETRIEVED",
                     "updateEligibility":"ALLOW_UPDATE",
                     "lastUpdated":"2017-12-22T05:48:16Z",
                     "lastUpdateAttempt":"2017-12-22T05:48:16Z"
                  }
               ]
            }
         ]
      }
   }
}
Event Attributes Name Details
info This attribute refers to the event name for which the customer is notified. The event info follows:
  • REFRESH.INTERIM_PROGRESS
  • REFRESH.PROCESS_COMPLETED
loginName The loginName of the user
data The data attribute is the payload the customer receives and is used by the developer to take relevant actions. The data attribute varies from event to event.
notificationId Unique identifier for the notification.
Events Event-Data Attribute Details

REFRESH.INTERIM_PROGRESS

Login Success Event Response

{
  "event": {
    "info": "REFRESH.INTERIM_PROGRESS",
    "loginName": "fri21",
    "data": {
      "providerAccount": [
        {
          "id": 10995860,
          "providerId": 16441,
          "isManual": false,
          "createdDate": "2017-12-22T05:47:35Z",
          "aggregationSource": "USER",
          "status": "IN_PROGRESS",
          "requestId": "NSyMGo+R4dktywIu3hBIkc3PgWA=",
          "dataset": [
            {
              "name": "BASIC_AGG_DATA",
              "additionalStatus": "DATA_RETRIEVAL_IN_PROGRESS",
              "updateEligibility": "DISALLOW_UPDATE"
            }
          ]
        }
      ]
    }
  }
} 

Account Summary Retrieved Event Response

{
	"event": {
		"info": "REFRESH.INTERIM_PROGRESS",
		"loginName": "fri21",
		"data": {
			"providerAccount": [{
				"id": 10995860,
				"providerId": 16441,
				"lastUpdated": "2017-12-21T18:30:00Z",
				"isManual": false,
				"createdDate": "2017-12-22T05:47:35Z",
				"aggregationSource": "USER",
				"status": "IN_PROGRESS",
                                "requestId": "NSyMGo+R4dktywIu3hBIkc3PgWA=",
				"dataset": [{
					"name": "BASIC_AGG_DATA",
					"additionalStatus": "ACCT_SUMMARY_RECEIVED",
					"updateEligibility": "DISALLOW_UPDATE"
				}]
			}]
		}
	}
}

REFRESH.PROCESS_COMPLETED

Process Completed Success Event Response

{
	"event": {
		"info": "REFRESH.PROCESS_COMPLETED",
		"loginName": "fri21",
		"data": {
			"providerAccount": [{
				"id": 10995860,
				"providerId": 16441,
				"isManual": false,
				"createdDate": "2017-12-22T05:47:35Z",
				"aggregationSource": "USER",
				"status": "SUCCESS",
                                "requestId": "NSyMGo+R4dktywIu3hBIkc3PgWA=",
				"dataset": [{
					"name": "BASIC_AGG_DATA",
					"additionalStatus": "AVAILABLE_DATA_RETRIEVED",
					"updateEligibility": "ALLOW_UPDATE",
					"lastUpdated": "2017-12-22T05:48:16Z",
					"lastUpdateAttempt": "2017-12-22T05:48:16Z"
				}]
			}]
		}
	}
}

Process Completed Failure Event Response

{
	"event": {
		"info": "REFRESH.PROCESS_COMPLETED",
		"loginName": "fri21",
		"data": {
			"providerAccount": [{
				"id": 10995860,
				"providerId": 16441,
				"isManual": false,
				"createdDate": "2017-12-22T05:47:35Z",
				"aggregationSource": "USER",
				"status": "FAILED",
                                "requestId": "NSyMGo+R4dktywIu3hBIkc3PgWA=",
				"dataset": [{
					"name": "BASIC_AGG_DATA",
					"additionalStatus": "DATA_RETREIVAL_FAILED",
					"updateEligibility": "ALLOW_UPDATE",
					"lastUpdated": "2017-12-22T05:48:16Z",
					"lastUpdateAttempt": "2017-12-22T05:48:16Z"
				}]
			}]
		}
	}
}
Note: The status and additionalStatus values may vary depending on the type of failure. Customers have to refer to the different types of status and additional status for effective implementation.

Best Practices

  • User input required events are time-bound. When the notification is received, customers should ask for the MFA information from users and post it to the relevant Yodlee API before the process gets timed out.
  • If you have subscribed for notifications, customers should not call the get provider account API; this action can prevent Yodlee from notifying customers for the user input required event and may lead to add/update account failures.
  • Yodlee does not recommend customers having implementations with different API versions. The refresh webhooks will always use the latest API version format in such cases.
  • When the providerAccount is not eligible to be called in the update account API, the reason will be given to customers in the update account response as API errors. Notifications will not be sent to customers in such cases.
  • There are possibilities that add or update account process takes a longer time. Customers need not hold users on the screen; communicate to them that the process is taking longer than usual and provide them options to proceed with other associated activities.

Frequently Asked Questions

What does refresh mean?
Refresh is a process of adding accounts from the provider site or updating the already added accounts with the latest information.

Do notifications get delayed? How do we handle the same?
Yes, there are possibilities where the provider does not respond or takes a longer time than usual. If you don’t receive a response within a specific time period, inform the users that the process is taking longer than usual and ask them to proceed with other associated activities. Yodlee will still send notifications once the process is completed.