# 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>`.

{% hint style="info" %}
We recommend you use the [**Connector Configuration**](https://docs.zumrails.com/data-aggregation/connector-configuration) page to build your customized URL.
{% endhint %}

#### Event listener <a href="#event-listener" id="event-listener"></a>

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

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

Example message:

```json
{
  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 <a href="#create-a-token" id="create-a-token"></a>

To create a token, you must first authenticate in Zūm Rails API. More information can be found [here](https://docs.zumrails.com/docs/canada/api-specification/authentication)

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

`Method: POST`

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

Response

```json
{
  "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`.

{% hint style="info" %}
Each token is valid only once, for 15 minutes.
{% endhint %}

### Install JS SDK <a href="#install-js-sdk" id="install-js-sdk"></a>

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

Sandbox

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

Production

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

### Init the JS SDK <a href="#init-the-js-sdk" id="init-the-js-sdk"></a>

The library expects 2 mandatory parameters:

<table><thead><tr><th width="126">Parameter</th><th>Description</th></tr></thead><tbody><tr><td>token</td><td>The token received in the endpoint <code>{{env}}/api/aggregationconnector/createtoken</code></td></tr><tr><td>config</td><td>A JSON config representing all the configurations available and described <a href="https://docs.zumrails.com/docs/canada/data-aggregation/connector-sdk#configuration">here</a></td></tr></tbody></table>

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

**JS SDK Code**

```javascript
<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>
```

{% hint style="info" %}
In the example above, it will be needed to add [jQuery](https://jquery.com/) reference. Second, in order to trigger the aggregation flow is expected to define a button with id **btnGoConnect**

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

{% endhint %}

{% hint style="info" %}
We recommend you use the **Configure** page to build the `options` property.
{% endhint %}

### Callbacks <a href="#callbacks" id="callbacks"></a>

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 <a href="#onload" id="onload"></a>

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

*Parameters*

* There are no parameters in this callback

#### onConnectorClosed[#](https://docs.zumrails.com/docs/canada/data-aggregation/connector-sdk#onconnectorclosed) <a href="#onconnectorclosed" id="onconnectorclosed"></a>

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 <a href="#onerror" id="onerror"></a>

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 <a href="#onsuccess" id="onsuccess"></a>

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 <a href="#onstepchanged" id="onstepchanged"></a>

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.

{% hint style="info" %}
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.
{% endhint %}

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 <a href="#ways-to-integrate" id="ways-to-integrate"></a>

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

1. Connector SDK

{% hint style="info" %}
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.
{% endhint %}

#### Connector SDK <a href="#connector-sdk" id="connector-sdk"></a>

In order to reconnect a user’s card using the Connector SDK use the same payload specified [here](https://docs.zumrails.com/docs/canada/data-aggregation/connector-sdk) 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

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

{% hint style="info" %}
To activate this feature for your account, please reach out to us at <support@zumrails.com> or using the chat function in the portal.
{% endhint %}

{% hint style="info" %}
Only users added after this feature is activated will be able to reconnect their bank accounts.
{% endhint %}

## 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 <a href="#access-the-data-in-zum-rails-portal" id="access-the-data-in-zum-rails-portal"></a>

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 <a href="#access-the-data-via-api" id="access-the-data-via-api"></a>

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.&#x20;

#### Access the data via webhooks <a href="#access-the-data-via-webhooks" id="access-the-data-via-webhooks"></a>

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.&#x20;