Overview
Transactions enable money movement between two or more balances. These can be payments, transfers, settlements, internal treasury management, etc. All transactions in Blnk are recorded with the double entry principle — every transaction has a source and a corresponding destination. Transactions happen between balances, and balances are created within ledgers. In this guide, you’ll learn about:Transaction properties
- Immutability: Once recorded, transactions in Blnk cannot be modified or deleted. This fundamental property ensures the integrity and reliability of your transaction history, preventing any unauthorized alterations. See also: Transaction hashing
-
Idempotency: Each transaction in Blnk produces the same result whether executed once or multiple times. This is crucial for maintaining data consistency, especially during network failures or system retries.
Blnk implements idempotency by requiring a unique
reference
for every transaction. This reference serves as a transaction identifier, preventing duplicate processing and ensuring consistent outcomes.
Recording a transaction
To record a transaction, call the record-transaction endpoint:If this is your first transaction, the participating balances will start at 0. To ensure the transaction is successful, enable overdrafts as shown above, allowing the source balance to go negative.Learn more about Overdrafts and Negative Balances.
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.bash
Verifying transactions
After recording a transaction, you can verify its status using different methods depending on whether you’re using the default queue system or the skip queue feature.Verifying transactions with queue (default)
When using the default queue system, every transaction starts asQUEUED
. To verify your transaction status, you have two options:
- Webhooks: Blnk sends webhook notifications when transaction states change.
- Direct API calls: Query the transaction status using the reference or transaction ID. See below:
Verifying transactions without queue (skip queue)
When usingskip_queue: true
, transactions are processed immediately and you can verify them from the direct response. Learn more about skip queue.
INFLIGHT
, APPLIED
, or REJECTED
), allowing you to confirm the transaction result without waiting for webhooks or additional API calls.
When using
skip_queue: true
, you may encounter lock errors if multiple transactions are processed simultaneously on the same balance. Learn how to handle these scenarios in our Handling Hot Balances guide.Discarded transactions
A discarded transaction is not recorded in the ledger. Blnk discards transactions for one reason:- Duplicate reference: Your new transaction
reference
matches an existingreference
in your ledger. Blnk requires uniquereference
values per transaction. Options are timestamps (e.g. UNIX timestamp), random string or UUID (e.g.ref_e55c4f33-bff7-4c30-9b9f-5d2d10a29b7a
), or a business identifier like anorder_id
.
Make sure your request body match the Blnk Ledger API specifications. For example, avoid passing
apply_overdraft
instead of allow_overdraft
.Managing insufficient funds
Available in version 0.11.0 and later. For versions 0.10.8 and older, see our insufficient funds guide.
balance - inflight_debit_balance
on the source balance.
Inflight debit balance is the amount waiting to be deducted from the source balance from inflight transactions. Learn more: Inflight transactions.
- The transaction is rejected and status is recorded as
REJECTED
. - A webhook notification to inform your system of the rejected transaction and a reason in its
meta_data
.
Using overdrafts
If you want a transaction to proceed even when it exceeds the available balance, you can enable overdrafts by settingallow_overdraft: true
in your transaction request.
Learn about overdrafts
Detailed guide on managing overdrafts and negative balances
Dive deeper
Transaction lifecycle
Learn how transactions move through different states from creation to completion
Understanding precision
Master decimal handling and precision for accurate financial calculations
Transaction statuses
Understand what each transaction status means and when they occur