API response body

{
  "_meta": {
    "client_uuid": "6415e9a7-9496-4c4e-91c4-e3774cd491ad",
    "user_uuid": "33b6215d-3d75-4271-801c-6da27603a8be",
    "institution_id": "zenithbank",
    "utc_starttime": null,
    "utc_endtime": null
  },
  "balances": [
    {
      "account_id": "508**379",
      "account_type": "depository",
      "records": [
        {
          "description": "MC Loc Web Prch-130318299276--BUYPO",
          "balance": 6.6,
          "ts": 1635578149,
          "account_id": "508**379",
          "account_type": "depository",
          "currency": null,
          "labels": []
        }
      ]
    },
  {
      "account_id": "187**097",
      "account_type": "depository",
      "records": [
        {
          "description": "QwikyMart ATM",
          "balance": 44.3,
          "ts": 1635578011,
          "account_id": "187**097",
          "account_type": "depository",
          "currency": NGN,
          "labels": []
        }
      ]
    }
  ]
}

Summary

A "Balance" is a measure of capital associated with an account, belonging to a user's Institution, at a given point in time.
For a depository type account, balance signifies the amount held in a depository account.
For a loan type account, balance signifies the principal amount owed to a loan account.

Query/Response Behavior

If no time range is provided in the query, the endpoint defaults to returning a single, latest balance record, on a per account_number basis.

Fields

balances[].account_id

Multiple accounts can be associated with an institution. The Balances endpoint returns the entire collection of records, across all possible accounts. In this example, these are records belonging to the user's institution Zenith Bank (institution_id = "zenithbank"). It is possible that a user has multiple accounts (e.g. a savings and a checking), in which case Pngme attempts to extract the distinct account_id of each account. In this case, a call to the Balances API might show two sets of records, each grouped by different account_id. _If the account_id value is not extractable, this field shows as "account_id": "default".

balances[].account_type

The type of account associated with the set of records. See the Account Types section.

balances[].records[].description

A helper string extracted from the raw SMS. This is sometimes useful in contextualizing the balance record.

balances[].records[].balance

The amount of the balance.

For a depository type account, balance is the balance on the account at that point in time.

For a loan or revolving_loan type account, balance is typically the outstanding principal amount, or total amount owed, on a loan.

balances[].records[].ts

The UTC unix timestamp, in seconds, at which the balance record event occurred (specifically, when the SMS was received at the mobile phone user's phone)

balances[].records[].account_id

Same as above. The account_id for the account for which balance records are grouped.

balances[].records[].account_type

Same as above. The account type for the given account for which balance records are grouped.

balances[].records[].currency

A currency field, if available. Currency is not always extractable for a given balance record. If no currency field is provided, consider using the default currency or country currency provided from the /users/{user_uuid}/institutions endpoint.
If present, currency is one of the recognized currency codes, as detailed in the Currency Codes section.

balances[].records[].labels[]

One or more labels associated with the given balance record. See the Labels section for a list of recognized labels, and their description.

Interpreting labels

Example:

{
  "_meta": {
    "client_uuid": "6415e9a7-9496-4c4e-91c4-e3774cd491ad",
    "user_uuid": "33b6215d-3d75-4271-801c-6da27603a8be",
    "institution_id": "nicepay",
    "utc_starttime": null,
    "utc_endtime": null
  },
  "balances": [
    {
      "account_id": "default",
      "account_type": "loan",
      "records":
     {
      "description": "NicePay loan approval of 1800NGN, transfer first disbursement of 500 NGN on 01/12/2022",
      "balance": 1800,
      "ts": 1635576794,
      "account_id": "default",
      "account_type": "loan",
      "currency": NGN,
      "labels": ["LoanApproved", "LoanDisbursed"]
    }
  ]
}

The above is a balance statement, showing a principal balance owed of 1800 NGN, from an account of type "loan", with institution "nicepay". This transaction has been labeled with two labels: LoanApproved and LoanDisbursed. Those labels signify that at the time of this transaction, a loan approval and loan disbursement event took place. Given that a LoanApproval event coincided with this balance statement, it stands to reason that 1800NGN is the loan size at time of Approval.