Skip to main content
In this tutorial, we’ll build a simple escrow payment workflow using Blnk’s inflight transaction feature. Here’s what we’ll do:
  1. Initiate an escrow transaction.
  2. Verify that all conditions have been met.
  3. Update the transaction based on the conditions.
  4. Handle alternative use cases cases like partial fulfilment.
For this tutorial, we’ll use the Blnk TypeScript SDK and Blnk Go SDK for the implementation. If you prefer, you can also refer to the API reference for details on the available endpoints.

​
Designing your map

Before writing code, it’s crucial to design a money movement map that outlines how money moves in your system. This serves as the blueprint for your implementation. For our escrow payments workflow, here’s our map: Escrow payments map Explore the map yourself here Read more: Inflight transactions → This map shows three key aspects of the escrow fund flow:
  • Buyer initiates transaction to Seller.
  • Transaction is held inflight until the escrow conditions are met or not.
  • Transaction is completed or discarded depending on the inflight status, and the balances get updated.

​
Set up your implementation

Based on our map, we’ll implement the following steps:
  1. Initiate a transaction with inflight between the Buyer Wallet and the Seller Wallet.
  2. Update the status of our inflight transaction.
    • Commit if the escrow payment is successful.
    • Void if the escrow payment failed.

​
Prerequisites

Before starting, ensure you have:
  1. A running Blnk Core instance (e.g. at http://localhost:5001).
  2. An API key for Blnk (replace YOUR_API_KEY in the code examples). Required for authenticated requests.
  3. Optionally, you can connect your Blnk Core to your Blnk Cloud workspace to view your ledger data.
  4. Balances created for the buyer and seller wallets in your Blnk Ledger. Learn how: Building a Wallet Management System with Blnk →.
  5. Funded the buyer wallet balance in ledger.

​
Initialise your client

Initialize the Blnk client once at the start of your application: 
const { BlnkInit } = require('@blnkfinance/blnk-typescript');

let blnkInstance = null;

async function getBlnkInstance() {
  if (!blnkInstance) {
    blnkInstance = await BlnkInit('', { baseUrl: 'http://localhost:5001' });
  }
  return blnkInstance;
}

​
Initiate escrow transaction

Create a transaction with inflight enabled. 
curl --request POST \
  --url http://localhost:5001/transactions \
  --header 'X-blnk-key: <api-key>' \
  --header 'Content-Type: application/json' \
  --data '{
    "amount": 100.43,
    "precision": 100,
    "reference": "escrow_ref_12345",
    "description": "Escrow payment",
    "currency": "USD",
    "source": "<buyer_balance_id>",
    "destination": "<seller_balance_id>",
    "inflight": true,
    "meta_data": {
      "transaction_type": "escrow",
      "escrow_status": "pending",
      "buyer_confirmation": false,
      "seller_confirmation": false
    }
  }'
When inflight is enabled, the transaction remains pending, ensuring that neither the source nor the destination balance is affected until the specified conditions are met.

​
Path 1: Successful escrow payment

For a successful escrow payment, commit the inflight transaction to apply it to the buyer and seller balances: 
curl --request PUT \
  --url http://localhost:5001/transactions/inflight/<inflight-transaction-id> \
  --header 'X-blnk-key: <api-key>' \
  --header 'Content-Type: application/json' \
  --data '{
    "status": "commit"
  }'

​
Path 2: Failed escrow payment

If the escrow failed, void the inflight transaction instead: 
curl --request PUT \
  --url http://localhost:5001/transactions/inflight/<inflight-transaction-id> \
  --header 'X-blnk-key: <api-key>' \
  --header 'Content-Type: application/json' \
  --data '{
    "status": "void"
  }'

​
Path 3: Partial escrow payment

Escrow payments can also be fulfilled in bits, meaning you can complete part of the total amount over time, e.g., for a $100 transaction, you can commit $30, then $40, then the remaining $30 later. Commit a partial amount from the inflight escrow transaction: 
curl --request PUT \
  --url http://localhost:5001/transactions/inflight/<inflight-transaction-id> \
  --header 'X-blnk-key: <api-key>' \
  --header 'Content-Type: application/json' \
  --data '{
    "status": "commit",
    "amount": 30
  }'
You can also make multiple partial commits and void the remaining inflight amount if needed.

​
Conclusion

This tutorial demonstrated how to build a secure escrow payment system using Blnk’s inflight feature, enabling safe transactions for buyers and sellers. The system includes initiating escrows, tracking confirmations, releasing funds upon mutual agreement, and handling cancellations. With Blnk’s flexible architecture, you can easily adapt this escrow system to various business models, including from marketplace transactions and freelancer payments to real estate deals and complex business contracts.

Inflight transactions

Hold, commit, void, and best practices.