Plaid TAF v1.3
This package provides capabilities that extend the Avoka Transact platform for users wishing to include Plaid services in their forms.
Plaid product supported is Plaid product - Auth | ACH authentication (account and routing numbers)
Plaid Auth let’s you instantly authenticate Bank account for ACH and EFT payments. It easy to set up ACH transfers from any bank or credit union in the U.S. Once a user links their account via their banking credentials, Plaid retrieves their account and routing numbers. ACH payments can be set up in moment.
Package features Includes:
- Define relevant Account types – Store only what you need!
- Don’t risk storing unnecessary sensitive information or miss out on account types which could contribute to your onboarding application.
- This feature allows you to define the relevant accounts required.
- It also allows you to adjust the set up for your application while maintaining one , original Exchange service under the same organization.
- It’s also possible to store only the ACH accounts if that’s all needed.
- Insight Milestones and segmentation – Evaluate the quality of the service
- This package includes Pre-built segments and Milestones to assist you to evaluate the quality of the service that’s part of your application.
- Use insights to get a clear visual view of the number of applicants who started and successfully linked their bank account details from Plaid. From those who didn’t, you will be able to easily see at which stage they stopped, if it was by choice or an error?
- This feature lets you evaluate the quality of the service and make better and informed decisions about the user journey in your application.
- Added Language support
- Plaid provides services in US and Canada.
- English and French are supported.
Licensing
Clients must ensure they are appropriately licensed in order to use this package. Organisations who wish to use this package are required to establish a commercial relationship with the 3rd party vendor directly.
Compatibility
This package has the following compatibility requirements:
| Module | Compatibility | Notes |
|---|---|---|
| Journey Manager | 17.10.9 or above | |
| Journey Maestro | 18.05.7 or above | |
| Narration Controller | 1.4.3 or above | |
| Narrator Component | latest with support of form actions | |
| TIF version | 1.6.1 or above | |
| Configuration Service | 1.1.0 or above |
Release Notes
Version 1.3 Mar 8, 2022
- Migrate from the public key to a Link token, to support OAuth.
Version 1.2 March 20, 2020
- Configuration service support.
- Added support for disabling milestone events optionally.
- Use Narrator form action.
Version 1.1 Aug 20, 2019
- Defect fix: Browser install/uninstall issue related to a Plaid package version.
- Defect fix: Dependency issue with Plaid VO when it was used by Maven.
Version 1.0 Apr 24, 2019
- Baseline release.
Installation
Exchange Installation
This package should be installed as a single archive via the Avoka Exchange. Once installed you should walk through the following procedure to ensure you complete any required configuration:
- Review the documentation below for each of the imported services and make any adjustments necessary to service parameters.
- Review the documentation below for any Service Connections and add your credentials as required.
- Review the Help Doc tab for each of the imported services and make any required adjustments to service parameters.
- Review the Service Connection requirements under the same Help Doc tab for each of the imported services and make any required configurations to the Service Connection. Service Connections can be configured in Transact Manager under the Services >> Service Connections menu item.
- Installation of any included Maestro libraries requires you to login to you Maestro server and import them either into your organization (for global availability) or to your specific project.
Maven dependency
pom.xml as below in order to import and consume Plaid result through Plaid VO this package provides.
Form action in Narrator
This package uses form action to trigger the Plaid Auth fluent function. Please make sure you have configured the form action accordingly in your form narrative.Below is the example on how to create form actions in Form Narrative on the server.
{
"name": "Plaid Example Application Narrative",
"version": "1.0.0",
"pages": [
{
"name": "GetStarted",
"preActions": [],
"postActions": [],
"formActions": [
{
"name": "Plaid - Auth",
"version": "1.3.0",
"params": {
}
}
],
"nextPages": [
"Success"
]
}
...
]
}
Note: You need latest version of both Narration controller and Narrator Maestro library to support form action feature this package is relying on. Please contact Narrator team to get the correct version.
High Level Diagram
Below are the process flow diagrams for Plaid Auth. This gives an insight into the design of the components.Plaid Auth
Configure Plaid
Use the following procedure to configure Plaid Link in Maestro:
- The form must be saved prior opening Plaid Link as it records the result accounts in the form XML. This should be done for you when you use any Narrator form template.
- From the Maestro palette add button called Plaid Link Button to your form.
- Select the Plaid Link Button component and from the Properties tab select the Configuration section. Review the default service configuration ( Plaid Svc Name ) and make sure it matches the service you use. Also set your Your Bank/Institution Name and Language if other than English.
-
In the Rules section, add any processing rules to handle
On SuccessandOn Failureevents. - From the Maestro palette add component called Plaid Account Selector to your form.
- Select the Plaid Account Selector component and from the Properties tab select the Configuration section. Make sure the default Accounts Field is mapped to the correct account data field from the Plaid Link Button component. Also you can map the selected account fields to actual fields on your form by using the Output Fields field.
CSP Configuration
The Content Security Policy (CSP) response header helps you reduce XSS risks on modern browsers by declaring what dynamic resources are allowed to load via a HTTP Header, thereby protecting your solution from a range of vulnerability attacks.
By default, Avoka Transact has strict CSP settings configured so these will likely need to be modified in order to enable the Plaid Link integration.
You can configure CSP settings in Transact Manager at a system wide level via the 'Form Submission Access Controller' service, or at an Organization level in the Security tab. The following Sample CSP demonstrates how to enable the Plaid Link integration:
script-src 'self' https://cdn.plaid.com; object-src 'none';
For more information see CSP on The Avoka Community
Notes / Warnings
Note: Each service within this package must have Unified App Data enabled when building a form. Navigate to Forms > Form > Form Version and tick the Unified App Data checkbox.
Insights
Milestone events
Milestone events are automatically generated to show milestones on the User Journey view in Transact Insights, the Transact platform analytics tool.
| Name | Trigger |
|---|---|
| Plaid Auth Start | On receiving a Plaid Auth request. |
| Plaid Auth Account Retrieved | When Plaid Auth completed and accounts are retrieved. |
Note: You can optionally turn off all milestones inside the Exchange services by setting the service parameter: disableMilestones to true if you prefer
a simplified diagram in Journey Analytics.
Segment events
Segment events are automatically generated to show segments on the User Journey view in Transact Insights, the Transact platform analytics tool.
Note: Please make sure you've added the following segment name and valid values to Insights segment whitelist before using this component. For more information, please refer to Insights Preferences
| Name | Value | Trigger |
|---|---|---|
| Plaid Auth | Click | When initiate Plaid button clicked. |
| Plaid Auth | Open | When Plaid Link window is opened. |
| Plaid Auth | Exit | When Plaid Link window is closed by the user. |
| Plaid Auth | Submit | When the user submit his bank account credentials. |
| Plaid Auth | Complete | When the user press the continue button and Plaid Link work is done. |
Service Txn properties/ Server VO
The table below describes Plaid Auth server VO fields stored in the Form XML Data and also stored in transaction properties.
| Name | Description | Format | Notes |
|---|---|---|---|
| Plaid.Auth.Result.ExecutionStatus | The status of the service execution with possible values: [ SUCCESS | SYSTEM_ERROR ] | String | |
| Plaid.Auth.Result.Accounts.Account.AccountId | Unique ID of the account. | String | |
| Plaid.Auth.Result.Accounts.Account.Mask | The last four digits of the Account's number. | String | |
| Plaid.Auth.Result.Accounts.Account.Name | The name of the Account, either assigned by the user or the financial institution itself. | String | |
| Plaid.Auth.Result.Accounts.Account.OfficialName | The name of the Account as given by the financial institution. | String | |
| Plaid.Auth.Result.Accounts.Account.Type | The account type: depository (Checking or savings accounts), credit (Credit card), loan (Loan account), brokerage (Brokerage account),other (Non-specified account type). | String | |
| Plaid.Auth.Result.Accounts.Account.Subtype | The account subtypes. | String | |
| Plaid.Auth.Result.Accounts.Account.Label | The account label. | String | |
| Plaid.Auth.Result.Accounts.Account.Balances.Available | The amount of funds available to be withdrawn from an account, as determined by the financial institution. | String | |
| Plaid.Auth.Result.Accounts.Account.Balances.Current | The total amount of funds in the account. | String | |
| Plaid.Auth.Result.Accounts.Account.Balances.Limit | The limit for the account, primarily populated for credit-type accounts. | String | |
| Plaid.Auth.Result.Accounts.Account.Numbers.AccountId | The Plaid account ID associated with the account numbers. | String | |
| Plaid.Auth.Result.Accounts.Account.Numbers.Account | The ACH account number for the account. | String | |
| Plaid.Auth.Result.Accounts.Account.Numbers.Routing | The ACH routing number for the account. | String | |
| Plaid.Auth.Result.Accounts.Account.Numbers.WireRouting | The ACH wire routing number for the account, if available. | String | |
| Plaid.Auth.Result.ErrorCode | Error code | String | When a SYSTEM_ERROR is experienced, this value provides the error code. |
| Plaid.Auth.Result.ErrorMessage | Error Message | String | When a SYSTEM_ERROR is experienced, this value may provide more detail on the nature of the error. |
| Plaid.Auth.Result.RawResponse | Raw response | String | Optional field controlled by the connection property flag recordResponseInTxnXML to store raw response in server VO |
Configuration Service Support
This package supports the configuration service. Please make sure you follow the instruction below to setup your configuration service correctly.Create a service parameter keyMapping as below in your configuration service (service-def.json) if you haven't done so
{
"name": "keyMapping",
"type": "String",
"filePath": "json/keyMapping.json",
"bind": false,
"required": false,
"clearOnExport": false,
"readOnly": false
},
Note: You only need to create keyMapping service parameter once when you setup your first Exchange package. The rest of the Exchange package will just be keep adding content into the existing service parameter.
Create or append the following content into json/keyMapping.json
"plaid": [
{
"serviceKey": "auth",
"serviceName": "Plaid - Auth",
"serviceParamKeyMap": {
"recResInXml": "recordResponseInTxnXML",
"recResInProp": "recordResponseInTxnProperties"
}
}
]
Copy the following service parameters definition in your configuration service (service-def.json) and set the proper values for your project.
{
"name": "plaid-auth|1.3.0-conn.endpoint",
"description": "Service connection Endpoint for plaid auth service",
"value": "https://sandbox.plaid.com",
"type": "String",
"bind": false,
"required": true,
"clearOnExport": false,
"readOnly": false
},
{
"name": "plaid-auth|1.3.0-conn.username",
"description": "Service connection Username for plaid auth service",
"value": "58b0fcdebdc6a44288ea2018",
"type": "String",
"bind": false,
"required": true,
"clearOnExport": false,
"readOnly": false
},
{
"name": "plaid-auth|1.3.0-conn.password",
"description": "Service connection password for plaid auth service",
"value": "9d08325a1eba770867d269de84f4a1",
"type": "Password",
"bind": false,
"required": true,
"clearOnExport": false,
"readOnly": false
},
{
"name": "plaid-auth|1.3.0-conn.param1",
"description": "Service connection auth key for plaid auth service",
"value": "sandbox-8315c9f87b3847ce5f7ee88565b412",
"type": "Password",
"bind": false,
"required": true,
"clearOnExport": false,
"readOnly": false
},
{
"name": "plaid-auth|1.3.0-accountTypes",
"description": "A list of account types which are relevant to be used and stored. A comma-separated list of account types with the following possible values: brokerage,credit,depository,loan,other.",
"value": "depository,credit",
"type": "String",
"bind": false,
"required": false,
"clearOnExport": false,
"readOnly": false
},
{
"name": "plaid-auth|1.3.0-environment",
"description": "Plaid API Environment. must be \\u0027sandbox\\u0027, \\u0027development\\u0027 or \\u0027production\\u0027.",
"value": "sandbox",
"type": "String",
"bind": false,
"required": false,
"clearOnExport": false,
"readOnly": false
},
{
"name": "plaid-auth|1.3.0-depositoryAchOnly",
"description": "Use and store only depository accounts (Saving / cheque) with ACH option only. If true, then \\u0027accountTypes\\u0027 field should be empty.",
"value": "false",
"type": "Boolean",
"bind": false,
"required": false,
"clearOnExport": false,
"readOnly": false
},
{
"name": "plaid-auth|1.3.0-disableMilestones",
"description": "Whether to disable Journey Analytics milestones for this service.",
"value": "false",
"type": "Boolean",
"bind": false,
"required": false,
"clearOnExport": false,
"readOnly": false
},
{
"name": "plaid-auth|1.3.0-recResInProp",
"description": "",
"value": "true",
"type": "Boolean",
"bind": false,
"required": false,
"clearOnExport": false,
"readOnly": false
},
{
"name": "plaid-auth|1.3.0-recResInXml",
"description": "",
"value": "true",
"type": "Boolean",
"bind": false,
"required": false,
"clearOnExport": false,
"readOnly": false
}
Note: Once you setup your application to use configuration service, all the service connection and service parameters data directly comes from the your configuration service. So there is no need to setup the original service connection or service parameter of the Exchange fluent function.
Enable/Disable the configuration service
In order to enable the configuration service in your application, please define the following organisation properties in your organisationConfigServiceName.
This is to define which configuration service you would like to use in your organisation. For example, if you decide to trigger BankwestServiceConfiguration as the configuration service, set the following organisation property.
ConfigServiceName=MyCompanyServiceConfiguration
Note: Configuration service is an organisation level option. Once enabled, all Exchange services within the organisation will start retrieving the service connection and service parameters info from configuration service you specified above.
You can simply delete the organisation propertyConfigServiceName to disable the configuration service in your organisation.Maestro Assets
Allow applicant's to select an account retrieved from Plaid
Properties
| Property | Category | Description | Type | Default |
|---|---|---|---|---|
| Accounts Field | Configuration | Field containing results of PlaidLink and account retrieval | fieldRef |
data.accounts_account
|
| Output Fields | Configuration | Map the selected account fields to actual fields or your form.
Field Refs:
|
fieldRefMap |
Services
Service Connection
Compatibility
| Module | Compatibility |
|---|---|
| Manager | 17.10.9 |
Service Parameters
| Name | Description | Required | Default |
|---|---|---|---|
| configServiceAppName | AppName for configuration service. All exchange services use vendor code for AppName. | Yes |
plaid
|
| disableMilestones | Whether to disable Journey Analytics milestones for this service. | No |
false
|
| recordResponseInTxnProperties | Record response as txn property. | No |
false
|
| recordResponseInTxnXML | Record response in Plaid server VO and persisted in Txn XML. | No |
false
|
| accountTypes | A list of account types which are relevant to be used and stored. A comma-separated list of account types with the following possible values: brokerage,credit,depository,loan,other. | No |
|
| environment | Plaid API Environment. must be 'sandbox', 'development' or 'production'. | Yes |
sandbox
|
| depositoryAchOnly | Use and store only depository accounts (Saving / cheque) with ACH option only. If true, then 'accountTypes' field should be empty. | No |
false
|
| redirectUri | The OAuth redirect flow requires your system OAUth endpoint, it's usually a blank page that initiate Plaid second time and redirect you back to your original page. | No |
https://exchange.avoka-transact.com/web-plugin/oauth-page.html
|
| clientName | To create the link token we need the client name other we use txn.clientCode. | No |
|
Inputs
| Name | Description | Required |
|---|---|---|
| RequestType | When the request type is set to 'environment' the service will just return the plaid token and the environment. | No |
| PublicToken | The public token that was generated after successful login using Plaid Link widget. It's mandatory when AccessToken wasn't provided and RequestType 'environment' wasn't provided. | No |
| AccessToken | The access token that was exchanged from the public token. This can be useful for testing. It's mandatory when PublicToken wasn't provided and RequestType 'environment' wasn't provided. | No |
| ApplicantRole | The Applicant role is used to distinguish different applicant’s requests in the same session. | No |
| DepositoryAchOnly | Use and store only depository accounts (Saving / cheque) with ACH option only. If true, then 'accountTypes' field should be empty. | No |
| AccountTypes | A list of account types which are relevant to be used and stored. A comma-separated list of account types with the following possible values: brokerage,credit,depository,loan,other. |
No |
Outputs
| Name | Description |
|---|---|
| data.executionStatus | The status of the service execution [ SUCCESS | SYSTEM_ERROR ]. Successful execution will be denoted by a |
| formStatus | Form status |
Service Connections
The following service connections are used by this package.
| Property Name | Description | Required |
|---|---|---|
| Type | HTTP Endpoint | Yes |
| Endpoint |
Plaid web service end point. For example: Prod Endpoint: https://production.plaid.comSandbox Endpoint: https://sandbox.plaid.comMake sure you change to the correct URL on production before using this service. |
Yes |
| Username | The client id to access Plaid API. | Yes |
| Password | The secret key to access Plaid API. | Yes |