Practical Tips for Using Yodlee IAV

20 Dec 2016

 

Yodlee is an aggregation service companies use to access customer financial information. Its Instant Account Verification (IAV) provides account- and transaction-level data about customer activity which companies use to perform day-to-day procedures such as loan and insurance processing.

To access this data, companies create Yodlee accounts for their customers who then search for their institutions in FastLink UI, log in to those institutions’ accounts, and link them. Once the accounts are linked, the data becomes available to the company via Yodlee API. The software developer then integrates the Yodlee API with the company’s API.

To save software developers the time and effort needed to create applications to access each specific financial institution’s API, Yodlee provides unified APIs so data can be transferred from financial institutions to the businesses seeking customer information. Yodlee supports thousands of institutions at a relatively low price, so it has become widely used by companies working in the financial sector.

Although Yodlee offers some benefits, developers should be aware of common “white spots” that are not immediately apparent when using its IAV service. The purpose of this article is to help developers avoid some of the most prevalent issues.

User registration

The application needs to perform user registration for developers to access most of the “flows” in Yodlee. A company (or “brand” in Yodlee terms) registers users so they can log into their financial sites in FastLink UI later. After login, the application receives a unique “user token” that identifies that specific account’s data.

In order to register a user, the application needs to generate a username and password. They are never shown to the user, and they should be securely stored. For the username, you can use your application username. The password must follow several requirements:

  • It must be 6 to 50 characters in length.
  • It must contain at least one letter and one number.
  • It should not be same as the username.
  • It should not contain a sequence or repeated characters. (For example, aaa123 is an invalid password.)
  • It should not contain whitespace or control characters.

To avoid creating invalid passwords, I suggest using the following simple algorithm. This code snippet is in Ruby and is pretty straightforward:

def generate_yodlee_password
      letters = ('a'..'z').to_a
      digits = ('0'..'9').to_a
      allowed_chars = letters + digits

      password = digits.sample + letters.sample

      while password.length < 32 do
        new_char = allowed_chars.sample
        password << new_char if new_char != password.last
      end

      password
    end

The code above generates a fixed-length (32-character) password that conforms to Yodlee’s requirements. Make sure you do not store plain text passwords in your database!

FastLink integration

To access FastLink UI, the application needs to:

  1. Perform cobrand login to get the cobrand token.
  2. Register/log in the user to get the user token.
  3. Generate the FastLink token.
  4. Send POST request from the browser to the URL composed of elements above.

(Please refer to the documentation for more details.)

Step 4 above is typically performed by a user who needs to click a certain button that submits an HTML form using a POST method. This essentially means that the customer leaves your site, and you have no control over that user’s experience on the next FastLink UI page. When the user finishes linking his/her financial accounts, he/she “closes” the page by clicking on the link, and FastLink redirects him/her back to your site.

But what if you want to customize the interface and the UX, not just the branded FastLink page, for your application’s specific needs? For example, you may want to see a modal dialog with FastLink UI at the top of your page.

One way to perform this customization is to use IFRAMEs and to carry out “form submit” in JavaScript. You can create a form with hidden fields on your page. The fields would contain the tokens received from Yodlee and the form’s target will be equal to the IFRAME’s id:

<form action="<YODLEE BASE URL>/authenticate/iloan/" method="post" target="'yodlee_fastlink">
  <input type="hidden" name="app" id="yodlee_form_app" value="..."/>
  <input type="hidden" name="rsession" id="yodlee_form_rsession" value="..."/>
  <input type="hidden" name="token" id="yodlee_form_token" value="..."/>
  <input type="hidden" name="redirectReq" id="yodlee_form_redirect" value="true"/>
</form>
…
<iframe id='yodlee_fastlink' name='yodlee_fastlink' frameBorder='0'/>

Using this method, you will be able to view FastLink at the top of your page. In fact, the company-owned UI can now be styled to your preferences.

Synchronous UI flows

If you want to synchronously access user information right after you close FastLink, you should be aware of a potential issue involving Yodlee’s refresh process. Let’s say you allow users to link their accounts, close the FastLink dialog, and submit your page. Then you start processing the linked financial data. However, Yodlee starts the refresh process in the background after a user has linked his/her accounts, and the data is not immediately available for your application.

As a solution, you need to start periodical polling Yodlee by using getAllSiteAccounts API. For each site returned by this API, you need to check the refresh status by using getSiteRefreshInfo API. When no sites indicate “refresh in progress” status, your application can access the financial data.

In order to improve the UI experience, you can also show a spinner on the page that lets the user know that processing is on-going. In the background, your web front-end can make periodical requests to your web application API to check if the refresh is still in progress.

Testing

During this phase, make sure to check the real financial data before releasing your code to production. Yodlee’s Dummy Account Generator allows you to load anything, even invalid data. Unfortunately, the only way to check how your code will process real data is to link it to real financial accounts.

I also advise you not to rely on Yodlee to provide correctly formatted bank account numbers. Even if they are retrieved successfully, they can have glitches. For example, they may come back with dashes or other extraneous characters not present in the real account number.

Error handling

One way to alleviate errors is to validate all responses from Yodlee’s API. Your assumptions on data formats or required data elements can be wrong. If you encounter errors in your code during production, you can spend a lot of time trying to discover the real cause. On the other hand, if your Yodlee client library notes meaningful errors regarding absent elements or incorrect formats, you can easily spot and correct the real error. A “fail fast” strategy can be very useful in such situations.

I also recommend logging all your interactions with Yodlee, including their durations. This will help you when troubleshooting issues with the Yodlee support team. Of course, the log data should be securely stored because it can contain PII.

Unfortunately, no single error response format exists. You can reference the information here to match your response against several possible error message formats before actually trying to process one.

Token caching

Cobrand login and user login/registration operations return tokens that can be reused. I highly recommend you cache them according to Yodlee’s information regarding their duration periods.

I also advise using an interprocess cache like Memcache or Redis for these tokens. For our clients, the cobrand token expiration time is 90 minutes. The user token cache expiration time is 20 minutes.

Token caching not only allows you to optimize the performance of your application, but it also helps you avoid some “race condition” scenarios. Sometimes users can refresh a page or press the “Back” button, which can lead to the second parallel set of API requests being sent to Yodlee. If you do not reuse the same user session, your other session will fail on the next operation simply because the login of the second session will invalidate the first one.

Summary

Yodlee API integration can be a complex procedure. To help developers save significant time and effort, I recommend the following:

  • User registration: Generate a valid password by following a simple algorithm. Do not store this password as plain text.
  • FastLink integration: Use IFRAMEs and carry out “form submit” in JavaScript.
  • Synchronous UI flows: Periodically poll Yodlee’s sites and monitor the refresh status of each site the API returns.
  • Testing: Closely check the accuracy of the real financial data, including all bank account numbers, before releasing your code to production. Do not assume Yodlee will return correctly formatted account numbers.
  • Error handling: Validate all responses from Yodlee’s API and log all your interactions with Yodlee, including their durations.
  • Token caching: Use an interprocess cache like Memcache or Redis for reusable tokens returned during cobrand login and user login/registration operations.