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:

Call Zūm Rails API to create a Connector Token
Refer the javascript SDK library to your website, build your configuration options and init the SDK
Handle the callbacks
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

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 to the js library below on your website. One URL for sandbox, another one for Production.

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`
options	A JSON options 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,
          paymnetinstrumentid
        ) {
          console.log(
            "onSuccess",
            requestid,
            cardid,
            extrafield1,
            extrafield2,
            userid,
            clientuserid,
            paymentinstrumentid
          )
        },
        onStepChanged: function (data) {
          console.log("onStepChanged", data)
        },
        onConnectorClosed: function () {
          console.log("onConnectorClosed")
        },
      })
    })
  })
</script>

info

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

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

info

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
paymentinstrumentid: The id of the payment instrument associated to the user bank account. You will need to provide the payment instrument id in order to execute a reconnect or check balance flow.

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