How it works

Connector UI

The connector URL is a URL you can host on your website or send by email. No specific integration is required to let your clients link their cards. This connector UI is used if your use case is just aggregation. If you want to use aggregation with payments, this is a different flow, and you need to use the Url from the portal under Integration Codes >> Add Payment Profile.

An example URL looks like this:

• Production: https://connector.aggregation.zumrails.com/?customerid=<YOUR-CUSTOMER-ID>.

• Sandbox: https://connector-sandbox.aggregation.zumrails.com/?customerid=<YOUR-CUSTOMER-ID>.

Event listener

Every interaction with the UI triggers a JavaScript event listener that your host page can listen to. Each message has a step, as described below.

Add the event listener on your website

<script>
  window.addEventListener("message", function (e) {
    console.log(e.data)
  })
</script>

Example message:

{
  step: "INSTITUTIONSELECTED"
  data: {
    institution: "Zum Rails Test Bank"
  }
}

Steps that can be listened:

Step	Description
CONNECTORLOADED	When the Connector is loaded
CONNECTORCLOSED	When the Connector is closed
CONSENTACCEPTED	When the consent was accepted
INSTITUTIONSELECTED	When an institution is selected
AUTHENTICATEINITIATED	When we start authenticating the connection
ACCOUNTSELECTORFOOTERCLICKED	When the link on the instution selection footer is clicked
SECURITYQUESTIONPROMPTED	When a security question is prompted
SECURITYQUESTIONANSWERINITIATED	When the security question is answered, and we resume the authentication
AUTHENTICATECOMPLETED	When authentication is completed
GETINFORMATIONINITIATED	When the get card information process starts
GETINFORMATIONCOMPLETED	When the get card information process completes
CONNECTIONSUCCESSFULLYCOMPLETED	When the process is completed. The property data will contain up to 5 fields that can be used to link the user from your system with the aggregation. Example: { requestid: 'asdf...asdf', cardid: 'asdf...asdf', extrafield1: '', extrafield2: '', userid: 'asdf...asdf' }
GENERICERROR	When an unexpected error occurs

Connector SDK

The javascript SDK library allows you to build a more robust integration with the Zūm Rails Connector. Instead of hosting a public URL, the library enables you to create a temporary token, initiate and configure the Connector via Javascript and finally receive callbacks when the connection is completed.

Steps to follow to complete your integration:

1. Call Zūm Rails API to create a Connector Token

2. Refer the javascript SDK library to your website, build your configuration options and init the SDK

3. Handle the callbacks

4. Go Live

Create a token

To create a token, you must first authenticate in Zūm Rails API. More information can be found here

The second step is to create a token for the Connector SDK.

Method: POST

Endpoint: {{env}}/api/aggregationconnector/createtoken

Response

{
  "statusCode": 200,
  "message": "POST Request successful.",
  "isError": false,
  "result": {
    "Token": "production-75c90e75e76c49f5a3ae4504afc8cfc5",
    "ExpirationUTC": "2022-02-17T22:33:44.9490972Z",
    "CustomerId": "a3510efb-5edb-4972-96be-a5a91ddfa56a",
    "CompanyName": "Demo Aggregation"
  }
}

You will need to use the property result.Token.

Each token is valid only once, for 15 minutes.

Install JS SDK

Refer to the JS library below to integrate it into your website. Use one URL for sandbox, and another for production.

Sandbox

<script
  id="zumrailsconnector"
  src="https://cdn.aggregation.zumrails.com/sandbox/connector.js"
  type="text/javascript"
  async=""
></script>

Production

<script
  id="zumrailsconnector"
  src="https://cdn.aggregation.zumrails.com/production/connector.js"
  type="text/javascript"
  async=""
></script>

Init the JS SDK

The library expects 2 mandatory parameters:

Parameter	Description
token	The token received in the endpoint {{env}}/api/aggregationconnector/createtoken
config	A JSON config representing all the configurations available and described here

Below is an example of the code needed to init the JS SDK.

JS SDK Code

<button class="mt-5" type="button" id="btnGoConnect">Call aggregation</button>
<script>
  $(function () {
    $("#btnGoConnect").click(function () {
      const token = "<THE TOKEN RECEIVED IN THE CREATE TOKEN ENDPOINT>"

      ZumRailsConnector.init({
        token: token,
        options: {
          accountselector: true,
          testinstitution: true,
          backbutton: true,
          closebutton: true,
          extrafield1: "<my-extra-data>",
        },
        onLoad: function () {
          console.log("onLoad")
        },
        onError: function (error) {
          console.log("onError", error)
        },
        onSuccess: function (
          requestid,
          cardid,
          extrafield1,
          extrafield2,
          userid,
          clientuserid,
        ) {
          console.log(
            "onSuccess",
            requestid,
            cardid,
            extrafield1,
            extrafield2,
            userid,
            clientuserid  
          )
        },
        onStepChanged: function (data) {
          console.log("onStepChanged", data)
        },
        onConnectorClosed: function () {
          console.log("onConnectorClosed")
        },
      })
    })
  })
</script>

In the example above, it will be needed to add jQuery reference. Second, in order to trigger the aggregation flow is expected to define a button with id btnGoConnect

<button class="mt-5" type="button" id="btnGoConnect">Call aggregation</button>

We recommend you use the Configure page to build the options property.

Callbacks

When something happens, the SDK library will fire a few callbacks, allowing you to get the data and take immediate action quickly. For example, call the endpoint to get the full card information onSuccess by passing the requestId or cardId

onLoad

This callback is triggered when the UI is loaded and presented on the screen.

Parameters

• There are no parameters in this callback

onConnectorClosed#

This callback is triggered when the end user clicks the X button to close the Connector

Parameters

• There are no parameters in this callback

onError

This callback is triggered when the connection fails by any error not expected in the happy flow.

Parameters

• error: An error message explaining the reason why the failure happened

onSuccess

This callback is triggered when the connection is completed, and the card was successfully linked

Parameters

• requestid: The id of the request, unique per attempt

• cardid: The id of the card, unique per card, and institution number. If you connect the same card 2 times, the cardid will keep being the same

• extrafield1: The extra field 1 informed when the library was initiated

• extrafield2: The extra field 2 informed when the library was initiated

• userid: The id of the user added in Zūm Rails Portal if parameter adduserinportal is set to true

• clientuserid: Your internal user id for user added in Zūm Rails Portal if parameter adduserinportal is set to true and clientuserid is informed

onStepChanged

This callback is triggered when there is a page change, or an action was taken by the end-user

Parameters

• data: A json object with this format { step: <STEP>, data: {EXTRA DATA}}

A list of steps can be found here:

Parameter	Description
CONNECTORLOADED	When the Connector is loaded
CONNECTORCLOSED	When the Connector is closed
CONSENTACCEPTED	When the consent was accepted
INSTITUTIONSELECTED	When an institution is selected
AUTHENTICATEINITIATED	When we start authenticating the connection
ACCOUNTSELECTORFOOTERCLICKED	When the link on the instution selection footer is clicked
SECURITYQUESTIONPROMPTED	When a security question is prompted
SECURITYQUESTIONANSWERINITIATED	When the security question is answered, and we resume the authentication
AUTHENTICATECOMPLETED	When authentication is completed
GETINFORMATIONINITIATED	When the get card information process starts
GETINFORMATIONCOMPLETED	When the get card information process completes
CONNECTIONSUCCESSFULLYCOMPLETED	When the process is completed
GENERICERROR	When an unexpected error occurs

Reconnect

Aggregation Reconnect will help you to refresh your users bank accounts in a secure and intuitive way. You can use this to refresh the banking information of your users that were connected using aggregation.

You just need to inform the CardId that you want to reconnect using the Zūm SDK/URL and it will trigger the reconnect flow.

To reconnect a card, the username linked to the CardId has to be the same. In case the username has changed, the card cannot be reconnected.

Here is how Reconnect will work:

1. User has successfully connected a bank account using Zūm Aggregation.

2. Zūm returns a CardID for the user’s bank account that was connected.

3. Trigger the Reconnect URL/SDK flow specifying the cardID.

4. Zūm will retrieve the username and the bank account associated with the CardID

5. User reconnects successfully and callbacks are returned. Once reconnected, you can access the data collected for that particular bank account via the Zūm API.

Ways to integrate

There is one way of using Zūm Rails Aggregation Reconnect:

1. Connector SDK

To use the reconnect feature you will take advantage of our secure Javascript SDK. This will be mandatory because of it's added security when updating existing users through aggregation.

Connector SDK

In order to reconnect a user’s card using the Connector SDK use the same payload specified here to generate the token and build the configuration. You need to specify the option cardidforreconnect with the value of the CardId that need to be reconnected. Check the example bellow

options: {
  cardidforreconnect: "<CardId value>"
}

To activate this feature for your account, please reach out to us at [e-mail] or using the chat function in the portal.

Only users added after this feature is activated will be able to reconnect their bank accounts.

Access the data

After a card is linked using the Connect UI or Connect SDK, the data can be available to you in different ways, as listed below:

Access the data in Zūm Rails portal

For every new connection made for a specific card, a new user will automatically be created in the Zūm Rails portal. You can search it under the User page by the user name or email. In this option, zero integration is required, but it's a bit difficult to match the user since the name on the bank account might be different than the name you have in your file.

Access the data via API

After a successful connection via Connector UI or Connector SDK, the first step is to get the RequestId (Unique identifier for the request).

If you are using the Connector UI, you can get the RequestId with event listener. If you are using the Connector SDK you can get the RequestID in the callback.

After you have the RequestId, the next step is to call the API to get the aggregation data.

Access the data via webhooks

You can receive the information as well by webhook, to do that you have to open Zūm Rails portal, navigate to settings > webhook & api settings, then enable the aggregation events.

Once a new connection is made, a webhook will be fired to the specified url.