Refresh Balance

Learn how you could refresh your balance on our dashboard

Fetch Real-time Balance

Our Balance product allows you to obtain real-time balance information. When you call any product endpoint, balance data is one of the pieces of information returned as part of the account object. However, this data is saved when you make the initial request for your user and is not suitable for situations where you need real-time balance information. In order to receive up-to-the-minute balance data, you will need to call the /balance/refresh endpoint. This real-time balance data can be helpful when checking to see if an account has sufficient funds before using it as a funding source for a money transfer, such as one made via Auth.

curl -X POST https://api.okra.ng/v2/balance/refresh
-H 'Content-Type: application/json' 
-H 'Authorization: Bearer <secretKey>'
'{
    "account_id":"Account ID"
}'
{
    "status": "success",
    "message": "Balance checking...",
    "data": {
        "callback_url": "https://api.okra.ng/v2/callback?record=60b0bba673ffb32cdf4b972b&method=BALANCE",
        "record": "60b0bba673ffb32cdf4b972b",
        "method": "BALANCE"
    }
}

Balance Callback

When you refresh the 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 of how to handle the response and retrieve the balance in real-time.
Check out our 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"
    }
}

Check if Balance Has Changed (FREE)

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

How to check the 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: "5fe0a6f8ee69d878a679ef39" 
        }'
{
    "status": "success",
    "message": "Balance checking...",
    "data": {
        "callback_url": "https://api.okra.ng/v2/callback?record=60f19595dfa83247a9e12466&method=CHECK_BALANCE",
        "record": "60f19595dfa83247a9e12466",
        "method": "CHECK_BALANCE"
    }
}
  1. 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": 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 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 adjusting the balance accordingly. You can also view the balance at each transaction by using our Enhanced Balance product.


What's Next

Check out our Account endpoints

Did this page help you?