Record a transaction

​

Overview

This guide shows you how to record a transaction into your Blnk Ledger.

There are 3 main ways a transaction can be categorized:

1. Money is received from an external balance (accounts, cards, crypto, etc.)
2. Money is sent out to an external balance (accounts, wallets, etc.)
3. Money is sent between balances in your application.

To successfully post or record a transaction, the following fields are required:

There are multiple ways to manage Source and Destination for transactions that involve an external balance.

However, it is best to create a dedicated balance, @World, to represent external balance, i.e., when receiving money from an external balance, it is "source": "@World" and when sending money to an external balance, it is “destination: "@World".

Go to Internal balances for more information on how to use and manage @World.

​

How Blnk records transactions

Blnk cares about the accuracy, security and integrity of your transaction data. As a result, all transaction records have 2 main properties — immutability and idempotency.

​

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.

​

Record a transaction

Send a request to the Record Transaction endpoint and input the required fields.

{
    "amount": 750,
    "reference": "ref_001adcfgf",
    "currency": "USD",
    "precision": 100,
    "source": "bln_28edb3e5-c168-4127-a1c4-16274e7a28d3",
    "destination": "bln_ebcd230f-6265-4d4a-a4ca-45974c47f746",
    "description": "For fees",
    "meta_data": {
      "sender_name": "John Doe",
      "sender_account": "00000000000"
    }
}

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.

{
    "id": "txn_6164573b-6cc8-45a4-ad2e-7b4ba6a60f7d",
    "source": "bln_28edb3e5-c168-4127-a1c4-16274e7a28d3",
    "destination": "bln_ebcd230f-6265-4d4a-a4ca-45974c47f746",
    "reference": "ref_001adcfgf",
    "amount": 750,
    "precision": 100,
    "precise_amount": 75000,
    "currency": "USD",
    "description": "For fees",
    "status": "QUEUED",
    "created_at": "2024-02-20 05:28:03 UTC"
    "meta_data": {
      "sender_name": "John Doe",
      "sender_account": "00000000000"
    }
}

It’s strongly encouraged to always pass a precision value that converts your amount to its lowest unit possible to ensure correctness when computing your balances. To learn more, read: Understanding precision.

​

Transaction statuses

There are three primary statuses for any transaction in the Blnk Ledger.

• QUEUED: This is the default status of any new transaction record. It means your transaction record has been accepted by Blnk, added to a queue and is waiting to be applied.

  See also → Why Blnk queues transactions.

• APPLIED: The status is updated to applied when the participating balances in the transaction get updated with the transaction amount. Only transaction records with the APPLIED status are deemed complete and permanently stored in the Blnk Ledger.

  E.g., if ₦1,000 was sent from bal_01 to bal_02;

  • the default transaction status is QUEUED;
  • the status changes to APPLIED when ₦1,000 has been deducted from bal_01 and added to bal_02.

• REJECTED: The status of a transaction is updated to rejected if any of the conditions required for a successful transaction isn’t met.

​

Conditions required for a transaction

1. The participating balances (source and destination) must have the same asset class (currency) as specified in the transaction request.
2. The source must have enough funds to process the transaction.
3. Overdraft must be enabled if the transaction has to happen but the source has insufficient funds.

​

Track a transaction

To track a transaction, call the Get Transaction endpoint and pass the id of the transaction in the URL.

We also send notifications via webhook events to let you know the updated status of a transaction:

• transaction.applied: Sent when the transaction status is updated to APPLIED.
• transaction.rejected: Sent when the transaction status is updated to REJECTED.

​

See also

​

Need help?

Are you stuck? Do you have a question that isn’t answered in this doc? Have you run into a problem you can’t solve? Want to file a bug report?

Join our Discord server and share your questions/thoughts with other developers building financial applications like you.