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

Depending on your product use case, there are two ways you can use the data sync feature:

• Automatic Refresh
• Manual Trigger

Automatic Refresh

Mono automatically refreshes all connected accounts to your business on a daily basis. After the automatic refresh, the data of all connected accounts will be automatically updated.

Manual Trigger

If you need new data without waiting for an automatic refresh, you can manually trigger data sync through our Manual Data Sync. This will trigger a request to update the user's financial data.

🚧

NOTE

Some banks require the user to re-authorize data-sync if they have Multi-Factor Authentication (MFA) (i.e OTP, security question, or CAPTCHA) enabled before their data can be updated.

What happens?

For Accounts Without MFA

A webhook event called mono.events.account_updated is sent for both automatic refresh and 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' },
    account: {
      _id: '5fbcde8f8699984153e65537',
      institution: {
        name: "GTBank"
      },
      accountNumber: '0018709596',
      name: 'OGUNGBEFUN OLADUNNI KHADIJAH',
      type: 'SAVINGS_ACCOUNT',
      currency: 'Naira',
      bvn: '9422',
      balance: 3033984,
      created_at: '2020-11-24T10:21:03.936Z',
      updated_at: '2020-11-24T10:21:13.050Z',
      __v: 0
    }
  }
}

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": false,
    "code": "SYNCED_SUCCESSFUL"
}

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

1. Make an API call to the Re-auth Endpoint with the account._id returned from the mono.events.reauthorisation_required webhook event and your secret key. If successful, this will return a re-auth token.

   JSX

   {
     "token": "VwxcfeLRZvq1UlD5WiuN"
   }
   

2. Then you can pass the re-auth token to the mono connect reauthorise() function which will prompt the user to submit the required input as seen in this widget implementation. Please note that connect.reauthorise(reauthToken);, replaces connect.setup() in the Mono re-authorisation widget.

// Code snippet from reauthorize widget implementation

// connect.setup();
const reauthToken = "REAUTH_TOKEN_RETRIEVED_FROM_REAUTHORISE_ENDPOINT"
connect.reauthorise(reauthToken);

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:

📘

NOTE 1

By default, all connected accounts are automatically refreshed once every 24 hours. You can contact us at [email protected] if you want to change the update frequency to:

• 6h, all connected accounts will be refreshed every 6h (4 times a day)
• 12h, all connected accounts will be refreshed every 12h (2 times a day)

COST
We charge NGN 50 for fetching new data.

📘

NOTE 2

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

📘

NOTE 3

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.

📘

NOTE 4

• 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.