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 offers the possibility for you to first create a temporary token, then initiate and configure the Connector via Javascript and finally receive callbacks when the connection is completed.

Steps to follow in order to complete your integration:

Call Zūm Rails API to create a Connector Token
Refer the javascript sdk library into your website, build your configuration options and init the sdk
Handle the callbacks
Go Live

Create a token#

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

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

Method: POST

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

Payload (empty)
Response

{}

You will need to use the property result.Token.

info

Each token is valid only once, for 15 minutes.

Install JS SDK#

Refer the js library below into your website. One url for sandbox, another one

Sandbox
Production

  <script id="zumrailsconnector" src="https://cdn.aggregation.zumrails.com/sandbox/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 you can find an example of the code needed to init the JS SDK.

JS SDK Code

  <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) {
                      console.log('onSuccess', requestid, cardid, extrafield1, extrafield2);
                  },
                  onStepChanged: function (data) {
                      console.log('onStepChanged', data);
                  },
                  onConnectorClosed: function () {
                      console.log('onConnectorClosed');
                  }
              });
          });
      });
  </script>

info

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

Callbacks#

When something happens, the sdk library will fire a few callbacks, this allows you to easily get the data and take an immediate action. 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 in the X button to close the Connector

Parameters

There are no parameters in this callback

onError#

This callback is triggered when the connection failed 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 you can pass as an option, at this moment this field is returned as well
extrafield2: The extra field you can pass as an option, at this moment this field is returned as well

onStepChanged#

This callback is triggered when there is a page change or an action was taken by end the 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
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