ClickSWITCH v1.0

This package provides capabilities that extend the Avoka Transact platform with integration to the ClickSWITCH account switching solution. ClickSWITCH switches account holders recurring payments from their old accounts to new ones.

To support creating new ClickSWITCH customers, this package provides the following Maestro component:

  1. ClickSWITCH Enroll Customer
    This component is a single dynamic data button that calls the ClickSwitch - Enroll Customer service, to enroll new ClickSWITCH customer.

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 the 3rd party 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:

  1. Unzip the package to a directory on your computer
  2. Import each zip archive found in the services folder to Transact Manager under the Services >> All Services menu item.
  3. Open the ClickSWITCH - Enroll Customer service and configure the Institution ID as provided by ClickSWITCH.
  4. Review the Help Doc tab for each of the imported services and make any required adjustments to service parameters.
  5. 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.

  6. 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

Ideally the ClickSWITCH process should be presented on the Submission Confirmation modal page that is presented following a successful product application. The ClickSWITCH integration is a 2 step process:

  1. Opt In: The option to use the ClickSWITCH service is presented to the customer. The ClickSWITCH Enroll Customer button provided can be used as the opt in button. When the button is fired, the customer data is sent to ClickSWITCH and their account details are configured. A unique reference code is provided for use in the next step.
  2. Launch ClickSWITCH: Upon a successful enrolment, the customer may be presented with instructions on how to login to the ClickSWITCH Portal. The ClickSWITCH Reference Code and Portal URL (both returned from the customer enrolment service) will be required to achieve this. E.g.:

    Your ClickSWITCH account is ready! Just click the login link, enter your reference code and follow the instructions.

    ClickSWITCH Login
    Your reference code is UIBVEX6S

To configure the ClickSWITCH Enroll Customer component, please walk through the following procedure:

  1. Open your form in Maestro and drag and drop the field called ClickSWITCH Enroll Customer from the Palette.
  2. On the Properties tab of the field under Configuration section, click on Input Field Mapping to map your form's fields to the matching request keys.

    Please note - You must map all the mandatory fields as defined in the Inputs for the customer enrolment service.

    The service also supports multiple accounts by providing comma separated values in the Account input fields. For example, to pass multiple account numbers from a repeat you could use a data field with a script similar to this:

        var arrAccountNumber = Form.getRepeatData("Form.data.accountRepeat.accountNumber", data);
        if (arrAccountNumber !== undefined ) {
          return arrAccountNumber.join();
        }
  3. On the Properties tab of the field under Configuration section, click on Response Field Mapping to map the response fields switchTrackCode, portalUrl, executionStatus and errorMessage to data fields on your form. Use these values in the instructions you provide to the customer for launching the ClickSWITCH Portal.

This is provided to support use of ClickSWITCH test environments in non-production usage scenarios. The URLs can be configured in the service parameters.

Release Notes

Version 1.0 May 31, 2017

  • Baseline release.

Maestro Assets

ClickSWITCH Enroll Customer Library: exchange.clickswitch Category: clickswitch

A dynamic data button to enroll new ClickSWITCH customer.

Service Calls

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 the dynamic data call, the parameter info contains the response
  • On Failure : a script to run on failure of the dynamic data call, the parameter info contains the response

Services

ClickSwitch - Enroll Customer v1
This service enrolls a new customer to ClickSWITCH service.

Service Connection

Compatibility

Module Compatibility
Manager 5.0

Service Parameters

Name Description Required Default
clickSwitchPortalUrls JSON array structure that contains the service endpoint, portal URL and portal name. It's used for finding the correct portal URL (Prod, Demo..) by comparing the service endpoint. Yes [{"name": "DEMO","endpoint": "https://clickswitch.azure-api.net/api_demo","portal":"https://avoka.clickswitchdemo.com/Account/Login"},{"name": "PROD","endpoint": "https://clickswitch.azure-api.net/api_prod","portal": "https://avoka.clickswitch.com/Account/Login"}]

Inputs

Name Description Required
Customer details: Yes
emailAddress The email address for the customer primary contact. This will also be used as the UserName for the new customer. Yes
firstName First name for customer primary contact. Yes
lastName Last name for customer primary contact. Yes
middleName Middle name/initial for customer primary contact. No
businessName If the customer is a business, supply business name. No
phoneNumber The phone number of the customer primary contact. Yes
Address: Yes
addressLine1 Customer address line 1. Yes
addressLine2 Customer address line 2. No
city Customer address city. Yes
stateProvinceCode Customer state or province. Yes
postalCode Customer address zip/postal code. Yes
countryCode Customer address country code (use "US", "USA", "CA" or "CAN"). The default would be "US" No
Accounts: Yes
accountTypeId The account type id.
This field uses comma separated string in order to specify multiple accounts for the customer.
Valid values are: 1 for checking account, 2 for savings account, for Example: 1,2
The accountTypeId or the accountType must be provided to determine account type.
Yes
accountType Name of institution account in ClickSWITCH. This field uses comma separated string in order to specify multiple accounts for the customer. For Example: Checking,Savings
The accountTypeId or the accountType must be provided to determine account type.
Yes
accountNumber The account number.
This field uses comma separated string in order to specify multiple accounts for the customer. For Example: 111222333,111222444
Yes
branchId The id of the branch in ClickSWITCH to assign to the new account. This field uses comma separated string in order to specify multiple accounts for the customer. For Example: 2063,2063
The branchId or the externalBranchId must be provided to determine the branch.
Yes
externalBranchId The id used by the institution within ClickSWITCH to identity a branch. This field uses comma separated string in order to specify multiple accounts for the customer. For Example: 2063,2063
The branchId or the externalBranchId must be provided to determine the branch.
Yes

Outputs

Name Description
switchTrackCode The customer switch tracking code. The customer can enter this code in ClickSWITCH portal to create new login.
portalUrl The ClickSWITCH portal URL. This URL can be different for DEMO/PROD environments and it returns from the JSON service parameter called clickSwitchPortalUrls by matching the service endpoint.
portalName The ClickSWITCH portal name. This name describe the environment (DEMO, PROD) and it returns from the JSON service parameter called clickSwitchPortalUrls by matching the service endpoint.
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.

Service Connections

The following service connections are used by this package.

ClickSwitch
Property Name Description Required
Type HTTP Endpoint Yes
Endpoint Must point to the ClickSWITCH API endpoint. For example:

Demo Endpoint: https://clickswitch.azure-api.net/api_demo
Prod Endpoint: https://clickswitch.azure-api.net/api_prod

Yes
Auth Key Must contain your API User Key and Subscription Key separated by comma. The API User Key is provided by ClickSWITCH. And the Subscription Key can be found in your ClickSWITCH Profile
The expected format is: {{APIUserKey}},{{AzureSubscriptionKey}}
Yes
Username Username is the your institution id as provided by ClickSWITCH Yes