REFRESH EVENT

The current information for this feature in the Yodlee ver 1.1 release can be found on page https://developer.yodlee.com/Yodlee_API/docs/v1_1/Webhooks/Refresh_Event

The event REFRESH refers to the actions that happen during the add account and update account processes triggered by the users:

  1. Add provider account for linking accounts
  2. Update provider account for:
    1.  Editing the credentials of the added provider account
    2.  Updating (refreshing) the provider account for the latest information of accounts
Note :
  • Customers using FastLink cannot subscribe for REFRESH notifications.
  • Customers building their own add/update account user experience using APIs should not call get providerAccount detail API during the process.

The following are the three refresh related events for which notifications will be sent to customers:  

  1. User Input Required
  2. Interim Progress
  3. Process Completed

User Input Required

This is an event that notifies customers that the provider site needs some additional authentication information from the user to successfully add or update his/her account. This will be triggered for multifactor authentication (MFA) based provider sites. 

Note: There are chances that the MFA information is provided in the add account API or update account API response. In such cases, the notifications will not be sent to customers. 

Interim Progress

Login success and account summary are two interim progress events.

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.

Refresh Event Flow

The following diagram explains the flow between customer, the Yodlee system, and the provider site when the customer has subscribed to notifications

Event Payload Information

The payload sent to the customer-provided URL has a common structure, wherein the data attribute within the structure varies for every notification. The payload will have the following structure:

"event": {
  "info": "REFRESH.PROCESS_COMPLETED",
  "loginName": "yodleeuser",
  
  "data": {
   "providerAccount": {
    "id": 10523426,
    "providerId": 19686,
    "isManual": false,
    "createdDate": "2017-05-09",
    "aggregationSource": "USER",
    "refreshInfo": {
     "statusCode": 0,
     "statusMessage": "OK",
     "status": "SUCCESS",
     "nextRefreshScheduled": "2016-03-23T10:22:54Z",
     "lastRefreshed": "2016-03-22T10:23:07Z",
     "lastRefreshAttempt": "2016-03-22T10:23:07Z"
    }
   }
  }
}
Event Attributes Name

Details
info

This attribute refers to the event name for which the customer is notified. The event info follows:

  1. REFRESH.USER_INPUT_REQUIRED
  2. REFRESH.INTERIM_PROGRESS
  3. 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.

 

Events

Event-Data Attribute Details

REFRESH.USER_INPUT_REQUIRED

User Input Required Event Response

MFA type - Question & Answer

{
"data": {
  "providerAccount": {
    "id": 10523102,
    "providerId": 19686,
    "isManual": false,
    "createdDate": "2017-05-09",
    "aggregationSource": "USER",

    "refreshInfo": {
         "status": "IN_PROGRESS",
         "additionalStatus": "USER_INPUT_REQUIRED",
         "statusCode": 801,
         "statusMessage": "ADD_IN_PROGRESS"
    },
    "loginForm": {
      "mfaTimeout": 95650,
      "formType": "questionAndAnswer",
      "row": [
        {
          "id": "SQandA--QUESTION_1--Row--1",
          "fieldRowChoice": "0001",
          "form": "0001",
          "label": "What is the name of your state?",
          "field": [
            {
              "id": "SQandA--QUESTION_1--1",
              "name": "QUESTION_1",
              "isOptional": false,
              "value": "",
              "valueEditable": "true",
              "type": "text"
            }
          ]
        },
        {
          "id": "SQandA--QUESTION_2--Row--2",
          "fieldRowChoice": "0002",
          "form": "0001",
          "label": "What is the name of your first school",
          "field": [
            {
              "id": "SQandA--QUESTION_2--2",
              "name": "QUESTION_2",
              "isOptional": false,
              "value": "",
              "valueEditable": "true",
              "type": "text"
            }
          ]
        }
      ]
    }
  }
}
}

MFA type - Token

{
"data":{
	
   "providerAccount": {
	"id": 10526355,
         "providerId": 19686,
         "isManual": false,
         "createdDate": "2017-05-09",
         "aggregationSource": "USER",

		"refreshInfo": {
		             "statusCode": 801,
			"statusMessage": "ADD_IN_PROGRESS",
			"status": "IN_PROGRESS",
			"additionalStatus": "USER_INPUT_REQUIRED"
		},
		"loginForm": {
			"mfaTimeout": 61590,
			"formType": "token",
			"row": [{
				"id": "token_row",
				"label": "Security Key",
				"fieldRowChoice": "0001",
				"form": "0001",
				"field": [{
				      "id": "token",
				       "name": "tokenValue",
				      "isOptional": false,
				      "value": "",
				      "valueEditable": "true",
				      "maxLength": 10,
				      "type": "text"
						}]
					}]
				}
			}
        }
	}

MFA type - Image

{
  "data":{
  "providerAccount": {
    "id": 10815719,
    "providerId": 19686,
    "isManual": false,
    "createdDate": "2017-05-09",
    "aggregationSource": "USER",
    "refreshInfo": {
      "statusCode": 801,
      "statusMessage": "ADD_IN_PROGRESS",
      "status": "IN_PROGRESS",
      "additionalStatus": "USER_INPUT_REQUIRED"
    },
    "loginForm": {
      "mfaTimeout": 59250,
      "formType": "image",
      "row": [
        {
          "id": "image_row",
         "fieldRowChoice": "0001",
          "form": "0001",
          "field": [
            {
              "id": "image",
              "name": "imageValue",
              "isOptional": false,
              "value": "",
              "valueEditable": "true",
              "minLength": 5,
              "maxLength": 10,
              "type": "text",
              "image": [
                66,
                77,
                -122
                            ]
            }
          ]
        }
       ]
    }
   }
 }
}

REFRESH.INTERIM_PROGRESS

Login Success Event Response

{
	"data": {
		"providerAccount": {
		"id": 10526354,
                "providerId": 19686,
                "isManual": false,
                "createdDate": "2017-05-09",
                "aggregationSource": "USER",

			"refreshInfo": {
				"statusCode": 0,
				"statusMessage": "OK",
				"status": "IN_PROGRESS",
				"additionalStatus": "LOGIN_SUCCESS"
			}
		}
	}
}

Account Summary Retrieved Event Response

{
"data": {
	"providerAccount": {
      "id": 10526354,
      "providerId": 19686,
      "isManual": false,
      "createdDate": "2017-05-09",
      "aggregationSource": "USER",
 
	    "refreshInfo": {
	     "statusCode": 0,
	     "statusMessage": "OK",
	     "status": "IN_PROGRESS",
	    "additionalStatus": "ACCOUNT_SUMMARY_RETRIEVED"
			}
		}
	}
}

REFRESH.PROCESS_COMPLETED

Process Completed Success Event Response

{
	"data": {
		"providerAccount": {
		   "id": 10526354,
                   "providerId": 19686,
                   "isManual": false,
                    "createdDate": "2017-05-09",
                    "aggregationSource": "USER",

			"refreshInfo": {
				"statusCode": 0,
				"statusMessage": "OK",
				"status": "SUCCESS",
				"nextRefreshScheduled": "2016-04-08T20:25:10Z",
				"lastRefreshed": "2016-04-07T14:27:49Z",
				"lastRefreshAttempt": "2016-04-07T14:27:49Z"
			}
		}
	}

}

Process Completed Failure Event Response

{
	"data": {
		"providerAccount": {
		    "id": 10526261,
                "providerId": 19686,
                  "isManual": false,
              "createdDate": "2017-05-09",
              "aggregationSource": "USER",

			"refreshInfo": {
				"statusCode": 508,
				"statusMessage": "INSTANT_REQUEST_TIMEDOUT",
				"status": "FAILED",
				"additionalStatus": "REQUEST_TIME_OUT",
				"nextRefreshScheduled": "2016-04-07T12:40:42Z"
			}
		}
	}

}

Note :

The status and additionalStatus values may vary depending on the type of failure. Customers have to refer for the different types of status and additional status for effective implementation.

 

Best Practices

  • Customers should call the webhooks supported add account and update account APIs exposed under the provider account's end points.
  • 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 the customer has subscribed to the user input required event, customers should not call the get provider account API to retrieve the MFA information requested; this action can prevent Yodlee from notifying customers for the user input required event.
  • 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. Notifications will not be sent to customers in such cases.
  • There are situations when the MFA request information is retrieved quickly from the provider site. In such situations, the MFA information will be made available in the add account and update account responses and notifications will not be sent to customers.
  • 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.

FAQs

What does refresh means?
Refresh is a process of adding accounts from the provider site or updating the accounts that are already added with 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.