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:

  1. Call Zūm Rails API to create a Connector Token
  2. Refer the javascript sdk library into 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 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

{}

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

<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
configA 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.

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

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