Data Sync
Data sync allows you to fetch recent data (balance and transactions) from financial accounts linked to your web or mobile app, without requiring your user to login again.
The financial accounts in this case are of two natures:
i. The financial accounts that only require username and password to login on the Mono widget.
ii. The financial accounts that require Multi-factor Authentication (MFA).
There are two types of Data Sync. But before we delve fully into these types, we need to first understand how Mono's webhooks (events) run under the hood, and then we can understand what nature of data and response we are to expect.
Webhooks
Mono sends Webhook events to your Webhook URL to notify you of data updates.
To get started, it is important that you verify your webhook headers. This can be achieved with what we call "mono-web-secret". This is a secret key that Mono parses into the header, which helps you verify the authenticity of the webhook source on your end. This secret key can be gotten on your dashboard right after an app is created.
If you do not have this mono-web-secret, you can go through this guide. Right after this guide, head on to "Edit app" on your Mono Dashboard, and add your webhook URL to the field. Once added, you would get a webhook secret (e.g sec_webhook_key) displayed on the screen. Ensure to take note of this key, since you will need it to authorize your webhook connection.
Webhook Events
Webhook events is how Mono notifies you when there are updates to balance and transactions via events.
The snippet below is a typical successful response gotten from the Webhook account updates (account_updated event)
Mono's webhook events are of three categories.
mono.events.account_updated
mono.events.reauthorisation_required
mono.events.account_reauthorized
1. mono.events.account_updated
This webhook event is fired to notify you about updates to connected accounts.
For this particular event, a meta data_status is sent to indicate the current state of events for account updated.
The various meta data_status parameters are:
AVAILABLE | PROCESSING | FAILED
The snippet below is a typical response gotten from the account_updated event:
2. mono.events.reauthorisation_required
This event is sent when the connected account has Multi-factor Authentication (MFA) enabled and requires a token/OTP. MFA-enabled accounts need to be re-authenticated, and then the account ID will be sent to the data field.
3. mono.events.account_reauthorized
This event is sent after a successful account is reauthorised. The account ID. would be sent to the data field.
Types of Data Sync
With a solid understanding on how Webhook events run under the hood, we can then move onto the types below.
1. Automatic Refresh:
Mono automatically refreshes all the accounts connected to your business on a daily basis and notifies you via webhook events as soon as the connected account data is available for you to use. What this implies is that once you have your backend setup to receive requests and updates via webhooks, you could then save the updated account to your DB with the account id that is provided in the data field.
NOTE: By default, all connected accounts are automatically refreshed once, every 24 hours. You can contact us at hi@mono.co, 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)
2. Manual trigger endpoint:
Manual Trigger allows you to force-trigger data refresh which can be used to enable an option for your users to manually refresh their financial data, using the manual trigger sync Endpoint.
The snippet below is a basic implementation of triggering the data sync manually:
Once this is performed and a response code "SYNCED_SUCCESSFULLY" is received, Mono will notify you via webhook, you can then go on to update the connected user profile on your database(DB) at the webhook event → mono.events.account_updated
Expected Responses
a. Successful Response
This response is received when data sync for a connected account is successful. This implies that Mono will notify you via webhook, and then you can update the connected user profile on your database (DB) at the webhook event → mono.events.account_updated
A typical response that would be received from the sync endpoint when successful would be:
b. Re-authorisation Response
This response is received when data sync is unsuccessful. A typical response is seen in the snippet below:
Interested in using Mono?
Request access to get started with a N2000 free API call credit or reach out to us at hi@mono.co. Make sure to follow us on Twitter to stay in the loop of our latest announcements.
