Transactions are used to 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, i.e., there is a source and a corresponding destination for each transaction entry.

In this guide, you’ll learn:

  1. Transaction properties
  2. How transactions work in Blnk
  3. Recording a transaction

​
Transaction properties

  1. 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

  2. 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.

​
How transactions work in Blnk

1

Queueing transactions

When you record a transaction, Blnk places it in a temporary QUEUED status as part of its concurrency control mechanism. This queueing step ensures accuracy and maintains transaction idempotency.

A queued transaction typically processes within milliseconds, reaching either an APPLIED or REJECTED status.

See following: How Blnk handles concurrency

2

Applying transactions

A transaction reaches APPLIED status when it has been successfully processed and all participating balances have been updated accordingly.

To verify a successful transaction, look up its unique reference or transaction id in your ledger.

See also: Inflight statuses

3

Rejecting transactions

A transaction usually enters REJECTED status due to insufficient funds, i.e., when the source balance lacks sufficient funds and overdraft is not enabled for the transaction.

4

Discarded transactions

When a transaction is discarded, it was queued but never reached a final APPLIED or REJECTED status. Discarded transactions are removed from the queue and do not appear in the ledger. No webhook notification is sent for discarded transactions.

A transaction can be discarded for any of these reasons:

  1. Duplicate reference: The transaction’s reference number matches an existing transaction record in your ledger, violating idempotency requirements. We recommend generating unique references using a combination of:

    • Timestamp (e.g. UNIX timestamp)
    • Random string or UUID
    • Business identifier (like orderID or customerID)

  2. Incorrect attributes: The transaction request contains invalid or missing required attributes. For example, passing apply_overdraft instead of allow_overdraft, invalid amounts (like negative values), etc.

    To avoid this, double-check that all transaction requests match the API specifications before submitting.

​
Recording a transaction

To record a transaction, call the record-transaction endpoint:

POST http://YOUR_BLNK_INSTANCE_URL/transactions

With the following request body:

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.

Response
{
    "id": "txn_6164573b-6cc8-45a4-ad2e-7b4ba6a60f7d",
    "source": "@FundingPool",
    "destination": "bln_ebcd230f-6265-4d4a-a4ca-45974c47f746",
    "reference": "ref_001adcfgf",
    "amount": 750,
    "precision": 100,
    "precise_amount": 75000,
    "currency": "USD",
    "description": "Fund with starting balance amount",
    "status": "QUEUED",
    "created_at": "2024-12-21T01:36:46.997063436Z",
    "meta_data": {
      "sender_name": "John Doe",
      "sender_account": "00000000000"
    }
}
FieldDescriptionRequiredType
amountThe transaction amount.Yesfloat
referenceYour unique reference to ensure idempotency.Yesstring
currencyShort code for your asset class. See also: Asset classesYesstring
precisionPrecision for the currency/asset passed. See also: PrecisionNoint64
sourceSender’s balance IDYesstring
destinationRecipient’s balance ID.Yesstring
descriptionDescription or narration of the transaction.Nostring
meta_dataCustom data associated with the transactionNoobject

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:

bash
blnk transactions list

​
Learn more

Understanding precision

Transaction statuses

Inflight transaction

​
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 contact us or join our Discord community.

Get access to Blnk Cloud.

Manage your Blnk Ledger and explore advanced features (access control & collaboration, anomaly detection, secure storage & file management, etc.) in one dashboard.

Was this page helpful?

Suggest edits
Closing balancesStatuses