Quickstart

Summary

This quick start guide explains you how to set up and use the API in order to retrieve the accounts and transactions from the user's banks.

To get your user's accounts and transactions, you first need to create a new Linxo Connect user and set up his bank connection. The following steps show you how to do this easily:

1. Client authentication to retrieve a token allowing you to create the user (in 'client' mode).
2. Create a user if he doesn’t already exist. The user is at the center of the API resources. It will be used to group connections to banking providers and store the accounts and transactions.
3. User Authentication to retrieve a token allowing you to access user resources.
4. Initiate the widget: When using widgets, you need to create a user session to work with. The data created in the widgets will be attached to the user provided in the session.
5. Select a bank or the Linxo test bank. The widgets are available in a browser by using its URL and the user session. The user will follow the UI flow to perform actions before going back to the provided callback URL for you to handle the results.
6. Retrieve connections established from the widget
7. Get accounts and transactions. Once the data is made available, thanks to the connection, you will be able to collect accounts and transactions to manage your business needs.
8. How to continue provides you with additional links to access more information

Security: The secure connections are set up according to the OAuth2 protocol:

• You retrieve an OAuth2 client token with your client identifier & client secret and according to the client credential flow. This allows you to create a user.
• You retrieve an OAuth2 user token, according to the ROPC flow, needed to create the widget user session.
• With the widget, you can therefore create a connection using this user session.

1. Client authentication

You will need a Client OAuth2 access token that identifies your application so that you can create an Linxo Connect user.

To do so, you have to implement the OAuth2 client credentials flow. Go to the Advanced authentication page for more information.

To use this flow, you will have to perform a HTTP basic authentication with a POST request on the /token endpoint of the Linxo Connect authentication server.

Execute the following to generate a token. You can modify the body parameters if you want to test with your own credentials and parameters:

2. Create your Linxo Connect user

Let's assume you want to create a new Linxo Connect user: You just need to provide an email and password. No email will be sent, it is only used as a unique key.

Use the Client OAuth2 access token you just created, which identifies your application, to create your user in a secure way. Request the /users API endpoint to do so.

You must give a valid user email

You may also edit the email and password parameters in the body of the request:

curl -sk -X POST {baseUrl}/users
    -H 'authorization: Bearer {access_token}'
    -d email={email}
    -d password={password}

The response header location contains the user identifier that can be used as a reference for the requests

3. User authentication

To identify your Linxo Connect user over the system, You have to ask for a User Access Token following the OAuth2 Resource owner password credentials (ROPC) authentication flow. Refer to the Advanced authentication page for more information.

Widgets services are relying on Accounts API endpoints and therefore you need to use the accurate list of scopes depending on the widget action you want to deal with for your Linxo Connect user. Refer to the list of scopes for detailed information.

Request the /token API endpoint to get the user access token.

curl -sk -X POST {authUrl}/token
    --header 'Content-Type: application/x-www-form-urlencoded' \
    --data-urlencode 'grant_type=password' \
    --data-urlencode 'username={username}' \
    --data-urlencode 'password={password}' \
    --data-urlencode 'client_id={client_id}' \
    --data-urlencode 'client_secret={client_secret}' \
    --data-urlencode 'scope=openid profile accounts_read' \
    --data-urlencode 'provider=connect' \

4. Initiate widget

Linxo Connect widgets provide an easy way to integrate with our solutions. Thanks to a responsive UI, you can easily integrate this solution into your ecosystem.

You now own everything you need to negociate a Widgets Service session for your Linxo Connect user. The Widget service provides the endpoint /widget_session to create a session containing the user credentials and returning the session ID.

The Quick Start shows you in a simple and interactive way how the widget works.

Execute the following to create a user session with your client credentials: {widgetUrl}/widget/widget_session

curl -sk -X POST {widgetUrl}/widget/widget_session
    -d client_id={client_id}
    -d client_secret={client_secret}
    -d access_token={access_token}

5. Select bank or test bank

Once you have your widget session you can call:

• The add connection entrypoint allowing a user to select his bank(s) from among all offered by Linxo Connect. In this quickstart, this is done by clicking on add connection link below to display this list of banks.

A connection with each provider will be created. The service will try to reach the provider to validate the user credentials.

In this bank list you have the Linxo test bank which emulates the behavior of a real world provider. An HowTo is also dedicated to this test tool.

A configuration file makes it possible to configure this bank and supply it with different types of accounts and transactions. This is useful to test your implementation. The default file also available at https://linxo-test-bank.s3.amazonaws.com/stettestbank/test-bank.txt has the following credentials: login: dev - password: dev

The client can provide some parameters to customize the screen flow and he is notified of the results by a callback URL. This is also done by calling the endpoint /add_connection.

• The manage connections entrypoint allowing a user to manage his connections. In this quickstart, this is done by clicking on manage connections link below to display this list of connection.

The client can provide some parameters to customize the screen flow and he is notified of the results by a callback URL.

6. Retrieve connection

Connections contain the list of information required to connect to a provider's website. This endpoint allows you to retrieve the list of all connections. You can filter them and paginate them according to different criteria.

To do so, you call the /connections endpoint.

curl -sk -X GET {baseUrl}/connections/{connection_id}
  -H 'authorization: Bearer {access_token}'

7. Get accounts and transactions

Once you have your connection defined, you can now retrieve the list of accounts and the list of transactions.

The structure of an account can change depending on the type of account (LOAN, CHECKING, etc.).

Accounts can be filtered with several criterias and can be sorted by name and/or creation_date. It is possible to archive or unarchive an account by using its status. A closed account will not be synchronized and activate an account will schedule a synchronization.

You therefore use the following endpoints /accounts and /transactions to retrieve all the accounts and transactions of a user.

This example below allows you to retrieve transactions from all accounts.

curl -sk -X GET {baseUrl}/accounts/{account_id}
  -H 'authorization: Bearer {access_token}'

curl -sk -X GET {baseUrl}/transactions/{transaction_id}
  -H 'authorization: Bearer {access_token}'

8. How to continue

These few examples have allowed you to authenticate yourself, create a new user and initiate a widget to create a connection. With this connection you are able to retrieve all your accounts and transactions.

The next chapter gives you the main concepts and useful information to be able to use our API.

You can also implement more elaborate examples described in the 'HowTo' chapter.

And finally you may handle your users' data in a much specific way by using the endpoints described in the reference documentation. You will also have to take into account the credential lifecycle.

This Postman file contains the main endpoints describe in this Quickstart and may help you to quickly and easily send the REST requests. You just have to import this file and parametrize the client_id, client_secret, user_email and user_password variables.