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

{}

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.

<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:

ParameterDescription
tokenThe token received in the endpoint {{env}}/api/aggregationconnector/createtoken
optionsA JSON options representing all the configurations available and described here

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

<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:

ParameterDescription
CONNECTORLOADEDWhen the Connector is loaded
CONNECTORCLOSEDWhen the Connector is closed
CONSENTACCEPTEDWhen the consent was accepted
INSTITUTIONSELECTEDWhen an institution is selected
AUTHENTICATEINITIATEDWhen we start authenticating the connection
ACCOUNTSELECTORFOOTERCLICKEDWhen the link on the instution selection footer is clicked
SECURITYQUESTIONPROMPTEDWhen a security question is prompted
SECURITYQUESTIONANSWERINITIATEDWhen the security question is answered, and we resume the authentication
AUTHENTICATECOMPLETEDWhen authentication is completed
GETINFORMATIONINITIATEDWhen the get card information process starts
GETINFORMATIONCOMPLETEDWhen the get card information process completes
CONNECTIONSUCCESSFULLYCOMPLETEDWhen the process is completed
GENERICERRORWhen an unexpected error occurs