Forem: Etop - Essien Emmanuella Ubokabasi

How to Implement Recurring Payments with Blnk

Etop - Essien Emmanuella Ubokabasi — Wed, 25 Mar 2026 02:39:44 +0000

Learn how to implement recurring payments with Blnk by scheduling deposits in bulk, tracking progress with balance reads, and querying scheduled transactions for a complete audit trail.

Mia opens Kite, a personal finance app, sets a savings goal, and picks her terms: $200 a month for 3 months. She confirms it and moves on. From that point, she expects the deposits to happen on their own.

For you as the developer, a fixed savings goal gives you everything upfront: the amount, the deposit count, and the exact dates. In this guide, you'll set up Mia's savings balance, schedule all three deposits in a single bulk request, and query her progress, all with Blnk.

Mental model

Before you touch any code, define how money should move when Mia's goal is active. For Kite, there's one movement:

Deposit: @BankDeposits → bln_mia_savings. Each scheduled deposit moves $200 from the bank deposit source into Mia's savings balance on its due date.

@BankDeposits is a system balance that represents external inflows. Blnk creates it automatically the first time you reference it. In production, you define this name to map to your actual funding source.

The money movement map shows $200 flowing from @BankDeposits into Mia's savings balance on the 1st of each month across three scheduled deposits. See it with our Money Movement Map tool.

Step 1: Setting up your ledger design

Make sure you have a deployed Blnk instance before you start.

For Mia's savings goal, you need three things in place before you can schedule any transactions.

To implement this with Blnk:

Create a ledger called Savings Ledger to group all savings balances. Read docs.
Create an identity for Mia so you can attach her savings balance to her profile. Read docs.
Create a savings balance for Mia under the Savings Ledger, linked to her identity. Read docs.

Save the ledger_id, identity_id, and balance_id Blnk returns. You'll reference the balance_id as destination in every scheduled deposit, and the ledger and identity IDs when setting up savings for other customers.

Step 2: Activating a savings goal

When Mia activates her goal, your app has three inputs: the amount ($200 per deposit), the frequency (monthly), and the count (the number of deposits, 3 in this case). Use those to calculate the exact date for each deposit, then send all three transactions in one bulk request. Each transaction has a scheduled_for value set to the 1st of its respective month.

curl -X POST "http://YOUR_BLNK_URL/transactions/bulk" \
  -H "Content-Type: application/json" \
  -H "X-blnk-key: YOUR_API_KEY" \
  -d '{
    "atomic": true,
    "inflight": false,
    "run_async": false,
    "transactions": [
      {
        "amount": 20000,
        "precision": 100,
        "currency": "USD",
        "reference": "save_mia_2026-03",
        "source": "@BankDeposits",
        "destination": "bln_mia_savings",
        "description": "Monthly savings deposit - March 2026",
        "allow_overdraft": true,
        "scheduled_for": "2026-03-01T08:00:00+00:00",
        "meta_data": {
          "goal_id": "goal_mia_001",
          "period": "2026-03"
        }
      },
      {
        "amount": 20000,
        "precision": 100,
        "currency": "USD",
        "reference": "save_mia_2026-04",
        "source": "@BankDeposits",
        "destination": "bln_mia_savings",
        "description": "Monthly savings deposit - April 2026",
        "allow_overdraft": true,
        "scheduled_for": "2026-04-01T08:00:00+00:00",
        "meta_data": {
          "goal_id": "goal_mia_001",
          "period": "2026-04"
        }
      },
      {
        "amount": 20000,
        "precision": 100,
        "currency": "USD",
        "reference": "save_mia_2026-05",
        "source": "@BankDeposits",
        "destination": "bln_mia_savings",
        "description": "Monthly savings deposit - May 2026",
        "allow_overdraft": true,
        "scheduled_for": "2026-05-01T08:00:00+00:00",
        "meta_data": {
          "goal_id": "goal_mia_001",
          "period": "2026-05"
        }
      }
    ]
  }'

Response:

{
    "batch_id": "bulk_mia_goal_001",
    "status": "queued",
    "transaction_count": 3
}

Here's what happens:

All 3 transactions are accepted at once with status QUEUED. Blnk holds them and applies each one automatically when its scheduled_for time is reached.
Each reference is unique per period; it acts as an idempotency key. If your app sends the same request twice, Blnk will reject the duplicate.
run_async: false means Blnk processes the batch synchronously and returns only when all transactions are queued.
allow_overdraft: true on @BankDeposits lets the system balance go negative. This is the standard pattern for representing external inflows.
goal_id in meta_data tags every transaction in this goal to the same ID, so you can search all of them together.

Transactions table showing all three scheduled deposits for Mia's savings goal, each with status QUEUED and their respective scheduled dates.

Step 3: Tracking goal progress

To show Mia how much she's saved so far, read her savings balance:

curl -X GET "http://YOUR_BLNK_URL/balances/bln_mia_savings" \
  -H "Content-Type: application/json" \
  -H "X-blnk-key: YOUR_API_KEY"

Response:

{
    "balance_id": "bln_mia_savings",
    "balance": 40000,
    "credit_balance": 40000,
    "debit_balance": 0,
    "currency": "USD",
    "precision": 100,
    "ledger_id": "ldg_savings_001",
    "identity_id": "idt_mia_001",
    "created_at": "2026-03-01T08:00:00Z"
}

Here's what happens:

balance is returned in the smallest unit. Divide by precision (100) to get the display amount: 40000 / 100 = $400 saved so far (March and April deposits applied).
credit_balance reflects total money received into the balance; debit_balance reflects total money sent out. For a savings balance that only receives deposits, debit_balance stays at 0.

To see which deposits have run and which are still scheduled, query by goal_id:

curl -X POST "http://YOUR_BLNK_URL/search/transactions" \
  -H "Content-Type: application/json" \
  -H "X-blnk-key: YOUR_API_KEY" \
  -d '{
    "q": "goal_mia_001",
    "query_by": "meta_data.goal_id"
  }'

Response:

{
    "found": 3,
    "hits": [
        {
            "document": {
                "transaction_id": "txn_save_mia_001",
                "reference": "save_mia_2026-03",
                "amount": 20000,
                "currency": "USD",
                "status": "APPLIED",
                "scheduled_for": "2026-03-01T08:00:00+00:00",
                "meta_data": { "goal_id": "goal_mia_001", "period": "2026-03" }
            }
        },
        {
            "document": {
                "transaction_id": "txn_save_mia_002",
                "reference": "save_mia_2026-04",
                "amount": 20000,
                "currency": "USD",
                "status": "APPLIED",
                "scheduled_for": "2026-04-01T08:00:00+00:00",
                "meta_data": { "goal_id": "goal_mia_001", "period": "2026-04" }
            }
        },
        {
            "document": {
                "transaction_id": "txn_save_mia_003",
                "reference": "save_mia_2026-05",
                "amount": 20000,
                "currency": "USD",
                "status": "QUEUED",
                "scheduled_for": "2026-05-01T08:00:00+00:00",
                "meta_data": { "goal_id": "goal_mia_001", "period": "2026-05" }
            }
        }
    ]
}

Here's what happens:

found is the total number of transactions in this goal. Each hit has a status: APPLIED for deposits that have run, QUEUED for ones still scheduled.

Wrapping up

You now have a savings goal that runs completely on schedule. Mia confirmed her goal once; Blnk handles the rest: applying each deposit on the right date, updating her balance, and keeping a full audit trail.

This same pattern works for any recurring payment with a known duration: installment plans, fixed-term subscriptions, scheduled loan repayments, or any flow where you know the amount and the count upfront.

To see this flow end-to-end, run the savings goal demo in the blnk-demo repo.

What else can you build?

With this foundation you can:

Pause a goal: identify which scheduled transactions haven't run yet and cancel them with reversals when the customer pauses.
Adjust the amount: cancel remaining scheduled transactions and recreate them with the updated amount.
Extend the goal: add more scheduled transactions to cover the new periods.
Notify on each deposit: listen for transaction.applied webhooks to send Mia a confirmation when each month's deposit lands.

For more on Blnk, check the Blnk docs or join the community on Discord to ask questions and see what others are building.

How to Build a SaaS Referral System with Blnk

Etop - Essien Emmanuella Ubokabasi — Tue, 17 Mar 2026 14:19:27 +0000

Learn how to implement a referral program with the Blnk Ledger, from crediting referrer wallets to settling payouts.

Your product team just dropped a new referral program on your sprint: when a user invites a friend and that friend pays their first invoice, the referrer gets a $20 reward. The ticket's on you. What do you do?

The catch: the reward should only fire when the referred user actually pays, not just when they sign up. And it must only pay out once per referral, even if your webhook fires twice or your server retries the request.

We'll build this end to end with Blnk Finance, from crediting the reward when a referred user converts, all the way to processing the payout.

Mental model

Let's say you're building Flowly, a SaaS product with a subscription model. Your referral program works like this: Claire refers James, James signs up and pays for a subscription, and Claire gets $20 credited to her balance. The reward only fires after James pays, not when he signs up.

Before you touch any code, you need to define how money should move when a referral converts. For Flowly, there are two movements:

Pay-in: @ReferralExpense → referrer_wallet. When a referred user converts, Blnk credits the reward into the referrer's wallet.
Pay-out: referrer_wallet → @Payout. When you're ready to settle, Blnk moves the earned balance out to your payout provider for processing, e.g. Stripe, Adyen, Paystack, etc.

@ReferralExpense is a system balance that records every reward as an expense, giving you a real-time view of your Customer Acquisition Cost (CAC). Because it starts at zero and isn't pre-funded, you'll set allow_overdraft: true on each reward transaction.

The money movement map shows the pay-in flow (@ReferralExpense → referrer wallet) and the pay-out flow (referrer wallet → @Payout). Try it in our Money Movement Map tool.

Structuring your flows this way means you can query each balance to show your users exactly what they care about: total referrals earned, total paid out, and total pending payout.

Step 1: Setting up the referral ledger

Before you record any reward transactions, you need three things in place. Make sure you have a running Blnk instance before continuing.

Create a ledger to group all referrer wallets separately from the rest of your financial activity. We'll call it "Referral Ledger."
Create an identity for each referrer. This represents a real person in your ledger, so you can assign balances to them.
Create a balance and link it to the identity. This is the referrer's wallet — every reward credit and payout debit is recorded against it.

The Blnk Cloud dashboard showing our Referral Ledger with two referrer wallets created under it.

The ledger groups the wallets, the identity ties each wallet to a user, and the balance tracks every credit and debit. Together, they give you the structure to record reward transactions.

Step 2: Recording the referral reward

When James signs up using Claire's referral code, your app logs the relationship and tracks whether a reward should fire:

if (referral.status === "converted") {
  return fire_reward
} else {
  return no_reward
}

When James pays, record the reward to Claire's wallet in Blnk:

curl -X POST http://localhost:5001/transactions \
  -H "Content-Type: application/json" \
  -H "X-blnk-key: YOUR_API_KEY" \
  -d '{
    "precise_amount": 2000,
    "precision": 100,
    "reference": "reward-claire-referral-james",
    "currency": "USD",
    "source": "@ReferralExpense",
    "destination": "referrer-wallet-claire",
    "allow_overdraft": true,
    "description": "Referral reward: james converted",
    "meta_data": {
      "referral_code": "FLOWLY-CLAIRE",
      "referred_user": "james",
      "trigger": "subscription_payment_confirmed"
    }
    }'

A successful response looks like this:

{
  "transaction_id": "txn_a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "APPLIED",
  "precise_amount": 2000,
  "precision": 100,
  "currency": "USD",
  "source": "@ReferralExpense",
  "destination": "bln_referrer_wallet_claire_123",
  "reference": "reward-claire-referral-james"
}

‍

Here's what happens:

precise_amount: 2000 with precision: 100 is $20
@ReferralExpense sends out $20
referrer-wallet-claire receives $20
The reference must be unique. Blnk discards any transaction that reuses an existing reference, so duplicate webhooks or server retries won't pay out twice.

The transactions table shows the referral commission transaction — $20 (USD) debited from @ReferralExpense and credited to Claire Chen's wallet, with status Applied.

Step 3: Processing the payout

When you're ready to settle, retrieve all referrer balances greater than zero:

curl -X POST http://localhost:5001/balances/filter \
  -H "Content-Type: application/json" \
  -H "X-blnk-key: YOUR_API_KEY" \
  -d '{
    "filters": [
      {"field": "balance", "operator": "gt", "value": 0}
    ]
  }'

For each one, process a payout transaction that moves the full amount to @Payout, zeroing out the balance. For Claire's payout:

curl -X POST http://localhost:5001/transactions \
  -H "Content-Type: application/json" \
  -H "X-blnk-key: YOUR_API_KEY" \
  -d '{
    "precise_amount": 2000,
    "precision": 100,
    "reference": "payout-claire-2026-02-24",
    "currency": "USD",
    "source": "referrer-wallet-claire",
    "destination": "@Payout",
    "description": "Referral payout: scheduled",
    "meta_data": {
      "payout_provider_id": "po_stripe_98765xyz"
    }
  }'

‍

A successful response looks like this:

{

  "transaction_id": "txn_f9e8d7c6-b5a4-3210-fedc-ba9876543210",
  "status": "APPLIED",
  "precise_amount": 2000,
  "precision": 100,
  "currency": "USD",
  "source": "bln_referrer_wallet_claire_123",
  "destination": "@Payout",
  "reference": "payout-claire-2026-02-24"
}

‍Here's what happens:

referrer-wallet-claire sends out $20
@Payout receives $20
Your payout provider transfers the $20 to Claire's actual bank account

Once the money hits @Payout, it's out of your ledger. With this setup, your finance team can query @Payout to see how much was paid out in total and compare it against your payment provider statements to catch any drift.

The Blnk Cloud dashboard after the payout transaction — $20 (USD) debited from Claire Chen's referrer wallet and credited to @Payout, with status Applied.

What else can you build?

You now have a working referral system: reward on conversion, payout on schedule, full audit trail. The same building blocks can take you further:

Double-sided rewards. Credit both the referrer and the referred user when a conversion happens. Two transactions, same trigger.
Tiered rewards. Bump the reward amount after 5, 10, or 20 successful referrals. Your app checks the referrer's conversion count before setting the amount on the transaction.
Reward expiry. Set a deadline for referrers to claim their balance. If it lapses, move the unclaimed amount back to @ReferralExpense.
Commission-based rewards. Instead of a flat $20, pay a percentage of the referred user's subscription for N months. Calculate the amount per billing cycle and fire a reward transaction each time.

Ready to start building? Create a free Blnk Cloud account and follow along with the Blnk docs.

How to Build a Reward System for an eCommerce Platform using Blnk

Etop - Essien Emmanuella Ubokabasi — Fri, 06 Mar 2026 11:06:39 +0000

Learn how to set up customer wallets, issue rewards on purchase, and redeem them at checkout using Blnk with atomic bulk transactions.

Rewards are a common customer retention strategy for e-commerce and embedded finance products. In simple terms, you ‘reward’ customers for continuing to buy with you.

For you, the developer, it’s important for you to know if a customer has rewards, exactly how much has been rewarded, and how to help them redeem it.

In this guide, you'll learn how to implement a rewards system using the Blnk Ledger: from managing customer wallets to assigning and redeeming rewards at purchase. We'll use SunnySide Mart, a mid-sized supermarket franchise, as our example.

To see how this works in real-time, you can follow this guide hands-on using our example demo here.

Step 1: Setting up your ledger design

Since we’re using Blnk, make sure you have a deployed Blnk instance. If you don’t have one, we wrote a guide here on how to get started.

First, let’s review our rewards feature. We want customers to:

Earn rewards when they make a purchase.
Redeem the rewards as discount on a subsequent purchase
To do this, we’ll need to create and track a balance per customer for their rewards earned. To implement this with Blnk:

Create a ledger: Rewards Ledger to group all customer-owned balances. Read docs.
Create an identity for each customer: Add each customer as an individual identity. We’ll use this to create a balance for the customer in the next step. Read docs.
Create a rewards balance: Using the customer’s identity, create a balance for the customer under the Rewards ledger. Read docs.

Once you've done these, you'll have your customer balance ID. Save it, you'll need them for the next step.

Step 2: Earn rewards on purchase

For this guide: when a customer makes a purchase, we’ll issue a reward based on the amount spent. For simplicity, we'll award a 1% reward on purchases of $1,000 or more.

if (purchase_amount >= 1000) {
    reward_amount = 0.01 * purchase_amount
    return reward_amount
}

‍

So if a customer spent $3,000, they’d get $30 as rewards. To record this in Blnk, we’ll need two transactions that happen together:

We’ll record the customer $3,000 purchase as an external payment (e.g. card) to our revenue balance.
We’ll top-up the customer’s reward wallet with $30, using the balance ID from Step 1.

Money movement map for rewards payout after customer purchase. View the full map.

Here's how to implement it with Blnk's bulk transactions feature:

curl -X POST "http://localhost:5001/transactions/bulk" \
  -H "Content-Type: application/json" \
  -H "X-blnk-key: YOUR_API_KEY" \
  -d '{
    "atomic": true,
    "inflight": false,
    "skip_queue": true,
    "transactions": [
      {
        "amount": 3000,
        "precision": 100,
        "currency": "USD",
        "reference": "ref_purchase_order_10001",
        "source": "@CustomerPurchase",
        "destination": "@Revenue",
        "allow_overdraft": true,
        "description": "SunnySide order purchase",
        "meta_data": {
          "transaction_type": "purchase",
          "order_id": "10001",
          "customer_email": "peter.johnson@example.com"
        }
      },
      {
        "amount": 30,
        "precision": 100,
        "currency": "USD",
        "reference": "ref_reward_order_10001",
        "source": "@RewardsPool",
        "destination": "CUSTOMER_REWARD_BALANCE_ID",
        "allow_overdraft": true,
        "description": "Reward issued for order",
        "meta_data": {
          "transaction_type": "reward_earned",
          "order_id": "10001",
          "reward_rate": "1%"
        }
      }
    ]
  }'

You'll get the following response:

{
    "batch_id": "bulk_e1fb5f7a-74bc-47ad-83b9-44f428d4da97",
    "status": "applied",
    "transaction_count": 2
}

‍

Here's what happened:

With atomic: true, Blnk ensures that both transactions are successful together or not. If one isn’t successful, the other fails or is reversed.
The reference fields act as idempotency keys.
allow_overdraft: true allows system balances like @CustomerPurchase and @RewardsPool to go negative. This completes the double-entry requirement: every destination (revenue and customer rewards wallet) must have a source.

The transactions table shows the purchase to @Revenue and the reward issuance from @RewardsPool, both applied successfully.

Step 3: Redeem rewards at checkout

Now, the customer wants to use their rewards at checkout. They have a $50 order; if the $30 reward is applied, they’ll only have to pay $20 out of pocket.

For this, we’ll record a split transaction. First, we clear the reward balance completely, i.e. deduct the whole amount. Then we charge the remaining amount to the customer.

Money movement map for when a customer redeems their earned rewards in a subsequent purchase

curl -X POST "http://localhost:5001/transactions/bulk" \
  -H "Content-Type: application/json" \
  -H "X-blnk-key: YOUR_API_KEY" \
  -d '{
    "atomic": true,
    "inflight": false,
    "skip_queue": true,
    "transactions": [
        {
        "amount": 30,
        "precision": 100,
        "currency": "USD",
        "reference": "ref_rewards_discount_order_10002",
        "source": "CUSTOMER_REWARD_BALANCE_ID",
        "destination": "@Revenue",
        "description": "Rewards applied as discount",
        "meta_data": {
          "transaction_type": "reward_spent",
          "order_id": "10002"
        }
      },
      {
        "amount": 20,
        "precision": 100,
        "currency": "USD",
        "reference": "ref_purchase_order_10002",
        "source": "@CustomerPurchase",
        "destination": "@Revenue",
        "allow_overdraft": true,
        "description": "SunnySide order purchase (discounted)",
        "meta_data": {
          "transaction_type": "purchase",
          "order_id": "10002",
          "customer_email": "peter.johnson@example.com",
          "discount_source": "rewards",
          "discount_amount": 10
        }
      }
    ]
  }'

You should get the following response:

{
    "batch_id": "bulk_2eb77e28-ad3f-47b0-b04a-693c9a313a69",
    "status": "applied",
    "transaction_count": 2
}

‍

Here's what happened:

Revenue reflects the total amount earned from the purchase.
The rewards spend is recorded explicitly so you can always see what was discounted and by how much.
Unlike internal balances, customer rewards balances usually should not allow overdrafts. If the customer does not have enough rewards, this movement should fail.

The transactions table shows the discounted purchase and reward spend applied successfully.

Fetching a customer's rewards balance

To show a customer, how much they have in their rewards, you can simply fetch it from the ledger:

curl -X GET http://localhost:5001/balances/CUSTOMER_REWARDS_BALANCE_ID \
  -H "Content-Type: application/json" \
  -H "X-blnk-key: YOUR_API_KEY"

‍

You'll get your balance details in the response:

{
  "balance_id": "bln_7d606316-27d4-4ba4-bae1-3581692de614",
  "currency": "USD",
  "balance": 500,
  "credit_balance": 3000,
  "debit_balance": 2500,
  "inflight_balance": 0
}

Note: Blnk stores amounts in the smallest unit. Divide balance by precision before displaying, e.g. 100 for cents in USD, as used throughout this guide.

Peter's (the customer) balance after redeeming their reward

Wrapping up

You now have a fully auditable, retry-safe rewards system where every reward is a ledger entry and every workflow is reversible. This approach ensures that your rewards programme remains transparent and accurate.

Every reward earned or spent is now recorded as a clear transaction with full traceability.

What makes this system reliable is its atomic transaction model; purchases and rewards are always linked together, so you never lose track of where value flows.

Discounts are routed through @Revenue, keeping your financial statements accurate whilst still giving customers the benefit they've earned.
Cash-outs and redemptions are logged with payout references in metadata, giving you a complete audit trail for reconciliation and support.

What else can you build?

With this foundation in place, you can extend your rewards system in other ways like:

Implementing reward expirations using scheduled reversals,
Creating tiered reward rates based on customer segments,
Generate customer reward statements
Exportable audit trails for compliance and customer service.

Building your ledger this way gives you the flexibility to evolve your rewards programme as your business grows.

How to Build Loan Disbursement, Interest, and Repayments with Blnk

Etop - Essien Emmanuella Ubokabasi — Fri, 06 Mar 2026 10:32:24 +0000

A practical guide to building a lending ledger with the Blnk Ledger. Learn how to safely disburse loans, charge interest, track repayments, and prevent customers from accessing more credit than they’re allowed.

When build a lending product, the one mistake no developer wants to make is letting customers access more credit than they are allowed to access. If this happens, the company could lose millions of dollars with no clear way to recover it back from customers. For younger startups, this “fraud event” could mark the end for them.

In most cases, issues like these happen because of how their ledger is designed.

In this article, you’ll learn how to avoid this mistake using the Blnk Ledger. We’ll use Lumen Credit, a loan app that allows customers borrow money and repay at a later date plus interest.

Let’s dive in!

Step 1: Setting up your ledger

Since we’re using Blnk, make sure you have a deployed Blnk instance. If you don’t have one, we wrote a guide here on how to get started.

Before we start working with the ledger, let’s review Lumen Credit’s features. For each signed up customer, we want to:

Disburse a loan when requested
Charge interest on the amount owed
Track repayments from the customer. To do this, we’ll need to track two separate sets of balances for the customer.

Loan balance: This tracks the amount owed by the customer at any point in time. When a customer requests a loan, money is deducted from this balance and the overdraft created tracks the amount owed.
Main balance: This tracks the amount available for the customer to spend.

The ledgers table shows the Customer Main Ledger and Customers Loan Ledger after creation, along with the General Ledger.

To implement this architecture in our ledger:

Create two ledgers folders: Customers Loan Ledger to group all loan balances in one place; then Customer Main Ledger for all main balances. Read docs.‍
Create an identity for each customer: Add each customer as an individual identity. We’ll use this to link the customer to their respective pair of balances in the next step. Read docs.‍
Create the balances per customer: Using the newly created customer's identity, create the loan and main balance under their respective ledgers. Read docs.

The balances table shows two balances created for Billy Brian: a main balance and a loan balance, both starting at 0.00

Note: For each ledger, balance, and identity created, Blnk assigns a unique id. Keep these ids, you’ll need them for the rest of the steps.

Step 2: Disbursing a loan

At Lumen Credit, loan disbursement goes through three steps:

First, the customer requests a loan amount. Next, the system checks if the customer is eligible for that loan. This could be a set of conditions such as: KYC tier, location, credit score, loan limit, etc. Finally, if all checks pass, the loan is approved and sent to the customer; if not, loan is rejected.

To model this with Blnk, we’ll record this as an overdraft transaction moving from the customer’s loan balance to their main balance.

Money movement map for inflight transaction from the customer's loan balance to their main balance. View the full map.

Since we need to record the loan request first but delay execution until it passes our checks, we’ll use the inflight transaction feature to temporarily hold the transaction while we validate the conditions.

In simple terms, Inflight is how you ensure that a transaction doesn’t get applied to the destination until you tell it to. In our case, until we confirm that all conditions are met, the customer will not have access to those funds in their balance. Learn more about Inflight.

curl -X POST http://localhost:5001/transactions \
  -H "Content-Type: application/json" \
  -H "X-blnk-key: YOUR_API_KEY" \
  -d '{
    "precise_amount": 50000,
    "precision": 100,
    "currency": "USD",
    "reference": "LOAN-DISBURSE-001",
    "source": "bln_LOAN_BALANCE_ID",
    "destination": "bln_MAIN_BALANCE_ID",
    "description": "Loan disbursement to Billy",
    "allow_overdraft": true,
    "inflight": true,
    "meta_data": {
      "transaction_type": "loan_disbursement",
     "customer_id": "CUST_001",
    "loan_amount": 500

    }
}

Note:

The precise_amount field uses the smallest currency unit (e.g., cents for USD). With precision: 100, 50000 represents $500.00 (i.e. 500.00 x 100).
inflight: true is how you enable inflight on a transaction.
allow_overdraft: true tells Blnk that the source balance (i.e. loan balance) should be allowed to go negative.

Why negative for the loan balance?

This is because it allows us to represent debt on the loan balance. Once we submit this, we’ll get a response like this:

{
  "transaction_id": "txn_74382c5a-ee16-41c8-83a5-74464c34051a",
  "status": "QUEUED",
  "inflight": true,
  "precise_amount": 50000,
  "amount": 500,
 "source": "bln_b76a741f-4f1a-4018-b1a9-e7251e6f8541",
  "destination": "bln_1a817670-e647-4089-b1ba-e4d1a89e24f1",
  "reference": "LOAN-DISBURSE-001",
  "allow_overdraft": true,
  "meta_data": {
    "transaction_type": "loan_disbursement",
    "customer_id": "CUST_001",
    "loan_amount": 500
  }
}

Make sure that you keep the transaction ID.

Next, you check all of the conditions for the customer:

if (kyc && loan_limit && credit_score) {
    return approve_loan
} else {
    return reject_loan
}

To approve or reject our loan, we simply commit or void the inflight transaction in Blnk. To do this, we’ll call the update inflight endpoint using the transaction ID from the previous step:

# Approve loan (commit)
curl -X PUT http://localhost:5001/transactions/inflight/{transaction_id} \\
  -H "Content-Type: application/json" \\
  -H "X-blnk-key: YOUR_API_KEY" \\
  -d '{
    "status": "commit"
  }'

# Reject loan (void)
curl -X PUT http://localhost:5001/transactions/inflight/{transaction_id} \\
  -H "Content-Type: application/json" \\
  -H "X-blnk-key: YOUR_API_KEY" \\
  -d '{
    "status": "void"
  }'

A successful response will look something like this:

//Approved loan
{
  "transaction_id": "txn_15d09e5e-b38e-43cf-aeaf-29e42631c845",
  "parent_transaction": "txn_74382c5a-ee16-41c8-83a5-74464c34051a",
  "status": "APPLIED",
  "precise_amount": 50000,
 "amount": 500,
  "source": "bln_b76a741f-4f1a-4018-b1a9-e7251e6f8541",
  "destination": "bln_1a817670-e647-4089-b1ba-e4d1a89e24f1",
  "reference": "ref_5cc4daff-2005-43e4-8dcc-2c2db61a95fa",
  "meta_data": {
    "transaction_type": "loan_disbursement",
    "customer_id": "CUST_001",
    "loan_amount": 500
  }
}

The transactions table shows loan requests in different states: one Applied (approved), one Void (rejected), and two Inflight (pending).

Step 3: Charging Interest

At Lumen Credit, let’s assume we charge a 1% interest on a daily basis. When you charge interest, the amount owed naturally increases.

To model this with Blnk, we’ll move money from the customer's loan balance to a dedicated revenue balance. This would correctly track that the customer owes a bit more (i.e. original loan + interest) while recording our expected interest revenue from the customer.

Money movement map for interest charge on a transaction.

Our transaction looks something like this:

curl -X POST http://localhost:5001/transactions \\
  -H "Content-Type: application/json" \\
  -H "X-blnk-key: YOUR_API_KEY" \\
  -d '{
    "precise_amount": 500,
    "precision": 100,
    "currency": "USD",
    "reference": "INTEREST-001",
    "source": "bln_LOAN_BALANCE_ID",
    "destination": "@InterestRevenue",
    "description": "Daily interest charge",
    "allow_overdraft": true,
    "meta_data": {
      "transaction_type": "interest_charge",
      "interest_rate": 0.01,
      "principal_amount": 500
    }
  }'

Since, interest revenue is a balance we (Lumen Credit) own, we will use the internal balance feature to specify that.

This automatically creates the balance in the General Ledger if it doesn’t exist and uses it like a normal balance in our transaction. To apply, we’ll specify using an indicator — a unique name with the @ prefix. In our case, we used @InterestRevenue.

Once submitted, we should get a response like this:

{
  "transaction_id": "txn_533d55e7-8daa-468a-958a-9846f877c5bf",
  "status": "QUEUED",
  "precise_amount": 500,
  "amount": 5,
  "source": "bln_b76a741f-4f1a-4018-b1a9-e7251e6f8541",
  "destination": "@InterestRevenue",
  "reference": "INTEREST-001",
  "allow_overdraft": true,
  "meta_data": {
    "transaction_type": "interest_charge",
    "interest_rate": 0.01,
    "principal_amount": 500
  }
}

The transactions table shows an interest charge transaction of $5.00 moving from Billy Brian's loan balance to @InterestRevenue with Applied status.

Step 4: Collecting repayments

To model repayments, our goal is to zero out the loan balance. Once the loan balance is equal to or greater than 0, the customer is deemed as debt-free.

To record a repayment, we’ll simply move money from their main balance back to their loan balance to reduce the debt.

Money movement map of a $200.00 repayment transaction from the customer's main balance back to their loan balance.

Here's how to record that repayment in Blnk:

curl -X POST http://localhost:5001/transactions \\
  -H "Content-Type: application/json" \\
  -H "X-blnk-key: YOUR_API_KEY" \\
  -d '{
    "precise_amount": 20000,
    "precision": 100,
    "currency": "USD",
    "reference": "LOAN-REPAYMENT-001",
    "source": "bln_MAIN_BALANCE_ID",
    "destination": "bln_LOAN_BALANCE_ID",
    "description": "Loan repayment from Billy",
    "allow_overdraft": false,
    "meta_data": {
      "transaction_type": "loan_repayment",
      "customer_id": "CUST_001",
      "repayment_amount": 200
    }
  }'

Note:

allow_overdraft: false ensures the repayment fails if the customer doesn't have enough funds in their main balance.

Once submitted, we’ll get the following response:

{
 "transaction_id": "txn_a7e37fab-2b33-4fc9-9a54-b4ffa3d7d4e6",
  "status": "QUEUED",
  "precise_amount": 20000,
  "amount": 200,
  "source": "bln_1a817670-e647-4089-b1ba-e4d1a89e24f1",
  "destination": "bln_b76a741f-4f1a-4018-b1a9-e7251e6f8541",
  "reference": "LOAN-REPAYMENT-002",
  "allow_overdraft": false,
  "meta_data": {
   "transaction_type": "loan_repayment",
   "customer_id": "CUST_001",
   "repayment_amount": 200
  }
}

You can repeat this repayment flow as many times as needed. Once the loan balance reaches 0 or higher, the loan is fully repaid.

The balance detail view displays Billy Brian's loan balance at 0.00 after full repayment, showing all transactions that led to this state.

Wrapping it up

Now, we have our Lumen Credit product.

You can apply this guide to any lending-related product/feature that you’re building, e.g. credit cards, BNPL, employee loans, merchant advances, and more.

As long as your Blnk Ledger is structured to clearly represent loans, limits, and available balances, you can confidently build on top of it.

To see this in action, check out the demo. If you’d like to explore more, check the Blnk docs, or join our community on Discord to ask questions and get support.

How to Build a Bulk Payroll System Using the Blnk Ledger

Etop - Essien Emmanuella Ubokabasi — Fri, 23 Jan 2026 14:58:08 +0000

Learn how to process bulk payroll and payouts using Blnk’s Bulk Transactions API with reliable balance updates and safe, scalable execution.

When building a bulk payout system that handles hundreds or thousands of transfers, you want to make sure transactions are processed completely, and everyone’s balances are updated appropriately.

If you try to handle each payment one by one, things get messy fast. You'll end up with systems that break easily and recovery processes that are way too complicated.

When implementing bulk payouts developers face various integration complexities. You would have to deal with complexities such as API rate limits when mass requests are throttled.

In this guide, you’ll learn how to handle bulk payouts using Blnk ledger.
If you’d like to follow along hands-on, you can try this end to end using our example demo here.

Prerequisites

Before we start, make sure you have:

A running instance of Blnk.
Optionally, sign up to Blnk Cloud to manage your data as you build

Set up your payroll ledger structure

First things first, we need to set up our ledger architecture. This is how ledgers and balances are structured in our Core for easier reference.

For this article, we’ll design an internal payroll ledger for Acme Inc., a 3,000-person team with employees in 12 countries. Our ledger must have the following:

Multi-currency: We’ll be paying out to 12 different countries with different tax laws and we may need to track them.
Payslip generation: Every employee must own a balance to track their entire payroll history within the company.
Internal accounting/auditability: The Acme Finance team must be able to track and reconcile money movement on the company accounts.

To implement this in our ledger:

Create ledgers per country: This allows us to group employees from a particular country in one place, e.g., USA Ledger for all US-based employees, ITA Ledger for all Italy-based employees, and so on. Read docs.
Create an identity for each employee: Record every employee as an entity in the ledger. This will be important for the next step. Read docs.
Create a balance for each employee: Using the employee’s identity and their respective country of residence, create a balance for each employee. Read docs.

Fund your payroll account

Now that you’re set up, let’s work on payments.

Before we process payouts to employees, we need to first fund a company payroll balance. This sets a clear payroll budget for the period and gives Blnk a limit to work with. As a result, each payout is validated against the available payroll balance, allowing Blnk to track/manage cases where requested payouts exceed the payroll balance.

To do this, we’ll fund a balance dedicated to Acme’s payroll in our ledger. We’ll call it “@PayrollBalance.” Read docs on internal balances.

Internal balances are balances owned by Acme, and we reference this using indicators (like @BusinessAccount) instead of making use of balance IDs in your transaction request.

To fund the payroll account, we’ll create a transaction to represent a deposit from the business’ bank account to their payroll balance in your product:

curl -X POST http://localhost:5001/transactions \
  -H "Content-Type: application/json" \
  -H "X-blnk-key: YOUR_API_KEY" \
  -d '{
    "amount": 2000000,
    "precision": 100,
    "reference": "business_funding_2025-01-15",
    "currency": "USD",
    "source": "@BankDeposits",
    "destination": "@PayrollBalance",
    "description": "Payroll funding for January 2025",
    "allow_overdraft": true
  }'

In our example, we deposited $2,000,000.00 into Acme’s payroll balance. We used @BankDeposits as our source to ensure double-entry.

Our @BankDeposits balance here has been automatically created by Blnk in our general ledger because it was specified with “@”

Always calculate the total payroll amount and fund accordingly. Make sure to fund enough to cover all employee salaries.

Process payroll

Now, it’s that time of the month! Let’s payout 3,000 employees.

We can do this in two ways:

Synchronous processing: Process everything in one go, and return a success/failed response.
Async processing: Process all transactions in the background, and notify via webhooks/events.

Synchronous processing

With this, your batch payment would be processed in a single request. For Acme, we can process bulk payouts in batches of 100, i.e. a total of 30 requests to complete processing.

Now, we’ll create the bulk transaction request. You can create an array of transactions—one for each employee—and send them all in a single request.

First, let's prepare the transaction for a few employees:

curl -X POST http://localhost:5001/transactions/bulk \
  -H "Content-Type: application/json" \
  -H "X-blnk-key: YOUR_API_KEY" \
  -d '{
    "run_async": false,
    "transactions": [
      {
        "amount": 8752,
        "precision": 100,
        "reference": "PAYROLL_EMP150_2025-01-15",
        "description": "Salary payment for Stacy Jones - 2025-01-15",
        "currency": "USD",
        "source": "@BusinessAccount",
        "destination": "bln_c37fa6ca-b430-48f1-9095-1ebc514589d6",
        "allow_overdraft": false,
        "meta_data": {
          "employee_id": "EMP150",
          "employee_name": "Stacy Jones",
          "payroll_period": "2025-01-15",
          "payment_type": "salary"
        }
      },
      {
        "amount": 7243,
        "precision": 100,
        "reference": "PAYROLL_EMP149_2025-01-15",
        "description": "Salary payment for Gene Wells - 2025-01-15",
        "currency": "USD",
        "source": "@BusinessAccount",
        "destination": "bln_6c99439c-99e1-4f9b-923b-493693f38dff",
        "allow_overdraft": false,
        "meta_data": {
          "employee_id": "EMP149",
          "employee_name": "Gene Wells",
          "payroll_period": "2025-01-15",
          "payment_type": "salary"
        }
      }
      // Add more transactions here
    ]
  }'

run_async: false tells Blnk that the transactions should be processed synchronously. For larger batches, the request may take longer to complete.

Once completed, you should see the following response:

{
    "batch_id": "bulk_32472ce2-0ba2-46c1-b796-aafc6cd31811",
    "status": "applied",
    "transaction_count": 2
}

Store or use the batch_id to reference this batch in other operations.

Async processing

With async processing, run_async: true, Blnk accepts the request and returns a response telling you that it is being processed in the background.

With this, we can pass all 3,000 transactions in our payload without worrying about server timeouts:

curl -X POST  \\
  -H "Content-Type: application/json" \\
  -H "X-blnk-key: YOUR_API_KEY" \\
  -d '{
    "run_async": true,
    "transactions": [
      {
        "amount": 5000,
        "precision": 100,
        "reference": "PAYROLL_EMP001_2025-01-15",
        "description": "Salary payment for Employee 1 - 2025-01-15",
        "currency": "USD",
        "source": "@BusinessAccount",
        "destination": "bln_employee_1_balance_id",
        "allow_overdraft": false,
        "meta_data": {
          "employee_id": "EMP001",
          "employee_name": "Employee 1",
          "payroll_period": "2025-01-15"
        }
      }
      // ... add 2,999 more transactions here
    ]
  }'

Expected response:

{
    "batch_id": "bulk_204fa664-7171-4c38-9533-cc1086063376",
    "message": "Bulk transaction processing started",
    "status": "processing"
}

Since it is async, a batch_id is returned immediately and the payments continues in the background.

To know when the transactions have been processed, set up webhooks to listen for transaction.applied events and use them to trigger bank payouts via your payment provider.

This way, you can ensure that the transaction is verified first in your ledger before money leaves your system.

Payroll payment made to multiple employees in one request

Retrieve all transactions in a batch

To retrieve all transactions that belong to the same batch, use the Search API and query by a shared key such as a batch_id.

Async bulk transactions

Blnk automatically assigns a batch identifier and stores it in transaction metadata under QUEUED_PARENT_TRANSACTION. You can use this value to retrieve all transactions in the single batch.

curl -X POST  \\
  -H "Content-Type: application/json" \\
  -H "X-blnk-key: YOUR_API_KEY" \\
  -d '{
    "q": "bulk_c62f200b-905f-4983-a349-cadd279234aa",
    "query_by": "meta_data.QUEUED_PARENT_TRANSACTION"
  }'

This is the recommended approach for queued or asynchronous processing, since grouping is handled automatically.

Synchronous transactions

For synchronous processing where multiple transactions are created without a single batch_id, include your own shared identifier in the transaction metadata.

For example, you might add a value like tag: payroll-jan-2026 to each transaction.

You can then retrieve all related transactions by querying that metadata field:

curl -X POST  \\
  -H "Content-Type: application/json" \\
  -H "X-blnk-key: YOUR_API_KEY" \\
  -d '{
    "q": "payroll-jan-2026",
    "query_by": "meta_data.tag"
  }'

This approach gives you full control over grouping when transactions are created synchronously or across different workflows.

Alternatively, you can filter on Cloud and save to view for easy reference and operations.

A filtered Cloud dashboard (with saved view) for a bulk transaction.

You now have a working bulk payroll system. Get started with Blnk to try it out yourself. If you have any questions about this guide, reach out on Discord or send us a message.

Understanding Balances in Ledgers

Etop - Essien Emmanuella Ubokabasi — Thu, 22 Jan 2026 14:58:48 +0000

Explore the two main approaches to computing balances in a ledger.

A ledger’s primary role is to serve as the definitive source of truth for your financial product or records. It’s a system designed to track and report data accurately, but above all, it must answer one critical question at all times: "What is the balance?"

Whether it’s the current position of an asset, a user, or an entity, knowing the balance is the top priority of any ledger. How do we ensure this question is answered correctly and efficiently? The architecture you choose depends on your preferences, needs, and constraints.

In this article, I’ll explore the two main approaches used today—Running Balances and Aggregated Balances—and help you decide which might work best for your system.

Running balances

A running balance is a continuously updated total that changes as transactions occur, much like the balance in a check-book or bank account. For example, if you deposit $100 into a savings account with a starting balance of $500, the running balance immediately updates to $600.

Here’s what defines this approach:

Reacts to events: The balance adjusts in real-time as transactions (deposits, withdrawals) are recorded.
Concurrency challenges: Concurrency refers to multiple actions happening at once. If two transactions, like a deposit and a withdrawal, occur simultaneously, the system must ensure the balance doesn’t get miscalculated. This requires careful design, such as locking mechanisms.
Rebuildable: You should be able to reconstruct the running balance by replaying the transaction history, providing a safety net if something goes wrong.
Fast retrievals: Since the balance is precomputed and updated live, fetching it is quick and resource-light.

Trade-offs: Running balances excel in scenarios needing instant access (an ATM checking your account, for instance). However, they demand robust systems to handle concurrency and can be costly to scale if transaction volume spikes.

Aggregated balances

An aggregated balance calculates the total by summing all transactions (credits and debits) at a given moment, rather than maintaining a live tally. Imagine a payroll system: instead of updating an employee’s total earnings with every paycheck, it logs each payment and sums them up at the end of the month.

Key characteristics include:

No real-time reaction: Transactions are recorded without immediately updating a balance, simplifying the logging process.
Concurrency-friendly: Without a running total to maintain, there’s no risk of conflicts from simultaneous updates.
Aggregation process: The balance is computed by adding all credits and subtracting all debits. For large datasets, this can get slow without optimization.
Retrieval considerations: Fetching the balance requires summing transactions on demand, so performance may degrade as data grows unless you use techniques like precomputed summaries.

Trade-offs:

Aggregated balances are simpler to implement and maintain, ideal for high-throughput systems not needing real-time updates. However, the lack of instant balance tracking can fail apps like trading platforms or financial tools where users demand up-to-the-second accuracy.

Performance suffers as data grows, summing millions of transactions can slow queries or demand costly hardware. Without optimization (indexing, caching), retrievals may stall under load. Scaling requires heavy investment in storage and compute power.

Historical balances

Answering "What is the balance?" is only half the job. A good ledger must also answer "What was the balance?" to provide a complete financial history. Both approaches handle this differently.

Running balances

Snapshotting: You can take periodic snapshots of the running balance, saving the total at midnight each day, for example. If your savings account was $600 on Monday and $550 on Tuesday, snapshots capture those states.
Combining data: Pairing snapshots with transaction history lets you reconstruct the balance at any past point, like figuring out your balance mid-day after a withdrawal.

Aggregated Balances

Effective dates: Aggregation uses effective dates, the actual date a transaction occurred, not when it was logged. If you got paid on March 1st but it was recorded on March 3rd, the effective date ensures the balance reflects March 1st’s reality.
Caching: Storing precomputed totals (last month’s balance, for instance) and building from there speeds up historical queries without recalculating everything.

Trade-offs:

‍Running balances make historical lookups fast with snapshots but require extra storage. Aggregated balances are flexible with effective dates but may need caching to avoid slow recalculations.

Choosing the right approach

So, how do you decide between running balances and aggregated balances? There’s no one-size-fits-all answer, it hinges on your use case. Here are some questions to guide you and your team:

How critical is fast retrieval with minimal resources? If users, like bank customers, need instant balance updates, running balances shine. Aggregated balances might frustrate them with delays.
Are we prepared to handle concurrency issues? If your system sees heavy simultaneous activity (an e-commerce platform during a sale, for example), aggregated balances avoid concurrency headaches. Running balances require more engineering effort.
Do we trust our database or data warehouse’s aggregation capabilities? Modern databases like PostgreSQL or warehouses like Snowflake can handle massive sums efficiently, favoring aggregated balances if you’ve invested in them.
Who needs access to this data across the organization? Real-time dashboards for executives might lean toward running balances, while periodic reports for accountants align with aggregated balances.

Example decision:

A bank ATM system might choose running balances for speed and real-time accuracy, despite concurrency challenges. A payroll system might pick aggregated balances for simplicity and batch reporting, accepting slower on-the-fly queries.

Regardless of your choice, every ledger must answer:

"What is the balance?" quickly and accurately.
"What was the balance?" with equal precision.

Conclusion

In summary, choosing between running and aggregated balances depends on your specific needs. Running balances offer real-time accuracy, ideal for scenarios requiring instant updates.

Aggregated balances, on the other hand, simplify concurrency management and are easier to implement for high-throughput systems. Consider your use case, concurrency demands, and performance requirements to determine the best fit. Ultimately, the right approach is one that aligns seamlessly with your system's goals and constraints.

#LedgerSystems #AccountingArchitecture #FinancialInfrastructure #BalanceComputation #RunningBalances #AggregatedBalances #DoubleEntryAccounting #SystemDesign #BackendEngineering #DataConsistency #ConcurrencyControl #EventSourcing #FinancialSystems #Auditability #FintechEngineering #DeveloperEducation

AI Billing: How to Build Monetization & Cost Tracking for AI Agents with Blnk

Etop - Essien Emmanuella Ubokabasi — Thu, 22 Jan 2026 14:47:02 +0000

Learn how to setup a usage-based billing system for your AI products.

Everyone loves a good AI product: calendars, banking, e-commerce, education, research, design, engineering, etc.

As AI tools have become more common, teams building them have widely adopted usage-based pricing as the go-to billing model for their products.

Building usage-based billing starts out simple until you need to handle pricing for thousands of customers across different AI models, each with its own rate and usage behaviour. So how do you do it?

In this guide, we’ll walk through how to set up the core infrastructure behind an AI billing system. These steps cover setting up your ledger, creating and managing balances for your users’ subscriptions, invoicing, and enabling money movement.

Modelling your AI billing system

Let’s start with the basics. Every usage event in your AI product has two parts:

Tokens: How much was consumed, typically measured and reported by your AI provider.
Dollars: The monetary value of that consumption, i.e. how much it costs based on your pricing model.

Since both parts serve as halves of a whole, they should always be recorded together in one system — your single source of truth.

Why is this important? Because in most billing setups, these components are managed separately — tokens in provider dashboards, costs in card statements, and customer charges in your own system.

That separation creates room for error: missing logs, duplicate retries, overcharges, and ultimately, mismatched balances that frustrate customers.

1: Decide how you’ll track usage per customer

Most AI providers issue a single usage wallet per organization. This means it’s up to you to determine which usage belongs to which customer.

To track usage and invoices accurately at customer level, you’ll need to create a wallet for each customer. This setup allows you to:

Attribute every token used to the right customer.
Generate accurate usage-based invoices without mixing data across customers.
Enforce limits or apply discounts per wallet.

2: Define your money movement map

Money movement map refers to how money (or assets) move in your application. It gives you a visual blueprint for how transactions should be recorded across different workflows.

For example, most AI billing systems have two core workflows that move money:

Wallet funding
Token usage — whether prepaid or postpaid

Earlier, we established that each usage event should always record two components together: tokens and dollars. Here’s what that looks like in our money movement map:

To accurately record usage, both token usage and corresponding USD should be tracked & atomically linked in your ledger

After each usage:

The number of tokens consumed is recorded internally.
The corresponding USD value is debited from the customer’s wallet and credited to your revenue account.
Both actions occur together in a single atomic write, ensuring every token record has a matching customer debit transaction.

3: Choosing your double-entry ledger

A ledger serves as your source of truth for all transactions within your system, ensuring:

Transactions are immutable and idempotent.
Accurate balances being kept for your customers.
Reliable record keeping for audit needs.

Billing is an accounting problem, not just analytics. Your goal is to ensure that every event is traceable and auditable to the smallest cent.

Because AI providers only issue one wallet per organization, a ledger helps you keep track of usage and cost at the customer level like we planned in Step 1.

For this guide, we’ll use Blnk Core as our ledger infrastructure. You can install it here.

Setting up your ledger

Before implementing the billing workflows, you need to set up your ledger.

1: Create ledger

We’ll start with a ledger folder. A ledger folder in Blnk helps you group similar balances together. For this guide, we want a ledger for our customers’ balances.

To create our ledger, make the following API call to our Create Ledger endpoint:

curl -X POST http://localhost:5001/ledgers \
  -H "Content-Type: application/json" \
  -H "X-Blnk-Key: YOUR_API_KEY" \
  -d '{
    "name": "Customers Ledger"
  }'

The response includes a ledger_id which you’ll use to create the customer’s wallet balance in Step 2.

Your newly created Customers Ledger.

2: Create customer wallet

Next, create a balance for each customer in your system. In this example, we’ll create a balance for “Xavier Woods.” Make a request to our Create Balance endpoint:

curl -X POST http://localhost:5001/balances \
  -H "Content-Type: application/json" \
  -H "X-Blnk-Key: YOUR_API_KEY" \
  -d '
    "ledger_id": "ldg_90b6806c-98a9-4e4b-842b-581e4a918faf",
    "currency": "USD",
    "meta_data": {
        "name": "Xavier Woods"
    }
  }'

The response includes a balance_id which you’ll use when recording transactions to the customer’s balance.

Optionally, you can create a customer identity in Blnk and link it to the balance, rather than storing the customer’s name in metadata. Learn more about linking balances here.

Wallet top-up

Xavier wants to add $120.00 to his account. To do this, you’ll need to create a transaction that adds money to his balance in your ledger.

The money movement map for this is:

To top up the customer's wallet, specify the wallet balance as the destination in the transaction

To implement this with Blnk, make a request to the Create Transaction endpoint:

curl -X POST http://localhost:5001/transactions \
  -H "Content-Type: application/json" \
  -H "X-Blnk-Key: YOUR_API_KEY" \
  -d '{
    "amount": 120,
    "currency": "USD",
    "precision": 100,
    "reference": "ai-billing_ref-001",
    "source": "@World-USD",
    "destination": "bln_964e2037-c399-4f46-b566-6a84681600f7",
    "description": "Wallet funding",
    "allow_overdraft": true
  }'

Blnk enforces double-entry accounting through the source and destination fields.The source represents where funds are deducted from, while the destination represents where they are credited to.

$5,000 USD top-up transaction to Xavier's wallet

Also:

amount– The value to transfer (e.g. 43.23);
precision– Converts the amount to its smallest unit (e.g. 100 converts to dollar amounts to cents). This helps you avoid rounding errors that are common with floating-point arithmetic.
currency– All currencies are support: fiat and crypto. You can also use custom currencies as well, e.g. TOKENS.

Xavier's balance after funding

In Blnk, instead of balance IDs, you can use indicator names (like @World-USD or @Revenue) to reference wallets owned by your application. They’re automatically grouped under your General Ledger.

Learn more about recording transactions in Blnk here.

Manage billing

To record usage in your ledger, you first need to know how many tokens your AI model consumed and what that usage is worth in USD.

1: Connect to your LLM

You’ll start by connecting to your provider. For this guide, we’ll use the Open AI TypeScript SDK:

import OpenAI from "openai";
export const openai = new OpenAI({ apiKey: process.env.OPENAI_API_KEY! });

2: Capture token usage

Next, you can make a completion request and extract how many input and output tokens were used after each usage event.

export async function runCompletion(model: string, prompt: string) {
  const response = await openai.responses.create({
    model,
    input: [{ role: "user", content: prompt }],
  });

  const inputTokens = response.usage?.input_tokens ?? 0;
  const outputTokens = response.usage?.output_tokens ?? 0;

  return { inputTokens, outputTokens, totalTokens: inputTokens + outputTokens };
}

3: Calculate the corresponding USD value

Each model has its own rate for input and output tokens. After retrieving the token counts, calculate the cost for each, then add them together to get the total usage cost.

const MODEL_RATES = {
  "gpt-4.1-mini": { inputPer1K: 0.30, outputPer1K: 1.20 },
  "gpt-4o-mini":  { inputPer1K: 0.15, outputPer1K: 0.60 },
};

export function calculateUSD(model: string, inputTokens: number, outputTokens: number) {
  const rate = MODEL_RATES[model];
  if (!rate) throw new Error(`No pricing configured for model: ${model}`);

  const inputCost = (inputTokens / 1000) * rate.inputPer1K;
  const outputCost = (outputTokens / 1000) * rate.outputPer1K;

  return inputCost + outputCost;
}

4: Record token usage in your ledger

Like we defined earlier in our money movement map, both the token usage and dollar cost will be recorded together as one atomic write.

To accurately record usage, both token usage and corresponding USD should be tracked & atomically linked in your ledger.

To do this with Blnk, make a request to our Bulk Transaction endpoint:

curl -X POST http://localhost:5001/transactions/bulk \
  -H "Content-Type: application/json" \
  -H "X-Blnk-Key: YOUR_API_KEY" \
  -d '{
    "atomic": true,
    "run_async"@: false,
    "transactions": [
        {
            "amount": 2290,
            "precision": 1,
            "currency": "TOKENS",
            "reference": "ref_ai-billing_001_tokens",
            "source": "@Token-Wallet",
            "destination": "@System-Tokens",
            "description": "Token leg",
            "allow_overdraft": true
        },
        {
            "amount": 60.25,
            "precision": 100,
            "currency": "USD",
            "reference": "ref_ai-billing_001_usd",
            "source": "bln_964e2037-c399-4f46-b566-6a84681600f7",
            "destination": "@Revenue",
            "description": "USD leg",
            "allow_overdraft": false
        }
    ]
  }'

This workflow ensures that customers are charged accurately for what they use. The response includes a batch_id, which serves as the key linking both legs of the transaction in your ledger.

Both entries get recorded and are paired in your ledger. Xavier Woods gets debited, and revenue earned is tracked in a dedicated wallet.

Note: You can use meta_data to attach extra details to each transaction, such as the model name, prompt type, or customer ID if you wish to.

Also:

precision= 1: Tokens aren’t measured in decimals, so the precision is set to 1 by default.
reference: Use a stable, unique identifier for easy tracing. For example, include the customer ID, model, timestamp, and transaction type in the reference, e.g. ref_cus123_gpt40mini_1294892983_tokens and ref_cus123_gpt40mini_1294892983_usd.

Handling prepaid vs postpaid

With prepaid billing, the customer funds their wallet before using your product. As they consume tokens:

The corresponding dollar cost is deducted from the customer wallet.
If the wallet balance becomes insufficient or reaches zero, the transaction fails and the workflow stops.
The customer must top up their wallet to continue using the product.

With postpaid billing, the flow works differently:

The customer doesn’t need to fund their wallet in advance.
As usage accumulates, the balance moves into overdraft (using allow_overdraft: true in the dollar leg of the transaction)
The overdraft balance represents how much the customer owes.
At the end of the billing period, you can retrieve this overdraft amount to generate an invoice.
Once payment is made, the balance resets to zero and the next cycle begins.

Wrapping it up

Congratulations! You’ve just built an AI billing system that finally gets accuracy right.

Here’s what we did:

Implemented a wallet system to track usage per customer.
Linked token usage and dollar cost atomically in the ledger — works for one or multiple LLM models.
Enabled both prepaid and postpaid billing without breaking anything.

If you have any questions about this guide, reach out on Discord or send us a message.

#UsageBasedBilling #AIBilling #LLMOps #AIInfrastructure #BillingSystems #PaymentInfrastructure #LedgerSystems #DoubleEntryAccounting #TokenBilling #APIs #BackendEngineering #DeveloperTools #OpenSourceFintech #FintechEngineering #MoneyMovement
‍

How to Build Escrow Payments for Online Marketplaces

Etop - Essien Emmanuella Ubokabasi — Thu, 22 Jan 2026 14:23:15 +0000

A practical guide to building a marketplace ledger using an open-source and immutable system that accurately tracks buyers, sellers, escrow, settlements, and complex money movement from day one.

When you have a product where your users fall into these two buckets — buyers or sellers — you have a marketplace.

Building a marketplace means, as a developer, you’ll have to think about to handle money when buyers pay sellers for goods/services. At first, it may seem like a simple accounting problem, but marketplaces have very specific money movement needs that makes a generic debit-minus, credit-plus approach insufficient.

You’ll want your system to track:

Who owns what and at what point in time
How money flows during deposits, purchases, withdrawals, escrow, refunds, chargebacks, etc.
Event-level accuracy per transaction, rather than just end of day balances.
Sync between your records and your payment processors, application logic, third-party analytics tools, etc.
So how do you build one?

Setting up your infrastructure

First things first, start with a ledger.

Before you start to think about money workflows, payment logic, etc., you need to think about the infrastructure that’ll power them. For this guide, we’ll use our open-source ledger, Blnk Core, as our starting point.

git clone https://docs.blnkfinance.com && cd blnk

As a marketplace, there are always three first-class entities:

Buyer: Users making a purchase
Seller: Users offering goods & services in exchange for money
Organization (you): The platform making it all possible.

In your ledger (Blnk), you start by replicating this structure via ledger folders. Here, we’ll create two ledgers:

General Ledger (default): For the organization (you).
Customers Ledger: For the buyers and sellers. A customer can either be a buyer, seller, or both. To create a ledger:

curl -X POST http://localhost:5001/ledgers \
    -H 'Content-Type: application/json' \
    -H 'X-blnk-key: YOUR_API_KEY' \
    -d '{
        "name": "Customers Ledger"
    }'

You could apply this ledger design to larger, more complex products, e.g. a global marketplace like Fiverr could create customer ledgers per currency/country. A product like Fiverr could have Customers USD Ledger, Customers GBP Ledger, and Customers JPY Ledger for customers transacting in USD, GBP, and JPY respectively.

Tracking money owned with balances

Next, we need to solve for “who owns what?”

In real life, funds are not truly stored per user per vault somewhere. They’re typically pooled together into a kind of operational fund. Ownership is represented digitally, and this is where errors creep up on most developers.

So using our created ledger, we’ll create a balance for each user.

curl -X POST http://localhost:5001/balances \
    -H 'Content-Type: application/json' \
    -H 'X-blnk-key: YOUR_API_KEY' \
    -d '{
        "currency": "USD",
        "ledger_id": "customers-ledger-id"
    }'

Here’s what happens:

A balance is created for the user with a balance_id.
This balance is grouped as being a part of the customers ledger. This means when you see a balance with the customers ledger id, it tells you that this balance belongs to a customer.
The balance is assigned a currency (by you). You could give it any currency you want.

Your balances table with newly created balances | Blnk Cloud
Now, you have your ledger all set up and ready for transactions.

Don’t worry about your organization balances yet, we’ll come back to that when we start recording transactions.

Implementing transaction workflows

In Blnk, transactions happen between balances. When User A sends money to User B, what happens in the ledger is a transaction from User A’s balance to User B’s balance.

However, transactions are not always that simple. You have a lot of things you want to solve for per transaction and your ledger needs to be able to work with it.

For this guide, we'll work on 3 common workflows:

Deposits
Purchases between a buyer and a seller
Withdrawals & settlements

Deposits

In some marketplaces, buyers are given a wallet to fund before they are able to buy while in other case, buyers directly pay from their card or bank account.

For this example, we’ll select the former scenario.
Deposits
In some marketplaces, buyers are given a wallet to fund before they are able to buy while in other case, buyers directly pay from their card or bank account.

For this example, we’ll select the former scenario.

Simplified deposit money movement map for most marketplaces

This workflow is straightforward. All you need to do is add money to buyer’s balance in our ledger. However, Blnk is double-entry, i.e. if you’re adding money somewhere, it needs to be deducted elsewhere.

In this case, the “deduction” is happening from outside our marketplace. To represent this, we’ll create an internal balance (@World) belonging to our organization to represent money coming in from outside.

curl -X POST http://localhost:5001/transactions \
    -H 'Content-Type: application/json' \
    -H 'X-blnk-key: YOUR_API_KEY' \
    -d '{
        "amount": 1200.00,
        "precision": 100,
        "currency": "USD",
        "source": "@World",
        "destination": "buyer-balance-id",
        "reference": "unique-reference",
        "description": "Wallet deposit",
        "allow_overdraft": true
    }'

Here’s what happens:

The buyer’s balance increases by the amount, e.g. $1,200.00 USD.
You have a clear idea of where that amount came from. You can use metadata to add even more context like bank name, payment type, external reference, etc.

User (buyer) balance reflecting the deposit in your ledger | Blnk Cloud

Purchases

Purchases could be prepaid, postpaid, or escrow, depending on your business model. For most products, it is usually a transaction from the buyer (source) to the seller (destination).

For an escrow model, here's a simplified workflow:
Buyer initiates payment.
Platform holds the transaction until purchase conditions are met (e.g. buyer confirms receipt).
Seller sees the incoming payment, but can’t access it yet. Buyer can’t spend any funds held in escrow either.

We’ll create another transaction, but we’ll specify that we want it to be inflight. This tells the ledger that a transaction has happened but it shouldn’t be finalized yet.

curl -X POST http://localhost:5001/transactions \
    -H 'Content-Type: application/json' \
    -H 'X-blnk-key: YOUR_API_KEY' \
    -d '{
        "amount": 500.00,
        "precision": 100,
        "currency": "USD",
        "source": "buyer-balance-id",
        "destination": "seller-balance-id",
        "reference": "unique-reference",
        "description": "Payment for design proposal",
        "inflight": true
    }'

Here’s what happens:

You can see the total balance being held inflight for the buyer and seller.
You can see the inflight state of the transaction in your transactions table, and you can show that in your application.

Let’s assume the conditions for finalizing the transaction are:

Seller confirms delivery.
Buyer confirms receipt and all is good to go . Your code may look something like this:

async function finalizePurchase(transaction_id, buyer_confirmed, seller_confirmed) {
    if (buyer_confirmed && seller_confirmed) {
        // Commit transaction in Blnk
    } else {
        // Void transaction in Blnk
    }
}

This logic says that:

Commit the transaction only after both buyer and seller confirm that everything is complete. This ensures you only settle the seller when the buyer confirms receipt of the package.
If confirmation is missing from either party or a dispute is raised, void the transaction and release the funds back to the buyer. To commit the funds in your ledger:

curl -X PUT http://localhost:5001/transactions/inflight/{transaction_id} \
    -H 'Content-Type: application/json' \
    -H 'X-blnk-key: YOUR_API_KEY' \
    -d '{
        "status": "commit"
    }'

Applied (finalized) transaction after commit action | Blnk Cloud
What happens:

The funds held in inflight is finally deducted from the buyer and added to the seller’s balance.
Since it’s impossible for the buyer to access those held funds, you can always be sure that the transaction will always go through. Blnk handles insufficient fund checks for you.

Seller balance after commit, amount now available for withdrawal | Blnk Cloud

Settlements

Next, users need to be able to withdraw their money. Some products do this automatically once the seller gets paid, while others allow sellers to hold money in their wallet and withdraw any time they want to.

Simplified withdrawals/settlement money movement map for marketplace

The implementation for both workflows are the same. You simply reverse the deposits money movement. This time, money is deducted from the user balance and added to “@World.”

curl -X POST http://localhost:5001/transactions \
    -H 'Content-Type: application/json' \
    -H 'X-blnk-key: YOUR_API_KEY' \
    -d '{
        "amount": 400.00,
        "precision": 100,
        "currency": "USD",
        "source": "seller-balance-id",
        "destination": "@World",
        "reference": "unique-reference",
        "description": "Settlement/withdrawals",
        "inflight": true
    }'

Remember, “@World” is how we represent “outside” in our ledger, i.e. for withdrawals, we’re sending money outside of our product.

What else can you build?

Like you’ve seen, your money movement cannot be solved by just setting up simple accounting tables in your database. If you hope to grow your business or add creative features that affect how users pay in your app, an expert ledger is a no-brainer.

So what else can your marketplace ledger (Blnk) have:

Overdrafts: Offer and manage instant settlements to sellers based on their pending receivables.
Refunds: Safely handle reversals when requested with full auditability.
Split payments and fees: Most marketplace fees charge a fee per purchase. Track your organization’s take with full transparency to the user.
Delayed settlements and payouts: Track third-party payment processing in your ledger, e.g. Use inflight to model ACH settlements and only commit once the payout is confirmed.

Get started with Blnk to try it out yourself.

#EscrowPayments #MarketplacePayments #FintechEngineering #PaymentInfrastructure #DigitalWallets #LedgerSystems #DoubleEntryAccounting #MoneyMovement #Settlement #InFlightTransactions #BackendEngineering #APIEngineering #SystemDesign #OpenSourceFintech #PaymentsArchitecture #DeveloperTools #FinancialInfrastructure #DevRel

Identity Management in Fintech: Why It Matters

Etop - Essien Emmanuella Ubokabasi — Thu, 22 Jan 2026 10:13:50 +0000

Learn why identity is important and how to handle it in your application

Identity in fintech boils down to knowing who is involved in storing or moving assets within your organization. It is about identifying, verifying, and tying those assets to a real-world person or entity.

Done right, it is the backbone of trust and compliance. Done wrong, it is a gaping hole for fraud and regulatory nightmares. Let us break down why this matters, how to manage personal identifiable information (PII), why KYC (Know Your Customer) is non-negotiable, and how tools like Blnk Finance can help.

Why Identity Management Matters

Identity is not just a checkbox. It is a safeguard. Here is why it is critical:

Regulation: Governments and financial authorities operate with strict oversight. Laws like AML (Anti-Money Laundering) and GDPR require you to know who you are dealing with and handle their data responsibly. Non-compliance can result in fines, sanctions, or other penalties.
Fraud: Without robust identity checks, criminals can impersonate users, siphon funds, or launder money through your system. Proper identity management prevents this before it starts.
Accurate Records: Assets must be linked to real entities for audits, disputes, or reporting. If you cannot trace who owns what, chaos erupts. Think lawsuits or lost trust.

Ignoring identity management is not an option. It is the difference between a secure operation and a house of cards.

Handling Personal Identifiable Information (PII)

PII includes names, addresses, SSNs, anything that can identify someone. Mishandle it, and you risk breaches or fines. Here is how to get it right:

Tokenization: Replace sensitive data with unique tokens. Standard tokenization swaps PII for randomized strings. Format-preserving tokenization keeps the data’s structure (like a credit card number) but scrambles the value. Both keep raw data out of reach while letting systems function.
Access Control: Not everyone needs to see everything. Define who can create, view, or edit PII. Role-based access ensures only authorized staff touch sensitive data, cutting down on leaks or insider threats.

Handling PII is not just about tech. It is about discipline. A single misstep can undermine trust or invite regulatory scrutiny.

Why KYC (Know Your Customer) Is Essential

Collecting and storing identities is step one. Verifying they are who they say they are is step two. KYC is not optional; regulators mandate it, and your security depends on it. Here are common checks to run:

Sanctions: Cross-check identities against global sanctions lists. Engaging with a sanctioned entity can disrupt your operations.
PEP (Politically Exposed Persons): PEPs carry higher corruption risks. Flag them for extra scrutiny to avoid enabling bribery or influence peddling.
Advanced Media Search: Dig through news and public records for red flags like fraud or criminal history tied to the identity.
Government Identity Verification: Validate IDs against official databases (passports, driver’s licenses). Forged documents are common; do not take chances.
Address Verification: Confirm the person lives where they claim. It is a simple way to catch discrepancies early.
Age Verification: Critical for age-restricted services like lending or investing. Minors slipping through can trigger legal complications.

KYC is not a one-and-done task. It is ongoing. People change, risks evolve, and regulators keep watching.

How Blnk Helps Ease the Burden of Identity Handling

Blnk helps ease the burden of identity management with tools built for fintech demands. Here is what it offers:

Identity Module: Capture identities and tokenize them using techniques like Standard Tokenization (randomized strings) or Format-Preserving Tokenization (same format, scrambled data). Keeps PII secure without breaking your workflows.
Access Control: Decide who can create, view, or modify identities. Granular permissions mean fewer hands on sensitive data, reducing risk.
Blnk Cloud Features: Out-of-the-box PEP and sanctions list checks. No need to build your own database or integration; it is ready to go.

Conclusion

Identity management in fintech is not a nice-to-have. It is a must-have. From dodging fraud to meeting regulations to keeping records straight, knowing who you are dealing with underpins everything.

Handle PII with care, using tokenization and access controls. Prioritize KYC with rigorous checks like sanctions, PEP, and government ID verification. Tools like Blnk can streamline the process, offering modules for capture, tokenization, and compliance checks out of the box.

Get it right, and you build trust. Get it wrong, and you risk it all.
#Fintech #IdentityManagement #DigitalPayments #CardPayments #PaymentSystems #Authorization #Settlement #LedgerSystems #OpenSource #DeveloperTools #APIs #BackendDevelopment #NodeJS #TypeScript #NextJS #WebDevelopment #FinancialInfrastructure #BankingTechnology #PaymentsEngineering

How to Build a Wallet with Stripe & Blnk Finance

Etop - Essien Emmanuella Ubokabasi — Thu, 22 Jan 2026 08:59:59 +0000

Process payments with Stripe and track them with your Blnk Core.

Wallets are one of the most popular fintech products in the world today. It serves a wide range of use cases from traditional fintech apps like CashApp to other app categories like eCommerce (Shopify), travel (Booking.com), gaming (Call of Duty Mobile), etc.

To use a wallet, you typically add money from a bank account or credit card before making transactions in the app.

In this guide, we’ll show you how to build a wallet product step-by-step using Blnk Finance, with Stripe as your payment provider, to create a smooth and reliable experience.

The User Experience

Let’s create a wallet feature for an eCommerce app using AcmePay, a payment method that offers 5% cashback on checkout purchases. When users sign up, an AcmePay wallet is automatically created for them. Here’s how it works:

Users fund their AcmePay wallet via bank transfer or credit/debit card.
At checkout, users choose AcmePay as their payment option.
The purchase amount is deducted from their AcmePay wallet balance.
Users receive 5% cashback, credited directly to their AcmePay wallet.

To build this, you need the following:

A payment provider to handle online payments. We'll use Stripe for this guide
A double-entry ledger to accurately track transactions and wallet balances.

Money Movement Map

First, start by determining how money moves in our system for each transaction — wallet funding, making a purchase, and receiving cashback. This provides a bird's eye view of the flow of funds within AcmePay.

Simplified money movement map for AcmePay

Next, we set up our ledger architecture. Our ledger is how we know how much each user has in our system because Stripe will only show the total amount deposited across all users in our system.

Ledgers helps you keep an accurate record of how much belongs to each user in your application.

1. Implementing Our Wallet

Now that we've defined our user experience and money movement map, let's dive into building our wallet. To follow this guide, you need to have a live instance of Blnk Core and a Stripe account.

Step 1: Set up your Users Ledger

You need to create a ledger to keep track of all balances created for users in AcmePay. This is the only ledger we need to create for this guide.

To set up our Users Ledger, make a request to the Create Ledger endpoint as follows:

curl --request POST \
  --url http://localhost:5001/ledgers \
  --header 'Content-Type: application/json' \
  --data '{
    "name": "Users Ledger",
    "meta_data": {
      "organization": "AcmePay",
      "description": "For all users wallet created & managed by Acme."
    }
  }'

Step 2: Creating the user wallet

To create the user wallet, we'll do the following:

Create a customer on Stripe, and retrieve the customer id.
Create an identity on Blnk and add the Stripe customer id to its metadata.
Create a balance on Blnk using the identity id from Blnk.

I. Create a customer on Stripe

This helps us identify the user when they fund their wallet via Stripe checkout.

const stripe = require('stripe')('sk_test_51Q8vs7Rr ... Eh00okDxEs1L');

const customer = await stripe.customers.create({
  name: "Charles Xavier",
  email: "charlesxavier@example.com",
  metadata: { "userId": "123" }
});

II. Create an identity on Blnk

This helps us identify the user within our ledger. Once linked to a balance, all transactions performed by the balance can be traced to a user.

async function createIdentity(stripe_created_id, User) {
  const response = await axios.post(
    'http://localhost:5001/identities',
    {
      first_name: User.firstName,
      last_name: User.lastName,
      email: User.email,
      meta_data: {
        stripe_id: stripe_created_id
      }
    },
    {
      headers: {
        'Content-Type': 'application/json',
        'X-blnk-key': 's_key_x7k9p-4m2nq-8r5t-1v3wy-z6bjd'
      }
    }
  );

  console.log("Customer Identity created:", identity.data.identity_id);
  return identity.data.identity_id;
}

III. Create a balance for the user

This is how we store cash balances and record transactions that the user makes within our application.

async function createMainWallet(ledgerId, identityId, currency) {
  const balances = await axios.post("http://localhost:5001/balances",
    {
      ledger_id: ledgerId,
      identity_id: identityId,
      currency: currency,
      meta_data: {
        wallet_type: "main"
      }
    },
    {
      headers: {
        "Content-Type": "application/json"
      }
    }
  );

  const balanceId = balances.data.balance_id;
  console.log("Main Wallet created:", balanceId);
  return balanceId;
}

2. Wallet Funding

To handle wallet top-up, we will:

Get the amount from the customer via the app.
Initiate a Stripe checkout session with customer's email or id and generate a unique reference id.
Listen for webhooks to know when the payment is created or completed.
Create a transaction in the ledger to update your user's balance. Use the same reference id.

Step 1: Create a new Stripe checkout payment

Start by creating an inflight transaction to initiate the payment in your ledger. This creates the transaction but doesn't apply it to the balances until payment is confirmed by Stripe.

Make sure to generate a unique reference id for each new transaction in your app.

async function walletFunding(reference, amount, currency, customerBalanceId, stripeSessionId, paymentMethod) {
  const response = await axios.post("http://localhost:5001/transactions",
    {
      amount: amount,
      precision: 100,
      currency: currency,
      reference: "ref_acmepay-01",
      source: "@Stripe",
      destination: customerBalanceId,
      allow_overdraft: true,
      inflight: true,
      description: "Topup via Stripe",
      meta_data: {
        payment_method: paymentMethod
      }
    },
    {
      headers: {
        "Content-Type": "application/json"
      }
    }
  );

  const transactionId = response.data.transactionId;
  console.log("Transaction created:", transactionId);
  return transactionId;
}

Next, create a Stripe amount using the same reference and adding the transaction and balance id to the metadata:

const stripe = require('stripe')('sk_test_...');
const session = await stripe.checkout.sessions.create({
  payment_method_types: ['card'],
  line_items: [
    {
      price_data: {
        currency: 'usd',
        product_data: {
          name: 'Top-up',
        },
        unit_amount: 2000,
      },
      quantity: 1,
    },
  ],
  metadata: {
    blnk_balance_id: "bln_ 123",
    blnk_transaction_id: transactionId
  },
  mode: 'payment',
  success_url: 'https://yourdomain.com/success',
  cancel_url: 'https://yourdomain.com/cancel',
  client_reference_id: 'ref_acmepay-001'
});

Step 2: Listen for webhooks to know when the payment is captured

Set up a webhook handler to listen for events from Stripe. Then use these events to handle updating the status of the inflight transaction in your ledger.

If successful, the inflight transaction is committed. If failed or expired, it is voided.

const express = require('express');
const app = express();
const stripe = require('stripe')('sk_test_51Q8v ... MnEh00okDxEs1L');
const endpointSecret = 'whsec_b653c958ed ... 578088ea2';

app.post('/webhook', express.raw({ type: 'application/json' }), (request, response) => {
  const sig = request.headers['stripe-signature'];
  let event;
  try {
    event = stripe.webhooks.constructEvent(request.body, sig, endpointSecret);
  } catch (err) {
    response.status(400).send(`Webhook Error: ${err.message}`);
    return;
  }

  const session = event.data.object;
  console.log('Checkout session completed:', session.id);

  if (event.type === 'checkout.session.completed') {
    function commitPayment(session.metadata.blnk_transaction_id)
  } else if (event.type === 'checkout.session.async_payment_failed' || 'checkout.session.expired') {
    function voidPayment(session.metadata.blnk_transaction_id)
  }

  response.status(200).end();
});

app.listen(4242, () => console.log('Running on port 4242'));

Step 3: Update the user balance in your ledger

If successful, commit the inflight transaction in your ledger to update your user's balance.

async function commitPayment(transactionId) {
  const url = `http://localhost:5001/transactions/inflight/${transactionId}`
‍
  const response = await axios.put(url,
    {
      status: "commit"
    },
    {
      headers: {
        "Content-Type": "application/json"
      }
    }
  );

  const transactionId = response.data.transactionId;
  console.log("Transaction committed:", transactionId);
  return transactionId;
}

If failed, void the transaction instead:

async function voidPayment(transactionId) {
  const url = `http://localhost:5001/transactions/inflight/${transactionId}`
‍
  const response = await axios.put(url,
    {
      status: "void"
    },
    {
      headers: {
        "Content-Type": "application/json"
      }
    }
  );

  const transactionId = response.data.transactionId;
  console.log("Transaction voided:", transactionId);
  return transactionId;
}

4. Crediting user cashback

Once the purchase has been completed, we record another transaction to credit the customer with their cashback reward from an internal Cashback balance in our ledger:

const cashbackAmount = 0.05 x purchaseAmount;
‍
async function creditCashback(reference, cashbackAmount, currency, customerBalanceId) {
  const response = await axios.post("http://localhost:5001/transactions",
    {
      amount: cashbackAmount,
      precision: 100,
      currency: currency,
      reference: reference,
      source: "@CashBack",
      destination: customerBalanceId,
      description: "Cashback reward"
    },
    {
      headers: {
        "Content-Type": "application/json"
      }
    }
  );

  const transactionId = response.data.transactionId;
  console.log("Cashback credited:", transactionId);
  return transactionId;
}

Conclusion

This guide covers the key steps for managing a wallet, but there are still several important challenges and considerations you’ll need to address when building your wallet product.

For example, you may need to correct an error in your transactions. Since Blnk is immutable, it is impossible to edit a transaction that has been created. The only way to do it is to first refund the transaction, and then post the correct record.

Other considerations include, performing some checks before completing a transaction, handling Stripe refunds, managing wallet withdrawals, and collaborating with other teams like Customer Support for access to your users' financial data.

Getting started

This article outlined a straightforward way to designing a wallet product, however it doesn't cover all of the unique complexities that different wallet products may involve.

If you have questions about how to build your specific use case with Blnk, feel free to reach out to us via Support or contact Sales.

#ledger #walletfunding #stripe #blnkfinance #fintech #payments #banking #api #tutorial

A Practical Guide to Building Your First Card Payment System with Blnk Finance

Etop - Essien Emmanuella Ubokabasi — Fri, 09 Jan 2026 06:28:05 +0000

A step-by-step guide for developers to implement card payments with authorization and settlement flows

Introduction

Have you ever wondered how card payments actually work behind the scenes? When you swipe your card at a store, your money doesn't instantly leave your account. Instead, there's a fascinating two-step process: authorization (holding the funds) and settlement (actually moving the money).

In this guide, we'll show you how to build a fully functional e-commerce demo that implements this exact flow using Blnk Finance — an open-source ledger for building fintech products.

We'd demonstrate using a simple online store where users can create a virtual card, shop for products, and where merchants can accept or reject payments.

To build this you need the following:

Node.js (v18 or higher) installed
Docker installed and running
Basic knowledge of TypeScript and React

If you'd like to see the live demo of the e-commerce store and a step-by-step code explanation, check out the video below:
Build A Card Payment System with Blnk Finance

Note: In the video above, I specifically focus on the Inflight Transaction log, demonstrating how Blnk ensures financial integrity during the authorization hold phase.

The Money Movement Map

Let's design how money will flow in our system before writing any code. The Money Movement Map is the blueprint for your financial application.

Funding comes from @WorldUSD (external source) to the customer's card. When the customer pays, funds are held (not moved yet). Thereafter, when the merchant accepts → funds move permanently. Merchant rejects → funds released.

Next, let's understand some important terms:

1.Ledger: Think of it as a folder that contains all the balances for a specific purpose.

{
  "ledger_id": "ldg_5885cfce-873f-46ec-a4ec-a2204d2fff3d",
  "name": "Alice's Card Ledger",
  "created_at": "2026-01-08T00:39:06.160464Z",
  "meta_data": null
}

Field	What it means
`ledger_id`	Unique identifier for this ledger (starts with `ldg_`)
`name`	Human-readable name you assign
`created_at`	When the ledger was created
`meta_data`	Optional custom data you can attach

For example, if you're a bank, you might have separate ledgers for "Savings Accounts", "Card Accounts", "Loan Accounts", etc.

2.Identity: represents a customer or entity in your system.

{
  "identity_id": "idt_0449e806-262c-48d4-b07a-6d45d24f2704",
  "identity_type": "individual",
  "first_name": "Alice",
  "last_name": "User",
  "email_address": "alice@gmail.com",
  "category": "customer",
  "nationality": "US",
  "created_at": "2026-01-08T00:39:06.44318Z"
}

Field	What it means
`identity_id`	Unique identifier (starts with `idt_`)
`identity_type`	`individual` or `organization`
`first_name`, `last_name`	Customer's name
`category`	Your custom categorization (e.g., "customer", "merchant")

3.Balance: an actual account that holds money. It belongs to a ledger and can be linked to an identity.

{
  "balance_id": "bln_51658b42-577c-4922-8d7e-8726e41230e3",
  "balance": 95500000,
  "credit_balance": 100000000,
  "debit_balance": 4500000,
  "inflight_balance": null,
  "currency": "USD",
  "ledger_id": "ldg_5885cfce-873f-46ec-a4ec-a2204d2fff3d",
  "meta_data": {
    "card_id": "card-1767832745473",
    "card_scheme": "visa",
    "last_4_digits": "1234",
    "type": "virtual"
  }
}

Field	What it means
`balance_id`	Unique identifier (starts with `bln_`)
`balance`	Current available balance (in smallest unit, e.g., cents)
`credit_balance`	Total money received (credits)
`debit_balance`	Total money sent out (debits)
`inflight_balance`	Money currently held/reserved (pending transactions)
`currency`	The currency code (USD, EUR, etc.)
`meta_data`	Custom data (we store card details here)

Blnk stores amounts as integers to avoid floating-point errors. With precision: 100, the value 95500000 means $955.00 (divide by 100 for dollars, then by 100 again for the precision multiplier).

4.Transaction: records money moving from one balance to another.

{
  "transaction_id": "txn_d1ccdfe7-b944-4bf3-88f4-4fa5daa0087e",
  "amount": 79900,
  "precise_amount": 7990000,
  "precision": 100,
  "source": "bln_51658b42-577c-4922-8d7e-8726e41230e3",
  "destination": "bln_612c7f52-7bb0-4a49-9251-90dd3ec6ef70",
  "reference": "AUTH-1767841533907",
  "currency": "USD",
  "description": "Purchase of 2 items",
  "status": "QUEUED",
  "inflight": true,
  "created_at": "2026-01-08T03:05:35.759002Z"
}

Field	What it means
`transaction_id`	Unique identifier (starts with `txn_`)
`amount`	The transaction amount
`precise_amount`	Amount × precision (for exact calculations)
`source`	Balance ID money comes FROM
`destination`	Balance ID money goes TO
`reference`	Your unique reference (for idempotency)
`status`	Current state: `QUEUED`, `INFLIGHT`, `APPLIED`, `VOID`
`inflight`	If `true`, this is a pending/held transaction

5.Inflight Transactions: is Blnk's way of handling the authorization → settlement flow (i.e, your pending transactions).

When you set inflight: true the transaction is created but NOT finalized. The funds are reversed (held) from the source balance. The transaction then stays in INFLIGHT status. later, you can commit (finalize) or void (cancel) it

Transaction Status Flow:

For example,
⇒You swipe your card at a restaurant for $50
⇒Your bank authorizes (creates inflight transaction) — $50 is held
⇒Your available balance shows $50 less
⇒Hours later, the restaurant settles (commits) — money actually moves
⇒OR, if you cancel, the restaurant voids — $50 is released back

6.Internal Balances (@world): Balances starting with @ are internal balances. They represent external sources/destinations.

@WorldUSD: Represents money entering/leaving your system
@Merchant: — Could represent a merchant account
@Bank: Could represent your bank connection

These are automatically created when first used.

Setting Up the Project

Step 1: Set Up Blnk Core

First, we need to get Blnk Core running locally. Start by cloning the Blnk repository, which contains the core ledger system we'll be connecting to. After cloning, you'll need to create a blnk.json configuration file to set up your Blnk instance. This configuration file tells Blnk how to run, what port to use, database connections, and other important settings. Once configured, launch Blnk using Docker, which will start the ledger server on your local machine.

Clone the Blnk repository:

git clone https://github.com/blnkfinance/blnk.git
cd blnk

Set up your configuration by creating a blnk.json file in the repository root. This file configures how Blnk Core will run, including database connections, Redis settings, server port, and notification preferences:

{
  "project_name": "Blnk",
  "data_source": {
    "dns": "postgres://postgres:password@postgres:5432/blnk?sslmode=disable"
  },
  "redis": {
    "dns": "redis:6379"
  },
  "server": {
    "domain": "blnk.io",
    "ssl": false,
    "ssl_email": "your-email@example.com",
    "port": "5001"
  },
  "notification": {
    "slack": {
      "webhook_url": "https://hooks.slack.com"
    }
  }
}

This configuration sets up Blnk to use PostgreSQL for data storage, Redis for caching, and runs the server on port 5001.

Launch Blnk with Docker:

docker-compose up

Install the Blnk CLI globally, which provides helpful commands for managing your Blnk instance:

npm i -g @blnkfinance/blnk-cli

Verify Blnk is running by visiting: http://localhost:5001/ledgers

Step 2: Install Blnk TypeScript SDK and Create Next.js Project

Before creating our Next.js application, we need to install the Blnk TypeScript SDK, which provides all the functions we need to interact with Blnk Core.
First, install the Blnk TypeScript SDK. You can do this globally or we'll install it in the Next.js project directory in the next step:

First, install the Blnk TypeScript SDK. You can do this globally or we'll install it in the Next.js project directory in the next step:

npm install @blnkfinance/blnk-typescript

Now create the Next.js project with TypeScript support, Tailwind CSS for styling, and the App Router (Next.js 14's routing system). After creating the project, we'll install the Blnk TypeScript SDK in the project directory:

npx create-next-app@latest blnk-store --typescript --tailwind --app
cd blnk-store
npm install @blnkfinance/blnk-typescript

Step 3: Configure Environment Variables

The API key can be left empty if you're running Blnk locally without authentication. Create a .env.local file in your project root:

BLNK_API_KEY=
BLNK_CORE_URL=http://localhost:5001

Step 4: Initialize the Blnk SDK

This sets up a connection to Blnk Core that we'll reuse throughout our application. It uses a singleton pattern, which means we create the Blnk SDK instance once and reuse it for all API calls. This is more efficient than creating a new connection every time. Create src/lib/blnk.ts:

import { BlnkInit } from '@blnkfinance/blnk-typescript';

let blnkInstance: Awaited<ReturnType<typeof BlnkInit>> | null = null;

export async function getBlnkInstance() {
  if (!blnkInstance) {
    const baseUrl = (process.env.BLNK_CORE_URL || 'http://localhost:5001').replace(/\/$/, '');
    blnkInstance = await BlnkInit(process.env.BLNK_API_KEY || '', {
      baseUrl,
    });
  }
  return blnkInstance;
}

Implementing the Backend (Server Actions)

Now let's implement the core functionality. Create src/app/actions.ts:

Creating a Card Account

This helps create four essential components in sequence: a ledger to organize the customer's accounts, an identity to represent the customer, a balance to serve as the actual card account, and a funding transaction to add initial money to the card. Each step depends on the previous one, so we create them in order and use the IDs returned from each step for the next:

'use server';

import { getBlnkInstance } from '@/lib/blnk';

export async function createCardAccount(name: string, email: string) {
  const blnk = await getBlnkInstance();
  const { Ledgers, Identity, LedgerBalances, Transactions } = blnk;

  try {
    // Step 1: Create a Ledger
    console.log('Creating Ledger...');
    const ledger = await Ledgers.create({
      name: `${name}'s Card Ledger`,
    });
    const ledgerId = ledger.data.ledger_id;
    console.log('Ledger created:', ledgerId);

    // Step 2: Create an Identity
    console.log('Creating Identity...');
    const [firstName, lastName] = name.split(' ');
    const identity = await Identity.create({
      identity_type: "individual",
      first_name: firstName || name,
      last_name: lastName || 'User',
      email_address: email,
      phone_number: '+1234567890',
      gender: 'other',
      dob: new Date('1990-01-01'),
      nationality: 'US',
      category: 'customer',
      street: '123 Main St',
      country: 'US',
      state: 'NY',
      post_code: '10001',
      city: 'New York',
    });
    const identityId = identity.data.identity_id;
    console.log('Identity created:', identityId);

    // Step 3: Create a Card Balance
    console.log('Creating Card Balance...');
    const balance = await LedgerBalances.create({
      ledger_id: ledgerId,
      identity_id: identityId,
      currency: "USD",
      meta_data: {
        last_4_digits: "1234",
        card_scheme: "visa",
        type: "virtual",
        card_id: `card-${Date.now()}`
      }
    });
    const balanceId = balance.data.balance_id;
    console.log('Card Balance created:', balanceId);

    // Step 4: Fund the card with initial balance
    console.log('Funding card...');
    await Transactions.create({
      amount: 1000000, // $10,000.00
      precision: 100,
      reference: `FUND-${Date.now()}`,
      description: "Initial Funding",
      currency: "USD",
      source: "@WorldUSD",
      destination: balanceId,
      allow_overdraft: true
    });
    console.log('Card funded with $10,000');

    return { success: true, ledgerId, identityId, balanceId };
  } catch (error) {
    console.error("Error:", error);
    return { success: false, error: error.message };
  }
}

This creates a ledger that acts as a container for this customer's accounts. Second, it creates an identity that represents the customer profile with their personal information. Third, it creates a balance that serves as the actual card account that will hold money. Finally, it creates a funding transaction that adds $10,000 from @WorldUSD, which represents an external source of money entering the system.

Authorizing a Payment (Creating Inflight Transaction)

When a customer completes checkout, we need to authorize the payment by creating an inflight transaction. T This tells Blnk to hold the funds without actually moving them yet, which is exactly how real card payments work during the authorization phase:

export async function authorizePayment(
  cardBalanceId: string, 
  amount: number, 
  description: string
) {
  const blnk = await getBlnkInstance();
  const { Transactions } = blnk;

  try {
    const transaction = await Transactions.create({
      amount: amount * 100, // Convert dollars to cents
      precision: 100,
      currency: "USD",
      reference: `AUTH-${Date.now()}`,
      source: cardBalanceId,        // Customer's card
      destination: "@WorldUSD",     // Merchant
      description: description,
      inflight: true                // This makes it a hold!
    });

    console.log('Payment authorized:', transaction.data.transaction_id);
    return { success: true, transaction: transaction.data };
  } catch (error) {
    return { success: false, error: error.message };
  }
}

The status is set to pending

Settling the Transaction (Commit or Void)

After a payment is authorized, the merchant needs to settle it by either accepting or rejecting the transaction.
We'd make a direct API call to Blnk Core's inflight transaction endpoint, sending either a "commit" or "void" action. When committing, the transaction status changes to APPLIED and the money moves permanently. When voiding, the transaction status changes to VOID, and the held funds are released back to the customer

export async function settleTransaction(
  transactionId: string, 
  action: 'commit' | 'void'
) {
  const baseUrl = process.env.BLNK_CORE_URL || 'http://localhost:5001';

  const response = await fetch(
    `${baseUrl}/transactions/inflight/${transactionId}`,
    {
      method: 'PUT',
      headers: {
        'X-blnk-key': process.env.BLNK_API_KEY || '',
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({ status: action })
    }
  );

  const data = await response.json();

  if (action === 'commit') {
    console.log('Transaction committed - money moved permanently');
  } else {
    console.log('Transaction voided - funds released back to customer');
  }

  return { success: true, data };
}

There are two possible outcomes when settling a transaction.

If the merchant commits the transaction, its status becomes APPLIED and the money moves permanently from the customer to the merchant.

If the merchant voids the transaction, its status becomes VOID and all held funds are released back to the customer's available balance.

Building the Frontend

Project Structure

src/
├── app/
│   ├── page.tsx          # Main page
│   ├── actions.ts        # Server actions (backend)
│   └── layout.tsx        # App layout
├── components/
│   ├── CardSetup.tsx     # Account creation form
│   ├── StoreView.tsx     # Product catalog & cart
│   ├── MerchantDashboard.tsx  # Settlement UI
│   ├── Navbar.tsx        # Navigation
│   └── ui.tsx            # Reusable UI components
└── lib/
    ├── blnk.ts           # Blnk SDK initialization
    └── store.tsx         # React Context for state

Connecting Frontend to Backend

When the user clicks "Pay", the frontend calls the authorizePayment() server action. This server action then makes an API call to Blnk Core, creating a transaction with inflight: true to hold the funds. Once the transaction is successfully created, the frontend stores the transaction details in its state management system so it can be displayed in the merchant dashboard for settlement.

// In StoreView.tsx
const handleCheckout = async () => {
  setLoading(true);

  // Call the server action
  const result = await authorizePayment(
    user.balanceId,
    total,
    `Purchase of ${cart.length} items`
  );

  if (result.success && result.transaction) {
    // Store the pending transaction
    addTransaction({
      id: result.transaction.transaction_id,
      amount: total,
      description: `Purchase of ${cart.length} items`,
      status: 'INFLIGHT',
      reference: result.transaction.reference,
      timestamp: new Date().toISOString()
    });

    setSuccess(`Order authorized! Ref: ${result.transaction.reference}`);
    clearCart();
  }

  setLoading(false);
};

Testing the Complete Flow

Let's walk through the entire user journey:

1. Create Account

The user journey begins when a new customer enters their name and email address in the card setup form. Behind the scenes, the system creates a complete account structure: first a ledger to organize their accounts, then an identity to represent the customer, followed by a balance that serves as their virtual card, and finally a funding transaction that adds $10,000 to their card. Once this process completes, the user has a fully functional virtual card with $10,000 ready to use.

2. Shop and Checkout

Users can browse the product catalog, add items to their shopping cart, and proceed to checkout. When they click the "Pay" button, the system creates an inflight transaction that holds the funds from their card balance.

The user selects the products

The order is then successfully placed

3. Merchant Settlement

Once a payment is authorized, the merchant can view all pending orders in their dashboard. When the merchant clicks "Accept", the system commits the inflight transaction, which changes its status to APPLIED and permanently moves the money from the customer to the merchant. Alternatively, if the merchant clicks "Reject", the system voids the transaction, changing its status to VOID and releasing all held funds back to the customer's available balance.

4. Verify in Blnk

Check your Blnk Core directly:

http://localhost:5001/ledgers     # See all ledgers
http://localhost:5001/balances    # See all balances
http://localhost:5001/identities  # See all identities
http://localhost:5001/transactions/{id}  # See specific transaction

Summary

We've built a complete card payment system that demonstrates the core concepts of digital ledger-based payments. Your system includes ledgers that organize customer accounts, identities that represent customers, balances that serve as actual card accounts, inflight transactions that create authorization holds, and settlement functionality that allows merchants to commit or void pending payments.

Ready to dig deeper? Experiment with your project and see the magic for yourself.
If you have questions about how to build your specific use case with Blnk, feel free to reach out to us via Support or Contact Sales.

Resources

From Messy HTML to AI-Ready News Apps with Firecrawl + Lovable

Etop - Essien Emmanuella Ubokabasi — Tue, 06 Jan 2026 08:57:22 +0000

In the era of "Agentic" workflows, the biggest bottleneck isn't the LLM—it’s the data. Most websites are a mess of HTML, ads, and pop-ups that choke standard scrapers.

Firecrawl introduced a native integration with Lovable. The idea is simple but powerful: Firecrawl handles the hard problem of turning the web into clean, LLM-ready data, while Lovable handles everything else—UI, app logic, and deployment.
With this integration, Lovable users can connect directly to Firecrawl’s APIs and build web-data-powered applications without writing traditional scraping code.

I explored what this unlocks in practice. I built Pulse Reader: a modern AI news aggregator that transforms any messy news URL into clean, structured, AI-ready summaries.

Here is the technical breakdown of how I built it using Firecrawl for data ingestion and Lovable for rapid full-stack development.

Traditional web scraping with tools like Puppeteer or BeautifulSoup requires constant maintenance. If a news site changes its CSS classes, your scraper breaks. Furthermore, feeding raw HTML into an LLM is expensive and noisy.

A robust solution must:

Render JavaScript automatically.
Strip layout noise, such as ads and navigation
Convert content into clean Markdown.
Could be integrated into a frontend in minutes.

The Stack

Ingestion: Firecrawl (specifically the /scrape and /extract features).
Frontend/App Logic: Lovable (an AI full-stack engineer tool).
Styling: Tailwind CSS with a Glassmorphism aesthetic.

Configuring the Firecrawl "Engine"

The ingestion layer begins with Firecrawl. An API key provides access to a managed extraction pipeline that replaces custom scrapers entirely.

Firecrawl’s power lies in its simplicity. Instead of writing complex selectors, You can simply tell the API you want the output in Markdown format. This ensures that no matter how messy the source site is, your app receives a clean, standardized string.

"Vibe-Coding" the UI with Lovable

With web data standardized, Lovable handles application generation. Using natural-language instructions, Lovable produces:

The application interface
Data flow wiring
Firecrawl API integration
Deployment-ready output

The Data Flow

When a user pastes a URL (like TechCrunch) into Pulse Reader, the following happens:
⇒ Request: The frontend sends the URL to Firecrawl.
⇒ Extraction: Firecrawl bypasses anti-bot headers, renders the JavaScript, and strips away the "noise" (ads/sidebars).
⇒ Transformation: The clean Markdown is returned to the app.
⇒ UI Render: Pulse Reader takes that Markdown and displays it in beautiful, readable cards.

Over-Delivering with "Copy Markdown"

To support downstream AI workflows, Pulse Reader exposes Copy Markdown and Download Feed actions. This allows extracted content to be reused directly in tools like ChatGPT or Claude without additional cleaning or transformation.

This design ensures that Firecrawl’s output is not only readable but immediately reusable across research, summarization, and agent workflows.

In conclusion

Building Pulse Reader proved that the barrier to building sophisticated data tools has vanished.

Firecrawl is the "clean pipe" for web data. It provides a stable, production-grade ingestion layer for live web data.
Lovable is the high-speed engine for building the interface. It compresses application development into a prompt-driven workflow

Still a work in progress 👉 Check out the Live Demo here