Verify customers account balances in real-time, so you can guarantee successful payments.


The Balance API enables you to retrieve a user's current and historic balance information when they connect their bank accounts in your application.

Verifying your users' account balance is key to reducing the risk of returned payments and preventing transaction failures. Ensure that your users have the funds available to enjoy your services and reduce the possibility of NSF fees and overdrafts. Use the Balances API to make informed decisions while delivering a frictionless customer experience.

How it works

During an account connection flow, the Okra API creates a balance record based on the user's account data. You can view balance records in the Okra Dashboard or via the Balance API endpoints.

The Balance endpoints return both ledger and available balance information. For fraud detection and insufficient funds (NSF) prevention use cases, you can utilize the available balance, as it represents the predicted net balance of pending transactions, while the ledger balance does not take pending transactions into account.

Available balance indicates the balance that is available to spend, which may be different from overall value of the account.

A financial institution may not return available balance information. In this case, you can calculate the available balance for a user by enabling the Transactions product in your app. Based on the Transactions data, you can adjust a user's current balance with the value of any pending transactions retrieved via the /transactions endpoint.

How to use

You can add the Balance product to your application in just a few simple steps:

  1. Build your Okra app using the App Builder. When selecting the products that you want to retrieve user data for, make sure that you enable Balance. Check out the Build your app guide for more details.
  2. Embed the app you created into your website or application. Okra recommends that you do this through integrating with one of the available Libraries or SDKs - check out the Embed your app guide for more details.

Here is an example snippet for embedding the Okra app using OkraJS SDK and the buildWithOptions method, with the Balance product enabled:

import Okra from 'okra-js'

      name: '{Your app name}',
      env: 'production',
      key: '{Your API key, according to the environment you use}',
      token: '{Your Client token}',
      callback_url: '', // Specify a URL where Okra can send webhook notifications.
      redirect_url: '', // Specify a URL to redirect your users to the next step in your application's workflow.
      products: ['auth', 'balance'], // Define the array of products that you want to enable.
      showBalance: true, // Display the account balance to your users. 
      currency: 'NGN',
      logo: '' // Your company logo.
      onSuccess: function(data){
          console.log('success', data)
      onClose: function(){

You can use the same buildWithOptions method when you build your app via the API instead of integrating directly with Okra's libraries or SDKs.

After you have enabled Balance in your app, the Okra API will create balance records for users who connect their bank accounts via this specific app.

You can view balance records in the Okra Dashboard or via the API. Use these endpoint operations to retrieve balance records programmatically:

Both operations retrieve information that was valid in the moment when the balance record was created. To retrieve up-to-date balance information from users who already connected their accounts, you can create a Returning User Experience flow. Check out the RUX guide for more details.

Need help?

New to Okra? Get started here.

  1. If you have any questions about Okra's products or way of working, get in touch with the Support team.
  2. If you have technical questions or need help with your code, join Okra's Developer Community on Slack.

Was this page helpful?