Fetch balance
Fetch your customer’s bank balance in real-time
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.
Field | Description |
---|---|
idObjectID | Unique Auth ID (Unique Okra Identifier) |
available_balanceNumber | Amount of Available Funds in the Account |
ledger_balanceNumber | The Closing Balance of the Account |
accountObjectID | Unique Account ID (Unique Okra Identifier) |
connectedBoolean | Customer Connection Status (Did they Choose to Connect this Account to You?) |
customerObjectID | Unique Customer ID (Unique Okra Identifier) See Manage Customers ] |
recordObjectID | Unique Record ID (Unique Okra Identifier) See Records |
ownerObjectID | Unique Company ID (Unique Okra Identifier) (Your Client Token) |
envString | Okra API Env the Auth was Pulled from production or production-sandbox |
created_atDate | Date of Authentication |
last_updatedObject | Last Date of Authentication |
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.
- Install the
okra-js
package by runningnpm install okra-js
- Use the
buildWithOptions
approach. Includeauth, balance
into theproducts
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.
- Make a
POST
request tohttps://api.okra.ng/v2/balance/check
with theaccount_id
curl -X POST https://api.okra.ng/v2/balance/check
-H 'Content-Type: application/json'
-H 'Authorization: Bearer <secretKey>'
-d '{
account_id: "xxxxxxxxxxxx"
}'
- After two minutes, make a
GET
request todata.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.
Updated 7 months ago