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:

  1. Define relevant Account types – Store only what you need!
    1. Don’t risk storing unnecessary sensitive information or miss out on account types which could contribute to your onboarding application.
    2. This feature allows you to define the relevant accounts required.
    3. It also allows you to adjust the set up for your application while maintaining one , original Exchange service under the same organization.
    4. It’s also possible to store only the ACH accounts if that’s all needed.
  1. Insight Milestones and segmentation – Evaluate the quality of the service
    1. This package includes Pre-built segments and Milestones to assist you to evaluate the quality of the service that’s part of your application.
    2. 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?
    3. This feature lets you evaluate the quality of the service and make better and informed decisions about the user journey in your application.
  1. Added Language support
    1. Plaid provides services in US and Canada.
    2. 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:

ModuleCompatibilityNotes
Journey Manager17.10.9 or above
Journey Maestro18.05.7 or above
Narration Controller1.4.3 or above
Narrator Componentlatest with support of form actions
TIF version1.6.1 or above
Configuration Service1.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:

  1. Review the documentation below for each of the imported services and make any adjustments necessary to service parameters.
  2. Review the documentation below for any Service Connections and add your credentials as required.
  3. Review the Help Doc tab for each of the imported services and make any required adjustments to service parameters.
  4. 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.
  5. 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

  • In your maven project, add the following dependencies in 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 Success and On Failure events.
    • 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.

    NameTrigger
    Plaid Auth StartOn receiving a Plaid Auth request.
    Plaid Auth Account RetrievedWhen 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

    NameValueTrigger
    Plaid AuthClickWhen initiate Plaid button clicked.
    Plaid AuthOpenWhen Plaid Link window is opened.
    Plaid AuthExitWhen Plaid Link window is closed by the user.
    Plaid AuthSubmitWhen the user submit his bank account credentials.
    Plaid AuthCompleteWhen 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.

    NameDescriptionFormatNotes
    Plaid.Auth.Result.ExecutionStatusThe status of the service execution with possible values: [ SUCCESS | SYSTEM_ERROR ]String
    Plaid.Auth.Result.Accounts.Account.AccountIdUnique ID of the account.String
    Plaid.Auth.Result.Accounts.Account.MaskThe last four digits of the Account's number.String
    Plaid.Auth.Result.Accounts.Account.NameThe name of the Account, either assigned by the user or the financial institution itself.String
    Plaid.Auth.Result.Accounts.Account.OfficialNameThe name of the Account as given by the financial institution.String
    Plaid.Auth.Result.Accounts.Account.TypeThe 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.SubtypeThe account subtypes.String
    Plaid.Auth.Result.Accounts.Account.LabelThe account label.String
    Plaid.Auth.Result.Accounts.Account.Balances.AvailableThe amount of funds available to be withdrawn from an account, as determined by the financial institution.String
    Plaid.Auth.Result.Accounts.Account.Balances.CurrentThe total amount of funds in the account.String
    Plaid.Auth.Result.Accounts.Account.Balances.LimitThe limit for the account, primarily populated for credit-type accounts.String
    Plaid.Auth.Result.Accounts.Account.Numbers.AccountIdThe Plaid account ID associated with the account numbers.String
    Plaid.Auth.Result.Accounts.Account.Numbers.AccountThe ACH account number for the account.String
    Plaid.Auth.Result.Accounts.Account.Numbers.RoutingThe ACH routing number for the account.String
    Plaid.Auth.Result.Accounts.Account.Numbers.WireRoutingThe ACH wire routing number for the account, if available.String
    Plaid.Auth.Result.ErrorCodeError code String When a SYSTEM_ERROR is experienced, this value provides the error code.
    Plaid.Auth.Result.ErrorMessageError MessageStringWhen a SYSTEM_ERROR is experienced, this value may provide more detail on the nature of the error.
    Plaid.Auth.Result.RawResponseRaw responseStringOptional 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 organisation ConfigServiceName. 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 property ConfigServiceName to disable the configuration service in your organisation.

    Maestro Assets

    Plaid Account Selector Library: exchange-plaid-ach-taf Category: Plaid

    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:

    • routingNum : Routing Number
    • accountNum : Account Number
    • availableBal : Available Balance
    • currentBal : Current Balance
    • accountType : Account Type
    • accountName : Account Name
    • accountOfficialName : Official Name

    You may add your own field mappings as required.

    fieldRefMap

    Services

    Plaid - Auth v1.3.0
    Provides Plaid Get Accounts service.

    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 SUCCESS value. SYSTEM_ERROR indicates that there was an unrecoverable system fault and the form should fall-back gracefully to an alternative path.

    formStatus Form status

    Service Connections

    The following service connections are used by this package.

    Plaid
    Property Name Description Required
    Type HTTP Endpoint Yes
    Endpoint Plaid web service end point. For example:

    Prod Endpoint: https://production.plaid.com
    Sandbox Endpoint: https://sandbox.plaid.com
    Make 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