​
Overview

This guide shows you how to create and connect a balance to an existing ledger. A Balance represents the source or destination of a transaction record.

The Blnk Ledger is designed based on the Double Entry Accounting Principle; this means that all transactions must have a source (credit record) and a destination (debit record)

Balances are always updated whenever a new transaction is recorded, and they can be used to track the flow of funds within your application ensuring that your books are always balanced.

Every Balance is made up of 3 sub-balances:

  1. Credit balance: Total sum of all credits that’s happened on a balance.
  2. Debit balance: Total sum of all debits that’s happened on a balance.
  3. Total balance: Calculated by subtraction the Debit balance from the Credit balance.

​
Create a balance

1

Create a ledger

You cannot create a Balance without an existing ledger. If you do not have a ledger created yet, click here to create one.

2

Create a balance

Call the create-balance endpoint and provide the required fields.

{
    "ledger_id": "ldg_073f7ffe-9dfd-42ce-aa50-d1dca1788adc",
    "currency": "USD",
	"meta_data": {
		"first_name": "John",
		"last_name": "Doe",
		"account_number": "1234567890"
	}
}
FieldDescriptionRequiredType
ledger_idThe unique id of the ledger that this balance belongs toYesstring
currencyThe currency in which transactions recorded in this balance will be recordedYesstring
meta_dataCustom data associated with the balance being createdNoobject

Do not use one balance to record transactions with different currency values. When recording transactions in a particular balance, The Blnk Ledger assumes all transactions in that balance have the same currency value.

3

Your balance gets created

Once your Balance has been created, you can move on to record your first transaction in your Blnk Ledger.

response
{
    "balance_id": "bln_0be360ca-86fe-457d-be43-daa3f966d8f0",
	"balance": 0,
	"version": 0,
	"inflight_balance": 0,
	"credit_balance": 0,
	"inflight_credit_balance": 0,
	"debit_balance": 0,
	"inflight_debit_balance": 0,
	"precision": 0,
	"ledger_id": "ldg_073f7ffe-9dfd-42ce-aa50-d1dca1788adc",
	"identity_id": "",
	"indicator": "",
	"currency": "NGN",
	"created_at": "2024-02-20T05:33:01.311600208Z",
	"inflight_expires_at": "0001-01-01T00:00:00Z",
	"meta_data": {
		"first_name": "John",
		"last_name": "Doe",
		"account_number": "1234567890"
	}
}
FieldDescriptionType
balance_idThe unique id of the balance you created.string
balanceSum of credit_balance and debit_balance.int64
inflight_balanceSum of inflight_credit_balance and inflight_debit_balance.int64
credit_balanceSum of all credit transaction amounts in the balance.int64
inflight_credit_balanceTotal amount waiting to be added to your balance.int64
debit_balanceSum of all debit transaction amounts in the balance.int64
inflight_debit_balanceTotal amount waiting to be deducted from your balance.int64
inflight_expires_atDate and time for inflight to expire.string
created_atDate and time of creation.string

​
View your balance

To view the details of a particular balance in your Blnk Ledger, call the Get Balance endpoint URL — /balance/[balance_id]. Provide the balance_id to fetch the details of a specific balance in real time.

See also → Search your Blnk data.

​
See also

Understanding precision

Improve the correctness of your ledger

​
Need help?

Are you stuck? Do you have a question that isn’t answered in this doc? Have you run into a problem you can’t solve? Want to file a bug report?

Join our Discord server and share your questions/thoughts with other developers building financial applications like you.

Was this page helpful?

Suggest edits