Initiating synchronisations

Operating modes

The 'Accounts' platform can be parametrized according 2 forms (contractuals), depending on the integrator's needs:

The 'Recurring' mode allowing to recover the banking data of the users from day to day.
The ‘OneShot' (or 'One Off’) mode for a specific need for which you only want to retrieve the user's banking data through a single synchronization. This synchronization is done at the creation of the connection. The user is then deleted.

There are 2 types of synchronizations, configurable via the 'auto_sync' widget parameter:

Automatic, performed daily for all existing connections and for all users. This is the default mode (auto_sync=true)
Manual, executed by a user his connections (auto_sync=false)

In 'OneShot' mode, automatic synchronizations must be disabled (widget 'auto_sync' parameter set to false) or the connection (or the user) must be deleted immediately after the user's data is recovered. Manual synchronizations are not allowed in this mode.

Synchronisations

Description

Synchronizations are asynchronous jobs. They are used to retrieve new user data: balance, transaction list, detection of new bank accounts and financial products. The duration of a synchronization is determined by several factors: quality of partner services, number of connections and accounts to refresh, etc.

As soon as a job starts, it will undertake a whole series of actions. For each action performed (in success or in error), an event is recorded in a Queue.

To follow the state of synchronization, it is possible to use a queue: just listen to the content of the queue and interpret the different events contained in it. Go to the dedicated chapter using queue and events to have a description of this proccess.

Manual synchronization

Our system is actually designed to refresh the data automatically:

1 time per day by nightly batch
during an API request if the last synchronization is older than 6 hours

You can synchronize all the connections of a user or a specific connection.

When you synchronize all connections and accounts, the API returns a list of links corresponding to the different connections that will be synchronized.
When you synchronize only one connection, the API returns an HTTP 204 status code indicating that the API has taken the request into consideration. You can also specify a synchronization type:
- Type=ALL allows you to retrieve the information (balances, transactions...) of the financial products linked to the connection.
- Type=LIST_ACCOUNTS allows you to retrieve the list of financial products linked to this connection. With a synchronization of type LIST_ACCOUNTS, any new account and all the accounts previously deleted will be added automatically. A synchronization of type ALL is started automatically when the LIST_ACCOUNTS synchronization finishes. The final event of the LIST_ACCOUNTS synchronization still contains the account list.

The Synchronization ends when there is an event with event_status: "SYNC_ALL_SUCCESS". You have the synchronization status in the status property of the resource associated with the event. The status description of the connection is described in the API reference.

Example:

# Synchronize one connection
curl -X POST \
  https://api.oxlin.io/v2.1/connections/{connection_id}/synchronize \
  -H 'authorization: Bearer {access_token}'

# Synchronization triggered
HTTP/1.1 204 No Content

# Synchronize all connections
curl -X POST \
  https://api.oxlin.io/v2.1/connections/synchronize \
  -H 'authorization: Bearer {access_token}'

# Synchronization triggered for each connections 
HTTP/1.1 200 No Content

{
  "connection_links": [
    "/connections/{connection_id_1}", 
    "/connections/{connection_id_2}",
    ... 
  ]
}

# If you poll the queue, events stack in the queue
curl -sk https://api.oxlin.io/v2.1/queues/{queue_id} \
  -H 'authorization: Bearer {access_token}'

# Queue contains events
HTTP/1.1 200 OK

# Here is one event from the list.
[
  ...
  {
    "id":"14",
    "event_type":"SYNC_ALL_STARTED",
    "resource_type":"CONNECTION",
    "creation_date":1527761001,
    "channel_definition_id": "redirect1",
    "resource":{
      "id":"{connection_id}",
      "provider_id":"200",
      "name":"WBX Test Bank",
      "status":"SUCCESS",
      "creation_date":0,
      "channels":[{
        "channel_definition_id": "8701",
        "expires": 1527761000,
        "status": "RUNNING",
        "last_success_date":1527760963,
        "last_end_date":1527760963
      },{
        "channel_definition_id": "8700",
        "status": "RUNNING",
        "last_success_date":1527760963,
        "last_end_date":1527760963
      }]
    }
  },
  ...
]

# Poll again to retrieve new events...
curl  -sk https://api.oxlin.io/v2.1/queues/{queue_id} \
  -H 'authorization: Bearer {access_token}'

...

# The Synchronization ends when there is an event with event_status=SYNC_ALL_SUCCESS
{
  "id": "20",
  "event_type": "SYNC_ALL_SUCCESS",
  "resource_type": "CONNECTION",
  "creation_date": 1528112097,
  "resource": {
    "id": "{connection_id}",
    "provider_id": "200",
    "name": "WBX Test Bank",
    "channels": [
      {
        "channel_definition_id": "8701",
        "expires": 1528106353
        "status": "SUCCESS",
        "last_success_date": 1528112084,
        "last_end_date": 1528112084
      },
      {
        "channel_definition_id": "8700",
        "status": "SUCCESS",
        "last_success_date": 1528112084,
        "last_end_date": 1528112084
      }
    ],
    "status": "SUCCESS",
    "creation_date": 0
  }
}

The reference documentation details the formalism of these 2 commands as well as the response and the different return codes of the API:

Challenge management

When a challenge request is detected on a connection following a manual synchronization, it is necessary to ask the user to perform a strong customer authentication (SCA).

this SCA can be of 2 types:

Code: The user must enter a code sent by SMS to his phone number.
Decoupled: The user must validate in the bank app the login action.

This can be done by:

Analyzing the queue events. You have to parse the events in the queue (SYNC_ALL_USER_INPUT_REQUESTED, LIST_ACCOUNTS_USER_INPUT_REQUESTED, …).
Presenting the user with the widget's graphical interface allowing him to perform this authentication. This is a fairly complex command to implement.You have to call the user_input function (documentation https://developers.oxlin.io/en/docs/widgets#user-input.

This makes it possible to manage the bank's challenge request in real time.

In case events are not used, for reasons of simplicity and/or to manage CHALLENGE_REQUIRED or CHALLENGE_TIMED_OUT statuses, it is also possible to use the edit_credential widget function. The challenge will thus also be managed by the widget.

The disadvantage of this solution is that this challenge management will be executed during an additional synchronization

In terms of managing challenges, it is also necessary to manage cases of error:

CHALLENGE_TIMED_OUT,
CHALLENGE_FAILED,
CHALLENGE_CANCELLED

Operating modes​

Synchronisations​

Operating modes

Synchronisations