Fetch balance

Overview

Balance is an Okra product for receiving real-time balance information data programmatically via /balance/check API.

How to add balance to your app

In this guide, we'll walk through from scratch, how to use the Balance API in your project
If you're familiar with using Okra and already have Okra setup on your machine, you can skip to Identity API, otherwise, carefully follow the next section.

Okra API keys

If you're new to Okra, you'll need to create an Okra developer account.
After creating your account, you'll need to login.
To find your API keys, navigate to the Settings menu on the Okra developer dashboard.
To better understand how Okra API keys work, check this tutorial

Balance model

Before diving deep into the tutorial, you might need to get yourself familiar with the balance object models.

Install Okra Libraries

Depending on your integration you can install any of our libraries/SDK, to fetch real-time balance.
Check the list of libraries you can use.

Using the Okra Widget

You can check an account's balance using the Okra widget.

1. Install the okra-js package by running npm install okra-js
2. Use the buildWithOptions approach. Include auth, balance into the products array.
   When the account is successfully linked, you will access the account balance of your customers, and also receive notification about the successful event to your webhook, if you have subscribed to it.

import Okra from 'okra-js'

Okra.buildWithOptions({
    name: 'Your company',
    env: 'production-sandbox',
    app_id: ''// app_id from your app builder
    key: '', // Your key from the Okra dashboard
    webhook_url: ''// Your webhook url
    token: '', // Your token from the okra dashboard
    products: ['auth', 'balance'], //in lowercase
    showBalance: true;
    onSuccess: function(data){
        console.log('options success', data)
    },
    onClose: function(){
        console.log('options close')
    }
})

How to check the balance via the API

You can easily understand if a user's balance has changed before making calls to get a real-time balance.

1. Make a POST request to https://api.okra.ng/v2/balance/check with the account_id

curl -X POST https://api.okra.ng/v2/balance/check
-H 'Content-Type: application/json' 
-H 'Authorization: Bearer <secretKey>'
-d '{ 
			account_id: "xxxxxxxxxxxx" 
		}'

2. After two minutes, make a GET request to data.callback_url in the response in step 1

curl -X GET https://api.okra.ng/v2/callback?record={recordId}&method=CHECK_BALANCE
-H 'Content-Type: application/json' 
-H 'Authorization: Bearer <secretKey>'

{
    "status": "success",
    "message": "Successfully checked balance",
    "data": {
        "balance_changed": false,
        "last_checked": "2021-07-16T14:20:05.968Z",
        "last_fetched": "2021-07-15T01:02:01.615Z"
    }
}

📘

Add a debounce of about 60 seconds to accommodate for banks with duplicate delays

Balance callback

When you refresh balance, the response is not instantaneous because we must interact with the customer's financial institution. As a result, you will receive a callback_url as in the JSON response example below. You can view an example on how to handle the response and retrieve the balance in real time.

Check the API Reference to see how it works.

exports.fetchBalance = async (req, res, next) => {
    req.setTimeout(0)
    const baseURL = 'https://api.okra.ng/v2' 
    const { account_id, waitTime } = req.body //waitTime is in minutes
    const token = `Your_JWT_token`
    let config = {
        headers: {
            'Content-Type': 'application/json',
            Authorization: `Bearer ${token}`
        }
    }
    const getBalanceReq = () => {
        try {
            return axios.post(`${baseURL}/balance/refresh`, { account_id: account_id },config)
        } catch (error) {
            console.error(error)
        }
    }
    const getCallBackData = (data) => {
        try {
            return axios.get(data, config)
        } catch (error) {
            console.error(error)
        }
    }
    const getCallBackReq = async () => {
        getBalanceReq()
            .then(async response  => {
                if (response.data.data) {
                    await waitFor(waitTime * 60000) // covert minutes to milliseconds
                    return [ response.data.data.callback_url.replace("undefined", "callback")].join('')
                }
            }).then(callBack => {
                getCallBackData(callBack)
                    .then(response => {
                       res.json(response.data)
                    })
                    .catch(error => {
                        console.log(error)
                    })
            })
            .catch(error => {
                console.log(error)
            })
    }
    getCallBackReq()
}

const waitFor = (ms) => new Promise(r => setTimeout(r, ms))

{
    "status": "success",
    "message": "Successfully checked balance",
    "data": {
        "balance_changed": true,
        "last_checked": "Fri Jan 01 2021 21:25:05 GMT-0500"
    }
}

Current and periodic balance

Balance typically returns both ledger and available balance information. For fraud detection and insufficient funds (NSF) prevention use cases, the available balance should be used, as it represents the predicted balance net of any pending transactions, while the ledger balance does not take pending transactions into account.

Available balance indicates the balance that is available to spend, which is not the same as the overall value of the account. In some cases, a financial institution may not return available balance information.

If that happens, you can calculate the available balance by starting with the current balance, then using our Transaction product to detect any pending transactions and adjust the balance accordingly.

🚀Now that you understand how the balance works, check out the API Reference) page to test the balance API in real-time.