Balance

Verify Your Customer’s Bank Balance in Real-time.

📘

Need to Reduce NSF (insufficient) Fund Errors?

With Okra you can check your customer's bank account balance before you initiate a payment. This allows you to capture payments seamlessly without having to worry about insufficient funds.

Overview

Okra allows you to retrieve current and historical balance information from your customer. Use OkraJS to instantly authenticate your customer's account and automatically fetch their available and ledger balances. Being able to view their historical balance information gives you a true understanding of your customer’s average bank balance. Verifying an account balance is key to reducing the risk of returned payments and preventing transaction failures.

With our Balance product, you can notify your customer of low funds, so they can choose an alternate payment method and move forward seamlessly.

Read more about Balance @ get.okra.ng/balance-deck.

👍

Refresh Balance in real-time!

Need to know your customer's most recent available balance? Easily Refresh Balance on any of their accounts connected to you.

Reduce Failures and Verify Funds

Whether you need to validate a user’s spending power or ability to pay, we provide access to the necessary balance information needed for your business to make informed decisions.

Real-time balance ensures that your user has the funds available to enjoy your services and reduces the possibilities of NSF fees and overdrafts. Retrieving balances instantly means you can reduce the risk to your business while delivering frictionless customer experience.

It only takes seconds to access real-time balances and get the insights you need.
You can choose a standard payment — where you will receive an NSF if the account balance is less than the payment amount, with the ability to check and charge later. You can also opt to garnish the payments. With this option, you can automatically adjust the payment to match the customer’s current available balance and collect the remaining payment amount once available.

Balance Model

A description of all the fields in the balance model

Field

Description

id
ObjectID

Unique Auth ID (Unique Okra Identifier)

available_balance
Number

Amount of Available Funds in the Account

ledger_balance
Number

The Closing Balance of the Account

account
ObjectID

Unique Account ID (Unique Okra Identifier)

connected
Boolean

Customer Connection Status (Did they Choose to Connect this Account to You?)

customer
ObjectID

Unique Customer ID (Unique Okra Identifier)

See Manage Customers ]

record
ObjectID

Unique Record ID (Unique Okra Identifier)

See Records

owner
ObjectID

Unique Company ID (Unique Okra Identifier) (Your Client Token)

env
String

Okra API Env the Auth was Pulled from production or production-sandbox

created_at
Date

Date of Authentication

last_updated
Object

Last Date of Authentication

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 processing...",
    "data": {
        "callback_url": "https://api.okra.ng/v2/callback?record=60f193d7dfa83247a9e122c8&method=BALANCE",
        "record": "60f193d7dfa83247a9e122c8",
        "method": "BALANCE"
    }
}

📘

NOTE

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.
Checkout 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" 
        }'
  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": false,
        "last_checked": "2021-07-16T14:20:05.968Z",
        "last_fetched": "2021-07-15T01:02:01.615Z"
    }
}

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 adjusting the balance accordingly. You can also view the balance at each transaction by using our Enhanced Balance product.

For an overview of all the balance endpoints visit the API Reference


What's Next
Did this page help you?