Credential Based Account Aggregation
Working with Datasets
What is a Dataset?
A dataset is a logical grouping of data attributes used for requesting a specific set of data from the data providers during add and refresh accounts.
Yodlee platform v1.1 supports four datasets: BASIC_AGG_DATA, ADVANCE_AGG_DATA, and ACCT_PROFILE. You can choose the dataset and attributes required for your business during the onboarding process.
- Premium – Dataset attributes that require additional navigation to aggregate.
- Sensitive – Dataset attributes like PII are sensitive and can be misused for fraudulent purposes. To subscribe to sensitive data, the audit or compliance criteria of the Yodlee Security Office have to be met.
Click the appropriate dataset tab to view the attributes-related details specific to the dataset:
| Dataset Attributes | Applicable Containers/Account Types | Regions | API Endpoints | Fields |
|---|---|---|---|---|
| BASIC_ACCOUNT_INFO | bank, investment, credit card, insurance, loan, reward, and bill. | All regions | GET/accounts GET/accounts/{accountId} | accountId accountNumber accountName accountType balance availableBalance |
| ACCOUNT_DETAILS | bank, investment, credit card, insurance, loan, reward, and bill. | All regions | GET/accounts GET/accounts/{accountId} | All attributes |
| TRANSACTIONS | bank, investment, credit card, insurance, and loan | All regions | GET transactions | All attributes |
| HOLDINGS | investment and insurance | All regions | GET/holdings | All attributes |
| STATEMENTS | credit card, insurance, loan, and bill. | All regions | GET/statements | All attributes |
| Dataset Attributes | Applicable Containers/Account Types | Regions | API Endpoints | Fields |
|---|---|---|---|---|
| INTEREST_DETAILS | loan | US | GET/accounts GET/accounts/{accountId} | interestRate interestRateType |
| PAYMENT_DETAILS | loan | US | GET/accounts GET/accounts/{accountId} | payByDate payoffAmount outstandingBalance |
| COVERAGE | investment and insurance | US and Australia | GET/accounts GET/accounts/{accountId} | type startDate endDate amountType limitType (applicable only for health insurance) unitType (applicable only for health insurance) cover met(applicable only for health insurance) |
| Dataset Attributes | Applicable Containers/Account Types | Regions | API Endpoints | Fields |
|---|---|---|---|---|
| FULL_ACCT_NUMBER | bank, investment, and loan | US, UK, Canada, Australia, and India. | GET/accounts GET/accounts/{accountId} | paymentAccountNumber unmaskedAccountNumber fullAccountNumber(deprecated) |
| BANK_TRANSFER_CODE | bank and investment. | US: Routing number India: IFSC Australia: BSB (Bank-StateBranch) UK: Sort code sites in the United States. | GET/accounts GET/accounts/{accountId} | bankTransferCode |
| HOLDER_NAME | bank, loan, and investment. | US, UK, Canada, Australia, and India. | GET/accounts?include=holder,profile GET/accounts/{accountId}?include=holder, profile | holder.name holder.ownershipType |
| HOLDER_DETAILS | bank and investment. | US, UK, Canada, Australia, and India. | GET/accounts?include=holder,profile GET providerAccounts/profile | holder profile |
| PAYMENT_PROFILE | loan | US | GET/accounts, GET/accounts/{accountId} | identifier address paymentBankTransferCode |
Dependent Datasets
Certain datasets are retrieved even though they are not provided in the request. Following datasets are retrieved implicitly during the add, edit, and update/refresh account flows so the requested datasets can be retrieved successfully.
| Requested Dataset | Implicit Dataset | Applicable Containers |
|---|---|---|
| ADVANCE_AGG_DATA.INTEREST_DETAILS | BASIC_AGG_DATA.ACCOUNT_DETAILS BASIC_AGG_DATA.BASIC_ACCOUNT_INFO | Loan |
| ADVANCE_AGG_DATA.PAYMENT_DETAILS | BASIC_AGG_DATA.ACCOUNT_DETAILS BASIC_AGG_DATA.BASIC_ACCOUNT_INFO | Loan |
| ADVANCE_AGG_DATA.COVERAGE | BASIC_AGG_DATA.BASIC_ACCOUNT_INFO | Investment Insurance |
| ACCT_PROFILE.FULL_ACCT_NUMBER | BASIC_AGG_DATA.BASIC_ACCOUNT_INFO | Bank Investment Loan |
| ACCT_PROFILE.BANK_TRANSFER_CODE | BASIC_AGG_DATA.BASIC_ACCOUNT_INFO | Bank Investment |
| ACCT_PROFILE.HOLDER_DETAILS | ACCT_PROFILE.HOLDER_NAME BASIC_AGG_DATA.BASIC_ACCOUNT_INFO | Bank Investment |
| ACCT_PROFILE.HOLDER_NAME | BASIC_AGG_DATA.BASIC_ACCOUNT_INFO | Bank Investment |
| ACCT_PROFILE.PAYMENT_PROFILE | ACCT_PROFILE.FULL_ACCT_NUMBER BASIC_AGG_DATA.BASIC_ACCOUNT_INFO | Loan |
| BASIC_AGG_DATA.ACCOUNT_DETAILS | BASIC_AGG_DATA.BASIC_ACCOUNT_INFO | Bank Investment Credit Card Insurance Realestate Loan Reward Bill |
| BASIC_AGG_DATA.HOLDINGS | BASIC_AGG_DATA.BASIC_ACCOUNT_INFO | Investment Insurance |
| BASIC_AGG_DATA.STATEMENTS | BASIC_AGG_DATA.BASIC_ACCOUNT_INFO | Insurance Loan Bill Credit Card |
| BASIC_AGG_DATA.ACCOUNT_DETAILS | CreditCard |
Choose Your Dataset Attributes
- You have the flexibility to choose among the dataset attributes needed for your product flow.
- You can configure the datasets to be retrieved by default and the datasets to be retrieved on demand.
- During the onboarding process, work with the Yodlee support team to define your dataset configurations and containers.
Important Notes
- Sensitive dataset attributes can be passed only if the same has been subscribed if not, an error will be returned.
- If a dataset attribute or a container is not supported, an error will be returned.
- If a data provider does not support some of the dataset attributes, then data only for the supported dataset attributes will be returned.
- If a subscribed dataset attribute is requested for multiple containers, but the provider supports the attribute only for one container, the request will be honored for the supported container and the rest will be ignored.
- If multiple subscribed dataset attributes are requested, but the provider does not support one of the dataset attributes, the request will be honored for the supported dataset and the rest will be ignored.
- If multiple subscribed dataset attributes are requested but the provider does not support all the requested dataset attributes then an error will be returned.
APIs Accepting Datasets as Input
The following is the list of API services that accept dataset and dataset attributes:
| Endpoint URL | Input Parameter | Impact |
|---|---|---|
| GET providers | dataset | Helps return all the provider sites supporting the provided datasets. Helps search a site supporting the provided datasets. Helps return the popular and suggested sites supporting the provided datasets |
| POST providerAccounts PUT providerAccounts | dataset datasetName | Indicates the data to be retrieved from the provider site that corresponds to the dataset name. If not provided, the implicit dataset attributes have to be retrieved. |
Link or Update Account API Implementation Flow Charts
Using the providerAccounts API services, you can add or update an account for a user. Click to view the Add or Update Account Flow Chart.
Add and update account summary view. Click to view the Flow Chart.
End User Account Credential Encryption
The Yodlee platform serves a customer base of Financial Institutions and FinTech companies. The end-users of our customers can link their financial accounts (bank, brokerage, credit card accounts, etc.) to the Yodlee platform. Our customers then have a comprehensive and regularly updated view of their end-users’ financial assets and needs. The Yodlee platform also supports account verification on behalf of customers to confirm their end-users’ account ownership.
Yodlee supports linking an account through Yodlee APIs. These APIs accept sensitive and personally-identifiable information (PII), like account access credentials. Network communication to these APIs uses the industry-standard Transport Layer Security defined as part of the https protocol.
In addition to encryption defined by the https protocol, Yodlee further protects end-user data by requiring account access credential data to be encrypted before uploading to a Yodlee server.
What Data is Encrypted?
If you use your own code to link your end-users accounts to the Yodlee platform, and not the FastLink tool, you must encrypt the end-user credentials to access an online financial account before uploading them to Yodlee. These fields are provided with a loginForm entity type when calling the relevant APIs and are identified in the table below.
| Fields | Examples |
|---|---|
formType=login & fieldType=password |
|
formType=questionAndAnswer & fieldType=password | Security answers for Multi-Factor Authentication questions |
In the “add or edit credentials” flow of your browser or app, when not using FastLink, encrypt these fields (only) before passing the encrypted data to Yodlee.
Note: Do not encrypt OTP (formType: token) or CAPTCHA (formType: image).
Encryption is not supported in the Sandbox environment, and should not be done in apps under development there. Encryption is supported in the Development and Production environments for all other pricing tiers (Launch, Grow, and Enterprise).
Yodlee APIs Requiring Data Encryption
These two API calls are the ones that upload account credential data. When you call either of these APIs to add or change credential data, you must first encrypt the credential data.
- Add Account: POST /providerAccounts
- Update Account: PUT /providerAccounts
If the credentials need to be updated, you can first retrieve them using the Get Provider Account Details: GET /providerAccounts/{providerAccountId}?include=credentials API call. The credentials will be returned to you in decrypted (plain) form.
How to Encrypt Data
Yodlee uses the RSA algorithm to encrypt credential data and provides you with an RSA public key for this purpose. You can encrypt the data by writing a short computer program, starting from the Java example shown below. Alternatively, you can test the process and encrypt small amounts of data by using the interactive form on the RSA Encryption Utility page.
To encrypt data in software, follow these steps:
Step 1: Retrieve the Public Key
Retrieve your public key using the GET /configs/publicKey endpoint once per application session. When retrieved, the public key can be cached on one of your servers.
Sample Response
{
"publicKey":{
"alias":"03072_9",
"key":"-----BEGIN PUBLIC KEY-----\r\nMIIBIjANBgkqhkiG9w0BAQEFAAOC\r\n-----END PUBLIC KEY-----"
}
}
Note: The RSA key pair used to encrypt/decrypt credentials is separate and unrelated to the RSA key pair used for JWT token creation.
Step 2: Encrypt the User Credentials
To encrypt one field using the public key obtained in Step 1: Retrieve the Public Key:
- Convert the string named "keyAsPemString" to a key object. The string is an RSA public key in PEM format.
PEM means “Privacy Enhanced Mail” and simply means the binary key has been encoded as one kind of base64 encoding to ensure it only contains printable ASCII characters. - Encrypt the data using the options “RSA/ECB/PKCS1Padding” and the key object.
- Hex-encode the encrypted data as a string.
- Note that the sample response returned from step 1 included a string called “keyAlias”. In the example, the keyAlias has the value “03072_9”. Concatenate the literal value of the keyAlias string “03072_9” + “:” + the hex-encoded encrypted string to form the encrypted data for this field.
You may find it helpful to use the BouncyCastle open-source encryption library, which can be found at https://www.bouncycastle.org/. Bouncy Castle has code libraries for Java and C#.
Here are the core steps in Java.
String keyAlias = "03072_9";
StringReader fileReader= new StringReader(keyAsPemString);
PEMReader pemReader= new PEMReader(fileReader);
PublicKey pk= (PublicKey)pemReader.readObject();
Cipher c = Cipher.getInstance ("RSA/ECB/PKCS1Padding");
c.init(Cipher.ENCRYPT_MODE, pk);
ciphertext = c.doFinal(cleartext.getBytes());
return keyAlias + ”:” + HexEncode.encode(ciphertext);
Step 3: Send the Encrypted User Credentials
In the “add or edit credential” flow, send the encrypted user credentials to the POST /providerAccounts or PUT /providerAccounts endpoints. All other details are similar to the non-encrypted “add an account or edit credentials” flow.
Sample Request:
{
"field":[
{
"id":"XXXXX",
"value":"02122015_1:0472a89dbdfccad71ec34361d8585d0f77028197abfadc11bf0c0"
},
{
"id":"XXXXX",
"value":"02122015_1:5d6643f0e861952a0580e4ddd48f3b1d17a2583edd2e9dc744a884e93b38b415de5e700a"
}
]
}
Note: The encrypted data are known as “value” starts with the string “02122015_1:”. This is the keyAlias for this developer. The encrypted credential follows the colon. The keyAlias tells Yodlee which private key to use to decrypt the credential when you next ask for it.
Error Response
If the following response is received, the keys assigned to you have changed, so fetch and cache the keys again (Step 1: Retrieve the Public Key). The Http response status is 400 and the error message is below. The error message may contain additional fields and values.
{
"errorCode": "Y400"
"errorMessage": "Decryption failure for FieldInfo"
}
Best Practices
If you are linking accounts using Yodlee APIs instead of Yodlee FastLink, we recommend you encrypt the credentials before you post to the Yodlee APIs. Along with the credentials, also encrypt the associated multi-factor authentication details like answers. Encrypt the data passed in, add a provider account, or update a provider account API calls.
Follow the instructions provided in the Credential Encryption page to encrypt the data before uploading it. You may also find the encryption utility page useful while testing. This page will encrypt strings that you provide, including strings with < or > in.
If you are not using Yodlee FastLink to link accounts, code for the following different types of MFA supported by Yodlee:
- Security questions and answers
- Token ID authentication
- CAPTCHA image authentication
- Multistep authentication
If you are not using Yodlee FastLink to link accounts, code for the following in the add/update account flows:
| Recommendation | Benefit |
|---|---|
| Construct the login form user experience using all the login form fields provided, including the optional fields. | Reduced user confusion while providing credentials, as login field names displayed to them will be the same as those in the provider site. |
Use the maxLength field, if provided in the login form fields. | Limits users from inputting credentials less than or exceeding the permitted length on the provider site. |
| Implement the Re-enter Password feature while accepting credentials from users. | Avoids errors when users enter credentials since they will be required to enter the same credentials twice. |
| Implement the Show Password field in the login form screen. | Gives users the option to view the characters they entered as passwords while will help them verify the entered password. |
| Implement the Edit/Update Credentials option in your application. | Helps the user to update their credentials during the add account flow rather than aggregating them again multiple times and avoid creating multiple provider account IDs. |
| Display site-level and login form help text provided in the login form to users. | Helps users provide the correct set of information for successful aggregation or log in. |
| Do not allow users to copy and paste passwords in to the login form. | Ensures that a user is not entering additional characters unintentionally and there are no cookie issues. |
| Enforces users to select at least one option to enter their credentials when the login form has multiple options. | Ensures that users do not leave any mandatory field empty or blank. |
- Display bank logos during the financial institution selection process and when users are asked to enter their credentials. Users feel more secure when they see the logo and it offers them clarity about which credentials are required.
- Provide a live URL of the user’s selected financial institution. If the user cannot recall their credentials, they are able to go directly to the FI site to obtain them.
- Be specific about which credentials are required to aggregate the user’s account. Restate the name of the financial institution selected alongside the username and password entry fields to minimize confusion.
- Let users see their password as they type using the eye icon.
Use the login form attributes found in the response of the polling API or REFRESH notification while building your MFA page:
- Use the
mfaInfoTitle,mfaInfoText, andmfaTimeoutavailable inloginFormentity in the form that you display to the user. Familiar brand names and icons reassure users. - Display counter for timeouts to let the user know the time remaining.
- Validate that the actual input length is no greater than
field.maxLength.
- When the user logs into your application, check for the following error cases, and push notification in your application, if any of them occur:
- Invalid MFA information provided
- New MFA information required
- Indicate user to answer all unanswered questions
- Implement the following flow in your application to correct the MFA error and refresh accounts:
The GET-provider/{providerId} API service lets you know what datasets are available for a provider. If you want to explicitly pass datasets, provide only the datasets supported by your provider to PUT /providerAccounts or POST /providerAccounts API services.
The dataset.additionalStatus field in the providerAccount API services response gives detailed information on why the PUT /providerAccounts or POST /providerAccounts API service calls failed. You have to refer to the list of the dataset.additionalStatus values in the data model page and design the user experience on your application.