About Transactions

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
Recording a transaction
Verifying transactions

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:

curl -X POST "http://YOUR_BLNK_INSTANCE_URL/transactions" \
  -H "X-blnk-key: <api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "precise_amount": 75000,
    "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
  }'

const response = await blnk.Transactions.create({
  precise_amount: 75000,
  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,
});

transaction, resp, err := client.Transaction.Create(blnkgo.CreateTransactionRequest{
    ParentTransaction: blnkgo.ParentTransaction{
        PreciseAmount: big.NewInt(75000),
        Reference: "ref_001adcfgf",
        Currency: "USD",
        Precision: 100,
        Source: "@FundingPool",
        Destination: "bln_ebcd230f-6265-4d4a-a4ca-45974c47f746",
        Description: "Fund with starting balance amount",
    },
    AllowOverdraft: true,
})

response = blnk.transactions.create({
  "precise_amount": 75000,
  "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,
})

ApiResponse<JsonNode> response = blnk.transactions().create(
    CreateTransactions.create()
        .preciseAmount(75000)
        .reference("ref_001adcfgf")
        .currency("USD")
        .precision(100)
        .source("@FundingPool")
        .destination("bln_ebcd230f-6265-4d4a-a4ca-45974c47f746")
        .description("Fund with starting balance amount")
        .allowOverdraft(true));

blnk transactions create

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"
    }
}

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.

To preview the same request without writing a transaction, set dry_run to true. See Dry-run transactions.

Request
Response

Field	Description	Required	Type
`precise_amount`	Transaction amount in its smallest unit (recommended). Send either `precise_amount` or `amount`, not both - see Precision.	Yes	`integer`
`amount`	Transaction amount as a float. Blnk multiplies by `precision` to store `precise_amount`.	Yes	`float`
`reference`	Your unique reference to ensure idempotency.	Yes	`string`
`currency`	Short code for your asset class.	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`

Field	Description	Type
`amount`	The transaction amount.	Yes	`float`
`reference`	Your unique reference to ensure idempotency.	Yes	`string`
`currency`	Short code for your asset class.	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`
`id`	Unique id for the transaction. This is generated by Blnk.	`string`
`precise_amount`	The transaction amount recorded after the `precision` value has been applied. See also: Precision	`integer`
`status`	Current state of your transaction record. See also: Transaction statuses	`string`
`created_at`	Date and time of the transaction record.	`string`

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.

Verifying transactions with queue enabled

When using the default queue system, every transaction starts as QUEUED. 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:

By reference (direct endpoint)
By reference (search)
By transaction ID

Blnk appends a _q suffix to your original reference after processing a QUEUED transaction. To verify the updated status, retrieve the transaction using your original reference plus the _q suffix.

curl -X GET "http://YOUR_BLNK_INSTANCE_URL/transactions/reference/{reference}" \
  -H "X-blnk-key: <api-key>"

Response

{
  "transaction_id": "txn_6164573b-6cc8-45a4-ad2e-7b4ba6a60f7d",
  "reference": "ref_001adcfgf",
  "status": "APPLIED"
}

Use the Search API to look up your transaction by reference. If the transaction exists, the response will include its current status.

curl -X POST "http://YOUR_BLNK_INSTANCE_URL/search/transactions" \
  -H "Content-Type: application/json" \
  -d '{
    "q": "<transaction-reference>",
    "query_by": "reference"
  }'

const response = await blnk.Search.search(
  { q: '<transaction-reference>', query_by: 'reference' },
  'transactions',
);

results, resp, err := client.Search.SearchDocument(
  blnkgo.SearchParams{
    Q:       "<transaction-reference>",
    QueryBy: "reference",
  },
  blnkgo.Transactions,
)

response = blnk.search.search(
  {"q": "<transaction-reference>", "query_by": "reference"},
  "transactions",
)

ApiResponse<JsonNode> response = blnk.search().search(
    SearchParams.create()
        .q("<transaction-reference>")
        .queryBy("reference"),
    "transactions");

Response

{
  "found": 1,
  "hits": [
    {
      "document": {
        "transaction_id": "txn_6164573b-6cc8-45a4-ad2e-7b4ba6a60f7d",
        "reference": "ref_001adcfgf",
        "status": "APPLIED"
      }
    }
  ]
}

To check the updated status, take the queued transaction ID and search with it as the parent_transaction. This is because Blnk treats the queued transaction as the parent for the next transaction state. See also: Transaction lifecycle

curl -X POST "http://YOUR_BLNK_INSTANCE_URL/search/transactions" \
  -H "Content-Type: application/json" \
  -d '{
    "q": "<queued-transaction-id>",
    "query_by": "parent_transaction"
  }'

const response = await blnk.Search.search(
  { q: '<queued-transaction-id>', query_by: 'parent_transaction' },
  'transactions',
);

results, resp, err := client.Search.SearchDocument(
  blnkgo.SearchParams{
    Q:       "<queued-transaction-id>",
    QueryBy: "parent_transaction",
  },
  blnkgo.Transactions,
)

response = blnk.search.search(
  {"q": "<queued-transaction-id>", "query_by": "parent_transaction"},
  "transactions",
)

ApiResponse<JsonNode> response = blnk.search().search(
    SearchParams.create()
        .q("<queued-transaction-id>")
        .queryBy("parent_transaction"),
    "transactions");

Response

{
  "found": 1,
  "hits": [
    {
      "document": {
        "transaction_id": "txn_6164573b-6cc8-45a4-ad2e-7b4ba6a60f7d",
        "parent_transaction": "txn_6164573b-6cc8-45a4-ad2e-7b4ba6a60f7d",
        "status": "APPLIED"
      }
    }
  ]
}

Verifying transactions without queue disabled

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 "X-blnk-key: <api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "precise_amount": 75000,
    "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
  }'

const response = await blnk.Transactions.create({
  precise_amount: 75000,
  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,
});

transaction, resp, err := client.Transaction.Create(blnkgo.CreateTransactionRequest{
    ParentTransaction: blnkgo.ParentTransaction{
        PreciseAmount: big.NewInt(75000),
        Reference: "ref_001adcfgf",
        Currency: "USD",
        Precision: 100,
        Source: "@FundingPool",
        Destination: "bln_ebcd230f-6265-4d4a-a4ca-45974c47f746",
        Description: "Fund with starting balance amount",
        SkipQueue: true,
    },
    AllowOverdraft: true,
})

response = blnk.transactions.create({
  "precise_amount": 75000,
  "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,
})

ApiResponse<JsonNode> response = blnk.transactions().create(
    CreateTransactions.create()
        .preciseAmount(75000)
        .reference("ref_001adcfgf")
        .currency("USD")
        .precision(100)
        .source("@FundingPool")
        .destination("bln_ebcd230f-6265-4d4a-a4ca-45974c47f746")
        .description("Fund with starting balance amount")
        .allowOverdraft(true)
        .skipQueue(true));

Response

{
  "id": "txn_6164573b-6cc8-45d4-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": "APPLIED",
  "created_at": "2024-12-21T01:36:46.997063436Z",
  "meta_data": {}
}

With skip_queue: true, a successful request immediately returns an INFLIGHT or APPLIED transaction. If the source has insufficient funds, see Managing insufficient funds.

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

Some requests are not recorded in the ledger. Common reasons include:

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.
Zero amount: Your transaction amount is 0. Zero amounts are not recorded in the Blnk ledger.
Insufficient funds with skip_queue: true: The rejected attempt is not recorded. See Managing insufficient funds.

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.

Blnk performs comprehensive balance checks before processing any transaction to ensure you have sufficient funds available. The system computes an available balance by calculating 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: Create inflight. If the transaction amount is more than the available balance, the outcome depends on how Blnk processes the request.

Default queue

The API first returns a QUEUED transaction. The worker then records a separate REJECTED transaction. That record uses parent_transaction to point back to the queued transaction, and stores the reason in meta_data.blnk_rejection_reason. Blnk sends a transaction.rejected webhook for the rejected record. With the default queue configuration, this happens on the first failure. If insufficient-fund retries are enabled, Blnk retries first and records REJECTED only after those retries are exhausted.

Skip queue

When skip_queue: true, Blnk processes the request immediately and returns 400 TXN_INSUFFICIENT_FUNDS. The rejected attempt is not recorded, so the reference is not used. You can retry the same reference after the source has enough funds.

If you want a transaction to proceed even when it exceeds the available balance, you can enable overdrafts by setting allow_overdraft: true in your transaction request. Learn more.

Dive deeper

Dry-run transactions

Preview balances without writing a transaction.

Transaction lifecycle

States from creation through completion.

Understanding precision

Decimal handling for accurate amounts.

Transaction statuses

What each status means and when it applies.

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.

Start Here

Ledgers

Ledger balances

Transactions

Reconciliation

Identities

Metadata

Search

Webhooks

API keys

Guides

Configuration

Advanced

Migration guides

Transaction properties

Recording a transaction

Verifying transactions with queue enabled

Verifying transactions without queue disabled

Discarded transactions

Managing insufficient funds

Default queue

Skip queue

Dive deeper

Dry-run transactions

Transaction lifecycle

Understanding precision

Transaction statuses

Need help?

​Transaction properties

​Recording a transaction

​Verifying transactions with queue enabled

​Verifying transactions without queue disabled

​Discarded transactions

​Managing insufficient funds

​Default queue

​Skip queue

​Dive deeper

Dry-run transactions

Transaction lifecycle

Understanding precision

Transaction statuses

​Need help?

Transaction properties

Recording a transaction

Verifying transactions with queue enabled

Verifying transactions without queue disabled

Discarded transactions

Managing insufficient funds

Default queue

Skip queue

Dive deeper

Need help?