Documentation

Account Linking / Web SDK

Reference for integrating with the Link JavaScript SDK

Installation

Include the IXily Link initialize script on each page of your site. It should always be loaded directly from https://ixily.io, rather than included in a bundle or hosted yourself.

    
  

Getting Started

To initialize, add your credentials:

  • keyrequired, string
    Include the key provided in the ixily settings.
  • secretrequired, string
    Include the secret provided in the ixily settings.
    
  

Environment

The setting of this value will determine whether demo or production accounts will be linked. Different investment account providers do have different workflow, but the intention is that if the environment is set to Demo, only demo/test/paper accounts can be added. When set to Production, if the configuration of the Collection allows for it, a demo account can be linked (to that collection).

  • envrequired, string
    Specify the access environment, it has the following properties: demo / production
    
  

Language

The text used within the SDK is available in multiple languages, however the text of the Collection shows in whatever language was used in its configuration.

  • setLanguageoptional, string
    Specify the language for text used within the SDK (EN, FR or ES). Defaults to EN.
    
  

Define User Type

There are two types of user - hybrid and partner.

  • Hybrid: The user is shared between IXily and you (the party requesting the connection) while a authorised connection remains in place. The user has an IXily logon with which the user must authenticate in order to link their account. This allows them to more easily link accounts - a single click versus completing the investment account provider's security process and in the case where s/execution access is being requested, it allows the user to define the limits within which their account can be managed.
  • Partner: The user is your internal, private, user; a reference is passed so that you can identify the link that is created, but no other identifable information need be passed. In doing so, a user will not be able to access the created account, nor share any data. In addition, you assume full management of the user and the account (depending on whether the connection created was for read or s access).

Note that if 'hybrid' is selected, the user will be required to authenticate, register or have a bearer token passed in. While it might seem easier to set all users to 'partner', the user's experience and ability to own, control and customise their data and interact with a service will be extremely limited if this is the case. While 'hybrid' does add an authentication layer, it will enable the user to link their account within the context of their financial network, rather than for just a single party.

  • userrequired, string
    User type: hybrid, partner
  • userDatarequired, object

    If the 'user' is set to 'partner' then an object of the user's details can be passed in for your own reference. None of these values are required and none are required to be 'real'. The purpose is associate some basic information with your internal user and the user record created at IXily.

    • reference: string/required: your internal reference for your user
    • email: string/required; pass a string with the structure of a valid email address. If not passed, a default (unusable) IXily email will be created.
    • firstname: string/optional; set to null if not passed
    • lastname: string/optional; set to null if not passed
    • country: string/optional: two character ISO code
    
  
    
  

Authentication Token

If a bearer token is available, it can be passed to the SDK in order to identify the authenticated user. This will be most commonly used when you have authenticated as yourself. A token should only be passed where the User Type has been set to 'hybrid'.

  • tokenoptional, string
    A valid bearer token where the user has been pre-authenticated. If the user type has been set to hybrid and an invalid token is passed, then the user will be asked to re-authenticate.
    
  

Payments

If you as a client have another way to accept/take payment then you must set this property to false otherwise the payment subscriptions will be enabled.

  • enablePaymentsoptional, boolean
    default value: true
    
  
    
  

Requested Scope

The level of access that is required on the end user's investment account. Note that only one party can have s (execution) access to the account at any one time.

  • s: requests execution access over an account, allowing positions to be opened, closed and/or adjusted.
  • Read: requests to read all data available for the account including current and historical financial data..
  • Read Portfolio: requests to read only the most basic portfolio of an account. This includes the asset ticker and name only and no financial, account or account owner information.

  • scoperequired, string
    write, read or read:portfolio
    
  
    
  

Callback Events

If after finishing a process you want to save or only show the result on your site, whether successful or not, you can use this function:

  • namerequired, string
    Event name you want to subscribe or listen (CLOSE, ACCOUNT_LINKED_INFO, DEBUG)
  • resultrequired, callback
    Process result: onSuccess, onError
    
  

Linking Workflow

The account owner can be directed to any number of points within the linking workflow to begin the process. Where they will be begin will depend on not only the service you want to provide, but if you want the user to see all your services/products, how you want to charge for your service and how simple you want the workflow to be.

List Services

Services are those financial products which you or your company provides such as account management, advisory, trade ideas, descretionary management and more. An end user will select a service to view those products that you offer within the service.

  • optionrequired, string
    services-offered - Option to list all available services
    
  
    
  

List Collections Within A Service Type

A collection is a group (of accounts). In the context of linking this is typically where the collection is used for Execution or Discretionary management i.e. each collection is a fund/strategy (to which the user will link their account). If you offer a number of funds/strategies then the SDK can be configured to open at the list of these funds/strategies.

  • optionrequired, string
    • select/discretionary (Execution or Discretionary Management)
    • select/advisory (Advisory or Trade Ideas)
    • select/account management (Account Managenment)
  • userrequired, string
    User type: hybrid, partner
  • scopeoptional, string
    write, read or read:portfolio
    
  
    
  

View Collection Detail

View the details of an individual collection including any supported business models (payments) and entry requirements such as minimum/maximum account balance, account types, investor type restrictions (retail vs accredited/professional).

  • optionrequired, string
    select/collection/{{collectionReference}}
  • userrequired, string
    User type: hybrid, partner
  • scopeoptional, string
    write, read or read:portfolio
    
  
    
  

Initiate Linking Account to Collection

Initiates the linking process of an account to a collection (for read or write), but bypasses the introductory view. This is may be preferential where the linking context has already been provided to the user in a site/app and the priority is the linking process only.

  • optionrequired, string
    select/collection/{{collectionReference}}
  • userrequired, string
    User type: hybrid, partner
  • linkTorequired, string
    Collection Reference
  • scopeoptional, string
    write, read or read:portfolio
    
  
    
  

Skip Previously Linked Accounts

For an authenticated user, investment accounts that the user has previously linked can be displayed to allow easier transparency during to the linking process as to what account they have already linked, with who and with what permissions. It may particularly help where the Requested Scope is for read access which can be granted on accounts that have already been linked (for each or s access). This means that the user has already connected their account securely and will not be required to do so again.

  • statusrequired, boolean
    If the status is true, the view will be skipped, otherwise it will be displayed as usual.
    
  

Know Your Client

Verification of user identity; in the context of account linking, a collection can be configured to require the connecting user to be KYC'd before the linking process can be initiated. For example, any invest manager would require their clients to be KYC.

  • optionrequired, string
    kyc
  • userrequired, string
    User type: hybrid, partner
    
  
    
  

Professional Status Check

Professional status is currently limited to the United Kingdom. Based on the FCA's criteria for what constitutes a Professional investor, a user can connnect both bank and brokerage accounts to determine if their level of cash trading experience.

  • optionrequired, string
    professional-status
  • userrequired, string
    User type: hybrid, partner
    
  
    
  

Billing

Option to add information related to user billing.

  • optionrequired, string
    payment-method
  • userrequired, string
    User type: hybrid, partner