Welcome to Blnk
The open-source backend for building fintech products at scale.
This is your guide to getting started with Blnk, pronounced as /blank/
. If you are new to Blnk or open-source fintech developer tools, this is where you should start.
Here is your start kit: ✨
1. Install Blnk
2. Launch Blnk
3. Create your first ledger
4. Create your first balance
5. Record your first transaction
6. Run your first reconciliation
What is Blnk?
Blnk offers an open-source financial ledger database for building and scaling fintech products. With Blnk, you can:
- Accurately record transactions in your system.
- Correctly manage complex flow of funds and transaction data.
- Reliably manage the size of your transactions as your product scales.
1. Install Blnk on your machine
To install Blnk, make sure you have Docker and Compose installed and running on your machine.
To get started with Blnk, first clone the repository into your machine:
Next, create a configuration file, blnk.json
:
Then copy and save the following configuration:
2. Launch Blnk
Start your Blnk server with Docker compose:
If successful, you should be able to access your server on the following URL:
3. Create your first ledger
Everything in Blnk begins with a ledger. Ledgers are used to group and manage how you arrange your ledger balances in our application.
When you install Blnk, an internal ledger called the General Ledger is created for you. This is a ledger meant for grouping all of the balances directly owned by your organization, e.g., Revenue, Fees, etc.
However, to create, store and represent balances for accounts/wallets owned by the users in your application, it is required to create ledgers to group them in.
To create a ledger, call the create-ledger endpoint:
With the following request body:
Field | Description | Required | Type |
---|---|---|---|
name | A name that best describes the function of the ledger | Yes | string |
meta_data | Custom data associated with the ledger being created | No | object |
Next, you can view a list of all your ledgers:
4. Create your first balance
Ledger balances (or balances for short) are used to represent store of value in a fintech application, e.g., wallet, account, card balance, etc. They represent the source or destination of a transaction record.
To create a balance, call the create-balance endpoint:
With the following request body:
Field | Description | Required | Type |
---|---|---|---|
ledger_id | The unique id of the ledger that this balance belongs to. | Yes | string |
currency | The currency in which transactions recorded in this balance will be recorded. | Yes | string |
meta_data | Custom data associated with the balance being created | No | object |
Next, to view a list of all your balances:
5. Record your first transaction
Transactions represent all financial activities happening in your application. Blnk uses the double entry principle to record transactions, i.e., to successfully record a transaction, there must be a source and a destination.
To record a transaction, call the record-transaction endpoint:
With the following request body:
Field | Description | Required | Type |
---|---|---|---|
amount | The transaction amount. | Yes | float |
reference | Your unique reference to ensure idempotency. | Yes | string |
currency | Short code for your asset class. See also: Asset classes | Yes | string |
precision | Precision for the currency/asset passed. See also: Precision | No | int64 |
source | Sender’s balance ID | Yes | string |
destination | Recipient’s balance ID. | Yes | string |
description | Description or narration of the transaction. | No | string |
meta_data | Custom data associated with the transaction | No | object |
Passing detailed data with the meta_data
object is encouraged; it provides you with 360-degree insights about each transaction record. Examples of data you can pass include sender_name
, account_number
, bank_name
, receiver_name
, payment_id
, ip_address
, location
, payment_method
, etc.
Next, you can view a list of all transactions in your ledger:
Transaction properties
-
Immutability: All transactions in Blnk are immutable. Once they have been recorded, they cannot be altered or tampered with. This ensures the accuracy and unchangeability of the transaction record. See also: Transaction hashing
-
Idempotency: All transactions in Blnk are idempotent. This ensures that performing the same operation multiple times results in the same outcome as doing it once. This property is crucial for maintaining consistent outcomes regardless of how many times a transaction is repeated, especially in scenarios where network errors or other issues might cause transaction failures.
Blnk ensures idempotency through the use of a unique reference
for every transaction. This is why it is required for you to provide one when recording a transaction.
Notifications
Notifications are sent via webhook events to let you know the updated status of a transaction:
-
transaction.applied
: This event is sent when a transaction has been processed and applied to the participating balances. It signifies the completion of a transaction’s lifecycle. -
transaction.inflight
: This event is sent when a transaction’s status has been updated toINFLIGHT
and is waiting for a certain condition to be met, as defined by your application. See also: Inflight transactions -
transaction.rejected
: This event is sent when a transaction is rejected because all of the conditions required to process it wasn’t met.
6. Run your first reconciliation
Reconciliation is a vital component of financial operations, essential for maintaining precise and reliable financial records.
This process involves comparing and matching internal records (your ledger) with external statements (such as payment processor reports and bank statements) to identify and rectify any discrepancies. The primary goal of reconciliation is to ensure that all records accurately represent the company’s financial position at all times.
To get started:
- Upload external data: Import external data from payment processor reports and bank statements, and prepare them for reconciliation.
- Set matching rules: Define how transactions should be compared and matched.
- Define reconciliation strategies: Choose what type of reconciliation strategy you want to apply.
- Run reconciliation: Initiate a reconciliation.
Learn more
Use cases
Here’s some of what you can build with Blnk:
Need help?
We are very happy to help you make the most of Blnk, regardless of whether it is your first time or you are switching from another tool.
To ask questions or discuss issues, please join our Discord community.
Was this page helpful?