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 tokenTo 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 SDKRefer the js library below into your website. One url for sandbox, another one
- Sandbox
- Production
#
Init the JS SDKThe 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
info
We recommend you using the Configure page to build the options
property.
#
CallbacksWhen 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
#
onLoadThis callback is triggered when the UI is loaded and presented on the screen.
Parameters
- There are no parameters in this callback
#
onConnectorClosedThis callback is triggered when the end user clicks in the X button to close the Connector
Parameters
- There are no parameters in this callback
#
onErrorThis 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
#
onSuccessThis 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
#
onStepChangedThis 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 |