Data Sync

Overview

Data sync allows you to fetch new data (balance, transactions, and statements) of a connected financial account from an institution.

Manual Trigger

You can manually trigger data sync through our Manual Data Sync endpoint so as to get new data. This will trigger a request to update the user's financial data.

On Manual Triggers

Some banks require the user to re-authorize data sync if they have Multi-Factor Authentication (MFA) enabled on their account. This means that the user will be required to enter an OTP, security answer, or CAPTCHA before their data can be updated.

What Happens?

For Accounts Without MFA

A webhook event called mono.events.account_updated is sent for a manual trigger. After this has been sent, requests to the Information , Statement, Transactions , Income endpoints will now return new data. The returned data object that is sent with this webhook event is shown below:

{
  "event": "mono.events.account_updated",
  "data": {
    "meta": {
      "data_status": "AVAILABLE",
      "auth_method": "internet_banking"
    },
    "account": {
      "scope": [
        "financial_data"
      ],
      "_id": "6631279bdedfbd",
      "name": "Samuel  Olamide",
      "accountNumber": "0235000043",
      "currency": "NGN",
      "balance": 20044,
      "type": "Tier 3 Savings Account",
      "bvn": "1010",
      "liveMode": true,
      "institution": {
        "name": "ALAT by WEMA",
        "bankCode": "035",
        "type": "PERSONAL_BANKING"
      },
      "accessType": "PERSISTENT",
      "created_at": "2024-04-30T17:16:01.171Z",
      "updated_at": "2024-05-01T10:25:23.666Z"
    }
  }
}

For the manually triggered sync, along with the webhook event above, the object response from the Data Sync endpoint when triggered is shown below:

{
    "status": "successful",
    "hasNewData": true,
    "code": "SYNC_SUCCESSFUL",
    "message": null
}

For Accounts With MFA Enabled

If the connected account has Multi-Factor Authentication (MFA) enabled, the user must re-authorise the connection using MFA (i.e OTP, security question or CAPTCHA), before new data can be retrieved from their financial institution.

A webhook event called mono.events.reauthorisation_required, will send the response below, containing the connected account._id

{
  event: 'mono.events.reauthorisation_required',
  data: {
    account: {
      _id: '5fbcde8f8699984153e65537'
    }
  }
}

For the manually triggered sync, along with the webhook event, the response from the Data Sync endpoint is shown below:

{
    "status": "failed",
    "hasNewData": false,
    "code": "REAUTHORISATION_REQUIRED"
}

The user then has to re-authorise their account on the Mono Connect Widget before the Data Sync can be completed.

Handling Re-authorisation

Re-authorising A User Account for Data Sync (Using the Reauth Link)

Data sync allows you to fetch new data of a connected financial account from an institution. However to do this, you need to reauthorise access to this account. This can be done by following the instruction in the reauth link guide.

Reauth Link Guide

Re-authorising A User Account for Data Sync (Using the Connect SDK)

{
  "token": "VwxcfeLRZvq1UlD5WiuN"
}

Once the user has successfully completed the re-authorisation, a webhook is sent with status mono.events.account_updated to notify you that the new data is available.

Now when the Information , Statement, Transactions , Income and the Identity endpoints are called, they will return the new data.

Best Practice

If you run a CRON job every night to refresh data and re-authorisation is required for some of your connected accounts you will need to store account ids that require re-authorisation and send a push notification or email to the user during the day when they are more likely to re-authenticate.

Another recommendation is that, when your receive reauthorisation_required, you can add a flag to that account in your database (e.g account.requires_reauth = true ). Thereafter when your user logs in back to your app, you can then check if that account requires reauthorisation. If yes, ask the user to reauthorise, then you can generate the re-auth token on fly and pass to the re-auth widget when done.

Please go through these important notes highlighted below:

Not all banks require Multi-Factor Authentication(MFA). To see a list of banks that require MFA before Data Sync, click here.

Re-auth tokens expire after 10 minutes. You should request a new re-auth token before you prompt the user to authenticate through the Mono Connect Widget.

• Manual Data Sync has a rate limit of one API call per connected account, every two minutes.
• Only the accounts created after data sync gets activated will receive webhook events notifications.

Activating Data Sync

To activate Data Sync for your business, log in to the Plans & Billing page on your dashboard, switch to the My Subscriptions tab and toggle the Data Sync switch on, to enable it for your business, as seen in the image below;