Overview

This feature allows you to retrieve the most recent financial data from your customer's linked account. We silently fetch data from the bank if persistence access is available; otherwise, re-authorization is requested from the user.

How It Works

• Step 1: Partners add x-realtime in their API header for endpoints like balance and transactions.

• Step 2: After initiating the call, we return the X-HAS-NEW-DATA: true | false , X-JOB-ID and X-JOB-STATUS in the response headers. These headers provide information on the job's progress and indicates if new data is available.

• Step 3: On completion of the job, the mono.accounts.jobs.update webhook is triggered to notify partners of the job’s status. Business will also receive the mono.accounts.account_updated webhook, providing updates on the sync status.

• Step 4: If account doesn't require reauth, the balance or transactions endpoint returns updated data. If the account requires reauthorization, this is returned as failed in the response headers as well as the jobs mono.accounts.jobs.update webhook. The business then users the reauthorization endpoint to trigger a reauthentication by the user.

Authentication

Requests to the API for real time data must include the following in the header:

• Mono Security Key: mono-sec-key: live_sk_example
• x-realtime: true

API Response Headers

The responses in the endpoints below will include the following header:

• x-has-new-data: true | false - Indicates if the user has new data and it was fetched.

• x-job-id: "string" - This represents a unique identifier for an asynchronous job or task. It’s a string that helps track the status and progress of the job as it processes in the background.

• x-job-status: finished | processing | failed - This header indicates the current status of the job associated with the x-job-id.

X-JOB-STATUS

Job Status can have one of the following values:

• FINISHED: The job has completed successfully.
• PROCESSING: The job is currently being worked on and hasn’t finished yet.
• FAILED: The job has encountered an error and didn’t complete successfully.

API Endpoints

Real Time can be retrieved using the following endpoints:

• Balance API
• Transactions API

{
    "status": "successful",
    "message": "Request was succesfully completed",
    "timestamp": "2024-07-05T12:20:59.336Z",
    "data": {
        "id": "666b166ce06be73",
        "name": "Samuel  Olamide",
        "account_number": "0200000043",
        "balance": 53769,
        "currency": "NGN"
    }
}

Webhook Events

When real-time data is triggered, two webhooks are sent.

• mono.accounts.jobs.update
• mono.events.account_updated

Job Update Webhook

This Webhook is sent to notify you of the job status i.e processing, failed, or finished

Sync Successful

If the sync was successful, you will receive the following response via the mono.accounts.jobs.update webhook:

{
  "event": "mono.accounts.jobs.update",
  "data": {
    "id": "jobs.accounts_66f3d4ed05261f275",
    "name": "jobs.accounts.sync_statement",
    "status": "finished"
  }
}

Sync processing

If the sync is processing, you will receive the following response via the mono.accounts.jobs.update webhook:

{
  "event": "mono.accounts.jobs.update",
  "data": {
    "id": "jobs.accounts_66f3d4b335261f275",
    "name": "jobs.accounts.sync_statement",
    "status": "processing"
  }
}

Sync failed

If the sync fails, you will receive the following response via the mono.accounts.jobs.update webhook:

{
  "event": "mono.accounts.jobs.update",
  "data": {
    "id": "jobs.accounts_66f3de36d05261f392",
    "name": "jobs.accounts.sync_statement",
    "status": "failed"
  }
}

Account Updated webhook

Shortly after the mono.accounts.jobs.update is sent, you will also receive the mono.accounts.account_updated webhook, providing updates on the sync status.

Webhook response sample

{
  "event": "mono.events.account_updated",
  "data": {
    "account": {
      "_id": "66e2d530c293212b39d34aa8",
      "name": "SAMUEL OLAMIDE NOMO",
      "accountNumber": "0100000062",
      "currency": "NGN",
      "balance": 17542,
      "type": "SAVINGS ACCOUNT - INDIVIDUAL",
      "bvn": "22000000003",
      "authMethod": "mobile_banking",
      "institution": {
        "name": "Union Bank of Nigeria",
        "bankCode": "000018",
        "type": "PERSONAL_BANKING"
      },
      "created_at": "2024-09-12T11:49:04.416Z",
      "updated_at": "2024-09-13T09:58:00.950Z"
    },
    "meta": {
      "data_status": "AVAILABLE | FAILED| PROCESSING",
      "auth_method": "mobile_banking",
      "sync_status": "SUCCESSFUL | FAILED | REAUTHORISATION_REQUIRED"
    }
  }
}

If the sync_status is successful in the webhook response, you can proceed to call the transactions or balance endpoint to retrieve the updated data. This means that the x-realtime field in the headers should be set to false once the API call is successful to avoid creating a new realtime session for the customer’s account.

If the sync_status is reauthorisation_required in the webhook response, you can proceed to call the Reauthorization endpoint

Real-time Job Status

Path Params

Requests to the API for real time data must include the following in the header:

• ID: Account ID of a connected account
• JOB-ID: This is a unique identifier returned in the response header when x-realtime is set to true.

Response

{
    "status": "successful",
    "message": "Job execution completed",
    "timestamp": "2024-09-25T09:16:58.051Z",
    "data": {
        "id": "66f3d4b3305261f275",
        "job_status": "processing | failed | finished",
        "name": "jobs.accounts.sync_balance | jobs.accounts.sync_statement",
        "account": "66f3caafc2d35bca",
        "type": "statement",
        "synced": true | false,
        "reauth_required": true | false
    }
}