This guide walks you through creating a complete transaction flow in Blnk: setting up a ledger, creating balances, and recording your first transaction.
Make sure you’ve installed Blnk and the server is running at http://localhost:5001 before proceeding. Understanding the Basics Before we start, let’s understand the core concepts:
Ledger : A container for organizing related balances (e.g., “Customer Wallets”, “Merchant Accounts”)Balance : An account that holds funds in a specific currency (e.g., a user’s USD wallet)Transaction : A movement of funds from a source balance to a destination balance
Step 1: Create a Ledger Ledgers organize your balances into logical groups. Let’s create a ledger for customer wallets:
curl -X POST http://localhost:5001/ledgers \ -H "Content-Type: application/json" \ -d '{ "name": "Customer Wallets", "meta_data": { "project": "main", "description": "Ledger for all customer wallet balances" } }'
Response: { "ledger_id" : "ldg_0be8a647-e155-4e2c-9fea-2e7cf1f14e23" , "name" : "Customer Wallets" , "created_at" : "2024-01-15T10:30:00Z" , "meta_data" : { "project" : "main" , "description" : "Ledger for all customer wallet balances" } }
Save the ledger_id - you’ll need it to create balances in this ledger.
Step 2: Create Balances Now let’s create two balances: one for Alice and one for Bob. Each balance represents a wallet that can hold funds.
Create Alice’s Balance curl -X POST http://localhost:5001/balances \ -H "Content-Type: application/json" \ -d '{ "ledger_id": "ldg_0be8a647-e155-4e2c-9fea-2e7cf1f14e23", "currency": "USD", "meta_data": { "customer_name": "Alice Johnson", "customer_id": "cust_alice_001" } }'
Response: { "balance_id" : "bln_a1b2c3d4-e5f6-7890-abcd-ef1234567890" , "ledger_id" : "ldg_0be8a647-e155-4e2c-9fea-2e7cf1f14e23" , "balance" : 0 , "credit_balance" : 0 , "debit_balance" : 0 , "inflight_balance" : 0 , "currency" : "USD" , "currency_multiplier" : 100 , "created_at" : "2024-01-15T10:35:00Z" , "meta_data" : { "customer_name" : "Alice Johnson" , "customer_id" : "cust_alice_001" } }
Create Bob’s Balance Repeat the same process for Bob:
curl -X POST http://localhost:5001/balances \ -H "Content-Type: application/json" \ -d '{ "ledger_id": "ldg_0be8a647-e155-4e2c-9fea-2e7cf1f14e23", "currency": "USD", "meta_data": { "customer_name": "Bob Smith", "customer_id": "cust_bob_002" } }'
Currency Multiplier : Blnk uses currency_multiplier to handle fractional amounts. For USD, the default is 100 (representing cents). A balance of 1000 equals $10.00.
Step 3: Record a Transaction Now let’s record a transaction sending $50.00 from Alice to Bob:
curl -X POST http://localhost:5001/transactions \ -H "Content-Type: application/json" \ -d '{ "amount": 50.00, "precision": 100, "reference": "ref_transfer_001", "currency": "USD", "source": "bln_a1b2c3d4-e5f6-7890-abcd-ef1234567890", "destination": "bln_b2c3d4e5-f6g7-8901-bcde-fg2345678901", "description": "Payment for services", "meta_data": { "type": "p2p_transfer", "invoice_id": "inv_12345" } }'
Response: { "transaction_id" : "txn_c1d2e3f4-g5h6-7890-cdef-gh3456789012" , "source" : "bln_a1b2c3d4-e5f6-7890-abcd-ef1234567890" , "destination" : "bln_b2c3d4e5-f6g7-8901-bcde-fg2345678901" , "reference" : "ref_transfer_001" , "amount" : 50.00 , "precise_amount" : 5000 , "precision" : 100 , "currency" : "USD" , "description" : "Payment for services" , "status" : "QUEUED" , "created_at" : "2024-01-15T10:40:00Z" , "meta_data" : { "type" : "p2p_transfer" , "invoice_id" : "inv_12345" } }
Transaction Status : Transactions start as QUEUED and are processed asynchronously by workers. The status will change to APPLIED once processing completes (usually within milliseconds).
Step 4: Verify the Transaction Let’s check the transaction status and verify the balances were updated:
Get Transaction by Reference curl http://localhost:5001/transactions/reference/ref_transfer_001
Response: { "transaction_id" : "txn_c1d2e3f4-g5h6-7890-cdef-gh3456789012" , "source" : "bln_a1b2c3d4-e5f6-7890-abcd-ef1234567890" , "destination" : "bln_b2c3d4e5-f6g7-8901-bcde-fg2345678901" , "reference" : "ref_transfer_001" , "amount" : 50.00 , "precise_amount" : 5000 , "currency" : "USD" , "status" : "APPLIED" , "hash" : "550e8400-e29b-41d4-a716-446655440000" , "created_at" : "2024-01-15T10:40:00Z" }
Check Alice’s Balance curl http://localhost:5001/balances/bln_a1b2c3d4-e5f6-7890-abcd-ef1234567890
Response: { "balance_id" : "bln_a1b2c3d4-e5f6-7890-abcd-ef1234567890" , "balance" : -5000 , "credit_balance" : 0 , "debit_balance" : 5000 , "currency" : "USD" , "currency_multiplier" : 100 }
Alice’s balance is -5000 (representing -$50.00 in precise format). The debit balance increased by 5000, showing money left her account.
Check Bob’s Balance curl http://localhost:5001/balances/bln_b2c3d4e5-f6g7-8901-bcde-fg2345678901
Response: { "balance_id" : "bln_b2c3d4e5-f6g7-8901-bcde-fg2345678901" , "balance" : 5000 , "credit_balance" : 5000 , "debit_balance" : 0 , "currency" : "USD" , "currency_multiplier" : 100 }
Bob’s balance is 5000 (representing $50.00). The credit balance increased by 5000, showing money entered his account.
Understanding Balance Fields Blnk tracks multiple balance dimensions:
balance : Net balance (credits - debits)credit_balance : Total credits (money in)debit_balance : Total debits (money out)inflight_balance : Funds held in pending transactionscurrency_multiplier : Precision multiplier (100 for cents, 1000000 for crypto)
Next Steps Now that you understand the basics, explore more advanced features:
Inflight Transactions Hold funds temporarily and commit or void them later
Multiple Destinations Split a single transaction across multiple recipients
Balance Monitors Set up webhooks for balance threshold alerts
Reconciliation Match internal transactions with external records
Common Operations
curl "http://localhost:5001/transactions?limit=20&offset=0"
Get All Balances in a Ledger
curl "http://localhost:5001/balances?limit=20&offset=0"
curl http://localhost:5001/transactions/txn_c1d2e3f4-g5h6-7890-cdef-gh3456789012
Filter Balances by Currency
curl -X POST http://localhost:5001/balances/filter \ -H "Content-Type: application/json" \ -d '{ "filters": [ {"field": "currency", "operator": "eq", "value": "USD"} ], "limit": 20, "offset": 0 }'
