Plaid

This package provides capabilities that extend the Avoka Transact platform with integration to the Plaid solutions. Plaid enables applications to connect with users bank accounts and to access accounts data, balance data, income data, transaction data, and account ownership details.

To support retrieving data from bank accounts using Plaid, this package provides the following Maestro components:

Plaid Link
This component is used for integrating with Plaid Link which offers a way to integrate with the Plaid API. Link is a drop-in module that handles credential validation, multi-factor authentication, and error handling for each institution that is supported all while keeping credentials from ever hitting the Avoka server.
Open Plaid Link
This is a single button component for opening the Plaid application.
Plaid Accounts
This component is used for retrieving bank accounts linked to Plaid using Dynamic data button. And displaying the accounts details and balances in a repeat block.
Plaid Get Balance
This component is similar to Plaid Accounts. And used for retrieving the real-time balance for each of the bank accounts.
Plaid Get Identity
This component is used for retrieving various account holder information with the financial institution, including names, emails, phone numbers, and addresses.
Plaid Get Income
This component is used for retrieving income information such as annual income and income streams.

Licensing

Clients must ensure they are appropriately licenses in order to use this package. Organisations who wish to use this package are required to establish a commercial relationship with Plaid directly.

Compatibility

This package has the following compatibility requirements:

Module	Compatibility	Notes
Transact Manager	5.0 or above
Transact Maestro	5.0.14 or above

Installation Instructions

To install this package please walk through the following proceedure:

Unzip the package to a directory on your computer
Import each zip archive found in the services folder to Transact Manager under the Services >> All Services menu item.
Review the Help Doc tab for each of the imported services and make any required adjustments to service parameters.
Configure any required Service Connections. These requirements can be found at the bottom of this document or in the Help Doc for each of the imported services.

Service Connections can be configured in Transact Manager under the Services >> Service Connections menu item.
Import each archive found in the libraries folder to Maestro.

Importing these into the Organisation level libraries folder is recommended as this will make the components available to all projects, however they can be imported at the Project level if required.

Usage Instructions

To configure Plaid please walk through the following procedure:

Open your form in Maestro and add the Plaid Link component from the Plaid category in the Palette. This widget is invisible, so it can be placed at the top or bottom of the form.
Open the Configuration section on the Properties tab of the Plaid Link component, and configure the following details:
- Client Name: This value is shown to the user once they have successfully linked their account with Plaid e.g.
  Your account has been successfully linked to {Client Name}
- Products: Select the Plaid products you wish to use. By default all the products are selected. (see Plaid Products)
Note that the target Plaid Environment setting and and Public Key will be loaded from the Plaid - Service Connection on initialization.
Drag and drop the Open Plaid Link button from Plaid category in the Palette. At this stage you should be able to click on the button to open Plaid frame to select a bank.
Display the results in the form. You can add one or more of the following components to the form:
NOTE : The display component has a button to run the relevant service. This button is hidden by default, and can be triggered from the Plaid Link On Success rule as described below.
Open the Properties tab of the Plaid Link component and create new On Success rule. Add code to fire the click rule of the button as described before.

NOTE : The public token is returned from the On Success rule, and it's a mandatory input field for each of the services. The system also creates data field called plaidPublicToken to store the public token.

E.g. to fire the display accounts click rule:
```
Form.fireRule("click", Form.getItemFromPath('data.displayAccounts'), data);
```
Open the Properties tab of the Plaid Link component, and create new rule called On Exit. Add code to grab the error message, if the user exits the Plaid portal unexpectedly.

E.g.
```
if (info && info.display_message) {
data.accountsErrorMessage = info.display_message;
}
```

Release Notes

Version 1.0 July 12, 2017

Baseline release.

Plaid Accounts Library: exchange.plaid Category: Plaid

Block for displaying details of accounts

Service Calls

Plaid - Get Accounts

Plaid Get Balance Library: exchange.plaid Category: Plaid

Block for displaying real-time balance for each of the bank accounts

Service Calls

Plaid - Get Balance

Plaid Get Identity Library: exchange.plaid Category: Plaid

Retrieve and display various account holder information with the financial institution, including names, emails, phone numbers, and addresses

Service Calls

Plaid - Get Identity

Plaid Get Income Library: exchange.plaid Category: plaid

Display annual income and income streams

Service Calls

Plaid - Get Income

Plaid Link Library: exchange.plaid Category: Plaid

Plaid link is a widget that uses the Plaid Link JavaScript library to integrate with the Plaid API

Rule Templates

You may add your own logic to handle the following rule types triggered by this component:

On Success : a script to run on success of plaid login
On Exit : a script to run when the user exited the Link flow. If the user encountered a Plaid API error prior to exiting, the error message will be returned in the info parameter

Properties

Property	Category	Description	Type	Default
Client Name	Configuration	This value is presented in a confirmation message to the user once they have successfully linked their account with Plaid e.g. Your account has been successfully linked to {Client Name}	text
Auth Product	Configuration	Add the auth product to the list of Plaid products to retrieve account and routing numbers for ACH authentication.	boolean	`true`
Identity Product	Configuration	Add the identity product to the list of Plaid products to retrieve identity information on file with the bank.	boolean	`true`
Income Product	Configuration	Add the income product to the list of Plaid products to retrieve employment and income information.	boolean	`true`
Transactions Product	Configuration	Add the transactions product to the list of Plaid products to retrieve transaction data going back as far as 24 months.	boolean	`true`
Insights Success Message	Configuration	Update Insights about successful login using Plaid	text

Open Plaid Link Library: exchange.plaid Category: Plaid

Trigger the standard institution select view

Properties

Property	Category	Description	Type	Default
Plaid Link Reference	Configuration	The reference to the Plaid Link component	fieldRef	`plaidLink`

Plaid - Get Accounts v1

This service retrieves bank accounts data and balances.

Service Connection

Plaid

Compatibility

Module	Compatibility
Manager	5.0

Inputs

Name	Description	Required
publicToken	The public token that was generated after successful login using Plaid Link widget.	Yes

Outputs

Name	Description
accounts: account_id name official_name subtype type mask balances: available current limit	The results are provided as a JSON array. Account id is a unique ID of the account. Note: In some instances, account IDs may change. The name is the name of the Account, either assigned by the user or the financial institution itself. The official name is the name of the Account as given by the financial institution. Account types: depository (checking or savings accounts), credit (Credit card), loan (Loan account), mortgage (Mortgage account), brokerage (Brokerage account),other (Non-specified account type) The mask is the last four digits of the Account's number.
executionStatus	The status of the service execution [ `SUCCESS` \| `DATA_ERROR` \| `SYSTEM_ERROR` ]. Successful execution will be denoted by a `SUCCESS` value. `DATA_ERROR` will indicate that there was an issue identified with the input data that may be resolved and potentially retried by the user. `SYSTEM_ERROR` indicates that there was an unrecoverable system fault and the form should fall-back gracefully to an alternative path.
errorMessage	When a `DATA_ERROR` is experienced, this value may provide more detail on the nature of the error.

Plaid - Get Balance v1

This service retrieves the real-time balance for each of the bank accounts. he current balance is the total amount of funds in the account. The available balance is the current balance less any outstanding holds or debits that have not yet posted to the account. Note that not all institutions calculate the available balance. In the event that available balance is unavailable from the institution, Plaid will return an available balance value of null.

Service Connection

Plaid

Compatibility

Module	Compatibility
Manager	5.0

Inputs

Name	Description	Required
publicToken	The public token that was generated after successful login using Plaid Link widget.	Yes

Outputs

Name	Description
accounts: account_id name official_name subtype type mask balances: available current limit	The results are provided as a JSON array. Account id is a unique ID of the account. Note: In some instances, account IDs may change. The name is the name of the Account, either assigned by the user or the financial institution itself. The official name is the name of the Account as given by the financial institution. Account types: depository (checking or savings accounts), credit (Credit card), loan (Loan account), mortgage (Mortgage account), brokerage (Brokerage account),other (Non-specified account type) The mask is the last four digits of the Account's number.
executionStatus	The status of the service execution [ `SUCCESS` \| `DATA_ERROR` \| `SYSTEM_ERROR` ]. Successful execution will be denoted by a `SUCCESS` value. `DATA_ERROR` will indicate that there was an issue identified with the input data that may be resolved and potentially retried by the user. `SYSTEM_ERROR` indicates that there was an unrecoverable system fault and the form should fall-back gracefully to an alternative path.
errorMessage	When a `DATA_ERROR` is experienced, this value may provide more detail on the nature of the error.

Plaid - Get Identity v1

This service allows you to retrieve various account holder information with the financial institution, including names, emails, phone numbers, and addresses. Note: This request may take some time to complete if identity was not specified as an initial product when creating the Item. This is because Plaid must communicate directly with the institution to retrieve the data.

Service Connection

Plaid

Compatibility

Module	Compatibility
Manager	5.0

Inputs

Name	Description	Required
publicToken	The public token that was generated after successful login using Plaid Link widget.	Yes

Outputs

Name	Description
accounts: account_id name official_name subtype type balances: available current limit	The results are provided as a JSON array.
identity	an object of addresses, emails, names and phone_numbers.
addresses: primary data: city state street zip	The results are provided as a JSON array.
emails: primary data type	The results are provided as a JSON array.
names: name	The results are provided as a JSON array.
phones: primary data type	The results are provided as a JSON array.
executionStatus	The status of the service execution [ `SUCCESS` \| `DATA_ERROR` \| `SYSTEM_ERROR` ]. Successful execution will be denoted by a `SUCCESS` value. `DATA_ERROR` will indicate that there was an issue identified with the input data that may be resolved and potentially retried by the user. `SYSTEM_ERROR` indicates that there was an unrecoverable system fault and the form should fall-back gracefully to an alternative path.
errorMessage	When a `DATA_ERROR` is experienced, this value may provide more detail on the nature of the error.

Plaid - Get Income v1

This service allows you to retrieve income information. In addition to the annual income, detailed information will be provided for each contributing income stream (or job).

Service Connection

Plaid

Compatibility

Module	Compatibility
Manager	5.0

Inputs

Name	Description	Required
publicToken	The public token that was generated after successful login using Plaid Link widget.	Yes

Outputs

Name	Description
lastYearIncome	The sum of the Item’s income over the past 365 days. If we have less than 365 days of data this will be less than a full year's income.
lastYearIncomeBeforeTax	lastYearIncome interpolated to value before taxes. This is the minimum pre-tax salary that assumes a filing status of single with zero dependents
projectedYearlyIncome	Item’s income extrapolated over a year based on current, active income streams. Income streams become inactive if they have not recurred for more than two cycles. For example, if a weekly paycheck hasn’t been seen for the past two weeks, it is no longer active.
projectedYearlyIncomeBeforeTax	projectedYearlyIncome interpolated to value before taxes. This is the minimum pre-tax salary that assumes a filing status of single with zero dependents.
incomeStreams: confidence days monthly_income name	The results are provided as a JSON array of income streams. The confidence is a numeric representation of the confidence in the income data stream, with 0 being the lowest confidence and 1 being the highest.
maxNumberOfOverlappingIncomeStreams	Max number of income streams present at the same time over the past 365 days.
numberOfIncomeStreams	Total number of distinct income streams received over the past 365 days.
executionStatus	The status of the service execution [ `SUCCESS` \| `DATA_ERROR` \| `SYSTEM_ERROR` ]. Successful execution will be denoted by a `SUCCESS` value. `DATA_ERROR` will indicate that there was an issue identified with the input data that may be resolved and potentially retried by the user. `SYSTEM_ERROR` indicates that there was an unrecoverable system fault and the form should fall-back gracefully to an alternative path.
errorMessage	When a `DATA_ERROR` is experienced, this value may provide more detail on the nature of the error.

Plaid - Get Transactions v1

This service allows you to receive user-authorized transaction data for credit and depository-type Accounts. Transaction data is standardized across financial institutions, and in many cases transactions are linked to a clean name, entity type, location, and category.

Service Connection

Plaid

Compatibility

Module	Compatibility
Manager	5.0

Inputs

Name	Description	Required
publicToken	The public token that was generated after successful login using Plaid Link widget.	Yes
startDate	The start date. Dates should be formatted as	Yes
endDate	The end date. Dates should be formatted as YYYY-MM-DD	Yes

Outputs

Name	Description
transactions: account_id account_owner amount category_id date name pending pending_transaction_id transaction_id transaction_type category: [] location: address city lat lon state store_number zip payment_meta: by_order_of payee payer payment_method payment_processor ppd_id reason reference_number	The results are provided as a JSON array. Amount is the settled dollar value. Positive values when money moves out of the account; negative values when money moves in. For example, purchases are positive; credit card payments, direct deposits, refunds are negative. Pending - when true, identifies the transaction as pending or unsettled. Pending transaction details (name, type, amount) may change before they are settled. Date is the date that the transaction took place in ISO 8601 format (YYYY-MM-DD). Transaction type value is Place, Digital, Special, or Unresolved. Category is a hierarchical array of the categories to which this transaction belongs. for example `["Travel","Airlines and Aviation Services"]`
accounts: account_id name official_name subtype type balances: available current limit	The results are provided as a JSON array.
executionStatus	The status of the service execution [ `SUCCESS` \| `DATA_ERROR` \| `SYSTEM_ERROR` ]. Successful execution will be denoted by a `SUCCESS` value. `DATA_ERROR` will indicate that there was an issue identified with the input data that may be resolved and potentially retried by the user. `SYSTEM_ERROR` indicates that there was an unrecoverable system fault and the form should fall-back gracefully to an alternative path.
errorMessage	When a `DATA_ERROR` is experienced, this value may provide more detail on the nature of the error.

Plaid - Service Connection v1

This service is used by the Plaid Link widget to retrieve the Plaid public configuration environment and public key from the service connection.

Service Connection

Plaid

Compatibility

Module	Compatibility
Manager	5.0

Outputs

Name	Description
environment	The Plaid environment, sandbox, development or production
publicKey	The Plaid public key to initialize Plaid Link
executionStatus	The status of the service execution [ `SUCCESS` \| `DATA_ERROR` \| `SYSTEM_ERROR` ]. Successful execution will be denoted by a `SUCCESS` value. `DATA_ERROR` will indicate that there was an issue identified with the input data that may be resolved and potentially retried by the user. `SYSTEM_ERROR` indicates that there was an unrecoverable system fault and the form should fall-back gracefully to an alternative path.
errorMessage	When a `DATA_ERROR` is experienced, this value may provide more detail on the nature of the error.

The following service connections are used by this package.

Plaid

Property Name	Description	Required
Type	HTTP Endpoint	Yes
Endpoint	Must point to the Plaid API endpoint. For example: Prod Endpoint: `https://production.plaid.com` Sandbox Endpoint: `https://sandbox.plaid.com`	Yes
Username	Username The client id to access Plaid API.	Yes
Password	The secret key to access Plaid API.	Yes
Auth Key	Must contains the Plaid environment and Plaid public key. The public key is the identifier that is used to initialize Plaid Link. A valid value for the environment is: sandbox, development or production. The required format is `environment-public key`. For example: sandbox-8978335c9f87b3847ce5f7ee8856cc89a	Yes

Plaid v1.0

Licensing

Compatibility

Installation Instructions

Usage Instructions

Release Notes

Maestro Assets

Service Calls

Service Calls

Service Calls

Service Calls

Rule Templates

Properties

Properties

Services

Service Connection

Compatibility

Inputs

Outputs

Service Connection

Compatibility

Inputs

Outputs

Service Connection

Compatibility

Inputs

Outputs

Service Connection

Compatibility

Inputs

Outputs

Service Connection

Compatibility

Inputs

Outputs

Service Connection

Compatibility

Outputs

Service Connections