​
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:
  1. Transaction properties
  2. Recording a transaction
  3. Verifying transactions

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

​
Recording a transaction

To record a transaction, call the record-transaction endpoint: 
POST http://YOUR_BLNK_INSTANCE_URL/transactions
With the following request body: 
curl -X POST "http://YOUR_BLNK_INSTANCE_URL/transactions" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 750,
    "reference": "ref_001adcfgf",
    "currency": "USD",
    "precision": 100,
    "source": "@FundingPool",
    "destination": "bln_ebcd230f-6265-4d4a-a4ca-45974c47f746",
    "description": "Fund with starting balance amount",
    "allow_overdraft": true,
    "skip_queue": false,
    "meta_data": {}
  }'
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.
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

​
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 as QUEUED. To verify your transaction status, you have two options:
  1. Webhooks: Blnk sends webhook notifications when transaction states change.
  2. Direct API calls: Query the transaction status using the reference or transaction ID. See below:
curl -X POST "http://YOUR_BLNK_INSTANCE_URL/search/transactions" \
  -H "Content-Type: application/json" \
  -d '{
    "q": "<transaction-reference>",
    "query_by": "reference"
  }'

​
Verifying transactions without queue (skip queue)

When using skip_queue: true, transactions are processed immediately and you can verify them from the direct response. Learn more about skip queue. 
curl -X POST "http://YOUR_BLNK_INSTANCE_URL/transactions" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 750,
    "reference": "ref_001adcfgf",
    "currency": "USD",
    "precision": 100,
    "source": "@FundingPool",
    "destination": "bln_ebcd230f-6265-4d4a-a4ca-45974c47f746",
    "description": "Fund with starting balance amount",
    "allow_overdraft": true,
    "skip_queue": true
  }'
The response immediately shows the final status (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:
  1. Duplicate reference: Your new transaction reference matches an existing reference in your ledger. Blnk requires unique reference 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 an order_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

You can manage insufficient funds scenarios in two ways: through automatic rejection handling when transactions are attempted with insufficient balance, and through proactive balance checking before initiating transactions.

​
1. Automatic rejection

When a transaction is posted where the source balance has insufficient funds, Bink automatically handles this scenario to maintain ledger integrity. Blnk:
  1. Rejects the transaction.
  2. Records this rejection in your ledger using the same state tracking mechanism (i.e. QUEUED → REJECTED). Learn more about transaction lifecycle.
  3. Sends a webhook notification to inform your system of the state change and new ledger record.
You can also preemptively track the transaction status (via reference or parent_transaction) to know if the transaction was successful or rejected.

​
2. Proactive balance verification

Instead of waiting for a transaction.rejected webhook, you can implement a preemptive available balance check in your workflow. Here’s how: First, query the balance of the sender using:
cURL
curl -X GET 'http://YOUR_BLNK_INSTANCE_URL/balances/{balance_id}?with_queued=true' \
  -H 'Authorization: Bearer YOUR_API_KEY'
Next, calculate your available balance: 
available_balance = balance - queued_debit_balance
  • If the available balance is sufficient, proceed with posting your transaction.
  • If the available balance is insufficient, you can gracefully handle this scenario in your application by notifying the customer immediately, avoiding the need for webhook handling.

Queued balances

Learn how queued balances work

​
Insufficient funds for inflight transactions

For a detailed understanding of how insufficient funds can be managed in inflight scenarios, please refer to our Applying inflight guide.

​
Dive deeper

Transaction lifecycle

Understanding precision

Transaction statuses

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