Refresh balance

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"
    }
}

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

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"
    }
}

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.