TypeScript

Introduction

In this examples guide, you’ll learn how to implement common real life fintech use-cases with the Blnk TypeScript SDK.

Click on a use-case item to view its sample SDK code. Each example is also linked with a detailed documentation of how it works.

To view the full list of examples, see the following: Blnk TypeScript SDK Code Examples

To view a detailed explanation of this implementation, see the following: Multicurrency wallets

index.js
const { BlnkInit } = require(`@blnkfinance/blnk-typescript`);
const { GenerateRandomNumbersWithPrefix, sleep, BASE_URL } = require(`../util`);

async function main() {
  // Initialize Blnk SDK with configuration
  const blnk = BlnkInit(``, {
    baseUrl: BASE_URL,
    logger: console,
    timeout: 5000,
  });
  const { Ledgers, Transactions, LedgerBalances } = blnk;

  // Create a USD ledger for the customer
  const usdLedger = await Ledgers.create({
    name: `Customer USD Ledger`,
    meta_data: {
      project_name: `SendWorld App`,
    },
  });

  // Error handling: if ledger creation fails, throw an error
  if (usdLedger.data === null) {
    throw new Error(usdLedger.message);
  }
  console.log(usdLedger, Transactions, LedgerBalances);

  // Create a EUR ledger for the customer
  const eurLedger = await Ledgers.create({
    name: `Customer EUR Ledger`,
    meta_data: {
      project_name: `SendWorld App`,
    },
  });
  console.log(`Euro Ledger`, JSON.stringify(eurLedger, null, 2));

  // Create a USD balance within the USD ledger
  const usdBalance = await LedgerBalances.create({
    ledger_id: usdLedger.data.ledger_id,
    currency: `USD`,
    meta_data: {
      customer_name: `Jerry`,
      customer_internal_id: `1234`,
    },
  });
  console.log(`USD Balance`, JSON.stringify(usdBalance, null, 2));

  // Create a EUR balance within the USD ledger
  const eurBalance = await LedgerBalances.create({
    ledger_id: usdLedger.data.ledger_id,
    currency: `EUR`,
    meta_data: {
      customer_name: `Jerry`,
      customer_internal_id: `1234`,
    },
  });
  console.log(`EUR Balance`, JSON.stringify(eurBalance, null, 2));

  // Fund the USD balance with a transaction
  const usdTransaction = await Transactions.create({
    amount: 200,
    precision: 100,
    reference: GenerateRandomNumbersWithPrefix(`ref`, 4),
    description: `payment for service rendered`,
    currency: `USD`,
    source: `@World`,
    destination: usdBalance.data.balance_id,
    allow_overdraft: true,
    meta_data: {
      sender_name: `Future Design LLC`,
      sender_internal_id: `123333`,
    },
  });
  console.log(`USD Funding`, JSON.stringify(usdTransaction, null, 2));

  // Fund the EUR balance with a transaction
  const eurTransaction = await Transactions.create({
    amount: 3500.5,
    precision: 100,
    reference: GenerateRandomNumbersWithPrefix(`ref`, 4),
    description: `invoice A fulfilled`,
    currency: `EUR`,
    source: `@World`,
    destination: eurBalance.data.balance_id,
    allow_overdraft: true,
    meta_data: {
      sender_name: `Nlnk Bank`,
      sender_internal_id: `563825`,
    },
  });

  await sleep(4);  // Wait to simulate async processing
  console.log(`Eur Funding`, JSON.stringify(eurTransaction, null, 2));

  // Debit (withdraw) funds from the USD balance
  const usdDebit = await Transactions.create({
    amount: 200,
    precision: 100,
    reference: GenerateRandomNumbersWithPrefix(`ref`, 4),
    description: `payment for service rendered`,
    currency: `USD`,
    destination: `@World`,
    source: usdBalance.data.balance_id,
    meta_data: {
      sender_name: `Future Design LLC`,
      sender_internal_id: `123333`,
    },
  });
  console.log(`usd debit`, usdDebit);

  // Debit (withdraw) funds from the EUR balance
  const eurDebit = await Transactions.create({
    amount: 1470.49,
    precision: 100,
    reference: GenerateRandomNumbersWithPrefix(`ref`, 4),
    description: `payment for service rendered`,
    currency: `EUR`,
    destination: `@World`,
    source: eurBalance.data.balance_id,
    meta_data: {
      sender_name: `Future Design LLC`,
      sender_internal_id: `123333`,
    },
  });
  console.log(`eur debit`, eurDebit);

  await sleep(4);  // Wait to simulate async processing

  // Check and display the updated USD balance after debits
  const usdBalanceView = await LedgerBalances.get(usdBalance.data.balance_id);
  console.log(`usd balance after debit`, usdBalanceView);

  // Check and display the updated EUR balance after debits
  const eurBalanceView = await LedgerBalances.get(eurBalance.data.balance_id);
  console.log(`eur balance after debit`, eurBalanceView);

  // Transfer funds between USD and EUR wallets
  const usdToEur = await Transactions.create({
    amount: 200,
    precision: 100,
    reference: GenerateRandomNumbersWithPrefix(`ref`, 4),
    description: `payment for service rendered`,
    currency: `USD`,
    destination: eurBalance.data.balance_id,
    source: usdBalance.data.balance_id,
    rate: 0.92,
    meta_data: {
      sender_name: `Future Design LLC`,
      sender_internal_id: `123333`,
    },
  });
  console.log(`usd to eur wallet`, usdToEur);
}

main();

To view a detailed explanation of this implementation, see the following: Escrow application

index.js
const { BlnkInit } = require(`@blnkfinance/blnk-typescript`);
const { BASE_URL, GenerateRandomNumbersWithPrefix } = require(`../util`);

async function main() {
  // Initialize the Blnk SDK with base configuration
  const blnk = BlnkInit(``, {
    baseUrl: BASE_URL,
    logger: console,
  });
  const { Ledgers, LedgerBalances, Transactions } = blnk;

  // Create an escrow ledger for managing escrow accounts
  const escrowLedger = await Ledgers.create({
    name: `Escrow Ledger`,
    meta_data: {
      description: `Ledger for managing escrow accounts`,
    },
  });

  // Check if ledger creation was successful
  if (escrowLedger.data === null || escrowLedger.status !== 201) {
    throw new Error(escrowLedger.message);
  }

  // Create the first escrow balance for Alice
  const escrowBalance1 = await LedgerBalances.create({
    ledger_id: escrowLedger.data.ledger_id,
    currency: `USD`,
    meta_data: {
      account_type: `Escrow`,
      customer_name: `Alice Johnson`,
      customer_id: `alice-5678`,
      account_opened_date: `2024-01-01`,
      account_status: `active`,
    },
  });

  // Check if balance creation for Alice was successful
  if (escrowBalance1.data === null || escrowBalance1.status !== 201) {
    throw new Error(escrowBalance1.message);
  }

  // Create the second escrow balance for Bob
  const escrowBalance2 = await LedgerBalances.create({
    ledger_id: escrowLedger.data.ledger_id,
    currency: `USD`,
    meta_data: {
      account_type: `Escrow`,
      customer_name: `Bob Smith`,
      customer_id: `bob-9701`,
      account_opened_date: `2024-01-01`,
      account_status: `active`,
    },
  });

  // Check if balance creation for Bob was successful
  if (escrowBalance2.data === null || escrowBalance2.status !== 201) {
    throw new Error(escrowBalance2.message);
  }

  // Fund Alice’s escrow account with a deposit
  const fundAlice = await Transactions.create({
    source: `@bank-account`,
    destination: escrowBalance1.data.balance_id,
    amount: 1000,
    precision: 100,
    reference: GenerateRandomNumbersWithPrefix(`release`, 4),
    description: `Funding escrow account`,
    currency: `USD`,
    inflight: true,
    meta_data: {
      transaction_type: `deposit`,
      customer_name: `Alice Johnson`,
      customer_id: `alice-5678`,
      transaction_date: `2024-07-05`,
      payment_verified: false,
    },
  });

  // Check if funding transaction for Alice was successful
  if (fundAlice.data === null || fundAlice.status !== 201) {
    throw new Error(fundAlice.message);
  }

  // Release funds from Alice's escrow account to Bob's escrow account
  const releaseFunds = await Transactions.create({
    amount: 1000,
    precision: 100,
    reference: GenerateRandomNumbersWithPrefix(`release`, 4),
    description: `Releasing escrow funds`,
    currency: `USD`,
    source: escrowBalance1.data.balance_id, // Alice's escrow account balance_id
    destination: escrowBalance2.data.balance_id, // Bob's escrow account balance_id
    meta_data: {
      transaction_type: `release`,
      customer_name: `Alice Johnson`,
      recipient_name: `Bob Smith`,
      transaction_date: `2024-07-05`,
    },
  });

  // Check if funds release transaction was successful
  if (releaseFunds.data === null || releaseFunds.status !== 201) {
    throw new Error(releaseFunds.message);
  }

  // Refund the transaction, moving funds from Alice's escrow account back to the bank account
  const refund = await Transactions.create({
    amount: 1000,
    precision: 100,
    reference: GenerateRandomNumbersWithPrefix(`release`, 4),
    description: `Releasing escrow funds`,
    currency: `USD`,
    source: escrowBalance1.data.balance_id, // Alice's escrow account balance_id
    destination: `@bank-account`, // Destination is set as a bank account for refund
    meta_data: {
      transaction_type: `release`,
      customer_name: `Alice Johnson`,
      recipient_name: `Bob Smith`,
      transaction_date: `2024-07-05`,
    },
  });

  // Check if refund transaction was successful
  if (refund.data === null || refund.status !== 201) {
    throw new Error(refund.message);
  }
}

main();

To view a detailed explanation of this implementation, see the following: Loyalty points

index.js
const { BlnkInit } = require(`@blnkfinance/blnk-typescript`);
const { BASE_URL } = require(`../util`);

async function main() {
  // Initialize the Blnk SDK with base configuration
  const blnk = BlnkInit(``, {
    baseUrl: BASE_URL,
    logger: console,
  });
  const { Ledgers, LedgerBalances, Transactions } = blnk;

  // Create a ledger specifically for customer loyalty points
  const customerLedger = await Ledgers.create({
    name: `Customer Loyalty Points Ledger`,
    meta_data: {
      project_name: `RetailStore App`,
    },
  });

  // Log and check if the ledger creation was successful
  console.log(`customer ledger`, customerLedger);
  if (customerLedger.data === null) {
    throw new Error(customerLedger.message);
  }

  // Create a balance entry for storing loyalty points for a customer
  const pointBalance = await LedgerBalances.create({
    ledger_id: customerLedger.data.ledger_id,
    currency: `POINTS`,
    meta_data: {
      customer_name: `Alice`,
      customer_internal_id: `5678`,
    },
  });

  // Check if balance creation was successful
  if (pointBalance.data === null) {
    throw new Error(pointBalance.message);
  }
  console.log(`Point Balance`, pointBalance);

  // Award points to Alice's loyalty balance as part of a purchase
  const awardPoints = await Transactions.create({
    amount: 100, // Representing 100 points
    precision: 1,
    reference: `purchase-001`,
    description: `Points for purchase`,
    currency: `POINTS`,
    source: `@Store`,
    destination: pointBalance.data.balance_id, // Alice's loyalty point balance_id
    inflight: true,
    meta_data: {
      customer_name: `Alice`,
      purchase_id: `purchase-001`,
    },
  });

  // Check if points award transaction was successful
  if (awardPoints.data === null) {
    throw new Error(awardPoints.message);
  }
  console.log(`Points awarded`, awardPoints);

  // Redeem some points from Alice's loyalty balance
  const redeemPoints = await Transactions.create({
    amount: 50, // Representing 50 points
    precision: 1,
    reference: `redemption-001`,
    description: `Points redemption`,
    currency: `POINTS`,
    source: pointBalance.data.balance_id,
    destination: `@Store`,
    inflight: true,
    meta_data: {
      customer_name: `Alice`,
      purchase_id: `purchase-001`,
    },
  });

  // Check if points redemption transaction was successful
  if (redeemPoints.data === null) {
    throw new Error(redeemPoints.message);
  }
}

main();

To view a detailed explanation of this implementation, see the following: Expense management

index.js
const { BlnkInit } = require(`@blnkfinance/blnk-typescript`);
const { BASE_URL, sleep, GenerateRandomNumbersWithPrefix } = require(`../util`);

async function main() {
  // Initialize Blnk SDK with base configuration
  const blnk = await BlnkInit(``, {
    baseUrl: BASE_URL,
  });
  const { Ledgers, Search, LedgerBalances, Transactions } = blnk;

  // Create a ledger for the Marketing department
  const marketLedger = await Ledgers.create({
    name: `Marketing Department Ledger`,
    meta_data: {
      department: `Marketing`,
    },
  });

  // Error handling for Marketing ledger creation
  if (marketLedger.data === null) {
    throw new Error(marketLedger.message);
  }

  // Create a ledger for the Human Resources department
  const hrLedger = await Ledgers.create({
    name: `Human Resources Department Ledger`,
    meta_data: {
      department: `Human Resources`,
    },
  });

  // Error handling for HR ledger creation
  if (hrLedger.data === null) {
    throw new Error(hrLedger.message);
  }

  // Retrieve the list of ledgers using the search function
  const ledgers = await Search.search(
    {
      q: `*`,
      sort_by: `created_at:desc`,
    },
    `ledgers`
  );
  console.log(ledgers);

  // Create a balance for the Marketing department's advertising expenses
  const marketingBalance = await LedgerBalances.create({
    ledger_id: marketLedger.data.ledger_id,
    currency: `USD`,
    meta_data: {
      department: `Marketing`,
      expense_type: `Advertising`,
    },
  });

  // Error handling for Marketing balance creation
  if (marketingBalance.data === null) {
    throw new Error(marketingBalance.message);
  }

  // Create a balance for the HR department's recruitment expenses
  const hrBalance = await LedgerBalances.create({
    ledger_id: hrLedger.data.ledger_id,
    currency: `USD`,
    meta_data: {
      department: `Human Resources`,
      expense_type: `Recruitment`,
    },
  });

  // Error handling for HR balance creation
  if (hrBalance.data === null) {
    throw new Error(hrBalance.message);
  }

  // Credit a transaction for marketing-related expenses
  const marketingTransaction = await Transactions.create({
    destination: marketingBalance.data.balance_id,
    source: `@CompanyFunds`,
    amount: 500,
    currency: `USD`,
    precision: 100,
    reference: GenerateRandomNumbersWithPrefix(`ad`, 4),
    description: `Payment for social media ads`,
    inflight: true,
    allow_overdraft: true,
    meta_data: {
      department: `Marketing`,
      expense_type: `Advertising`,
      vendor: `SocialMediaCo`,
    },
  });

  // Error handling for Marketing transaction
  if (marketingTransaction.data === null) {
    throw new Error(marketingTransaction.message);
  }

  // Credit a transaction for HR-related recruitment expenses
  const hrTransaction = await Transactions.create({
    destination: `@CompanyFunds`,
    source: hrBalance.data.balance_id,
    amount: 1000,
    currency: `USD`,
    allow_overdraft: true,
    precision: 100,
    reference: GenerateRandomNumbersWithPrefix(`recruitment-expense`, 4),
    description: `Payment for recruitment agency`,
    inflight: true,
    meta_data: {
      department: `Human Resources`,
      expense_type: `Recruitment`,
      vendor: `JobBoardCo`,
    },
  });

  // Error handling for HR transaction
  if (hrTransaction.data === null) {
    throw new Error(hrTransaction.message);
  }

  await sleep(4);  // Simulate a delay before committing transactions

  // Approving the marketing transaction
  console.log(`Approving marketing transaction`);
  const commitMarketingTransaction = await Transactions.updateStatus(
    marketingTransaction.data.transaction_id,
    {
      status: `commit`,
    }
  );

  // Error handling for committing the marketing transaction
  if (
    commitMarketingTransaction.data === null ||
    commitMarketingTransaction.status !== 200
  ) {
    throw new Error(commitMarketingTransaction.message);
  }

  // Approving the HR recruitment transaction
  console.log(`Approving HR transaction`);
  const recruitmentExpenseCommit = await Transactions.updateStatus(
    hrTransaction.data.transaction_id,
    {
      status: `commit`,
    }
  );

  // Error handling for committing the HR transaction
  if (
    recruitmentExpenseCommit.data === null ||
    recruitmentExpenseCommit.status !== 200
  ) {
    throw new Error(recruitmentExpenseCommit.message);
  }
}

main();

To view a detailed explanation of this implementation, see the following: Savings application

index.js
const { BlnkInit } = require(`@blnkfinance/blnk-typescript`);
const { GenerateRandomNumbersWithPrefix, BASE_URL } = require(`../util`);

async function main() {
  // Initialize the Blnk SDK with base configuration
  const blnk = BlnkInit(``, {
    baseUrl: BASE_URL,
    logger: console,
  });

  const { Ledgers, LedgerBalances, Transactions } = blnk;

  // Create a ledger specifically for managing savings accounts
  const savingsLedger = await Ledgers.create({
    name: `Savings Ledger`,
    meta_data: {
      description: `Ledger for managing savings accounts`,
    },
  });

  // Check if the savings ledger was successfully created
  if (savingsLedger.data === null || savingsLedger.status !== 201) {
    throw new Error(savingsLedger.message);
  }

  // Create a balance for Alice's savings account within the savings ledger
  const aliceSavings = await LedgerBalances.create({
    ledger_id: savingsLedger.data.ledger_id,
    currency: `USD`,
    meta_data: {
      account_type: `Escrow`,
      customer_name: `Alice Johnson`,
      customer_id: `alice-5678`,
      account_opened_date: `2024-01-01`,
      account_status: `active`,
    },
  });

  // Check if the balance creation for Alice's savings was successful
  if (aliceSavings.data === null || aliceSavings.status !== 201) {
    throw new Error(aliceSavings.message);
  }

  // Fund Alice's savings balance with an initial deposit transaction
  const aliceDeposit = await Transactions.create({
    amount: 1000,  // Amount to be deposited
    precision: 100,
    reference: GenerateRandomNumbersWithPrefix(`funding`, 4),
    description: `Funding savings account`,
    currency: `USD`,
    source: `@bank-account`,
    destination: aliceSavings.data.balance_id,  // Alice's savings account balance_id
    inflight: true,
    allow_overdraft: true, // Enable overdraft for the initial deposit
    meta_data: {
      transaction_type: `deposit`,
      customer_name: `Alice Johnson`,
      customer_id: `alice-5678`,
      transaction_date: `2024-07-05`,
      payment_verified: false,
    },
  });

  // Check if the deposit transaction was successful
  if (aliceDeposit.data === null || aliceDeposit.status !== 201) {
    throw new Error(aliceDeposit.message);
  }
}

// Execute main function and catch any errors
main().catch(error => {
  console.error(error);
});

To view a detailed explanation of this implementation, see the following: Virtual cards

index.js
const { BlnkInit } = require(`@blnkfinance/blnk-typescript`);
const { GenerateRandomNumbersWithPrefix, sleep, BASE_URL } = require(`../util`);

async function main() {
  // Initialize the Blnk SDK with base configuration
  const blnk = BlnkInit(``, {
    baseUrl: BASE_URL,
  });

  const { Ledgers, LedgerBalances, Transactions } = blnk;

  // Create a USD ledger for managing virtual card transactions
  const usdLedger = await Ledgers.create({
    name: `Customer USD Ledger`,
    meta_data: {
      project_name: `VirtualCard App`,
    },
  });

  // Check if the USD ledger creation was successful
  if (usdLedger.data === null) {
    throw new Error(usdLedger.message);
  }

  // Create a USD virtual card balance with masked card details for security
  const usdBalance = await LedgerBalances.create({
    ledger_id: usdLedger.data.ledger_id,
    currency: `USD`,
    meta_data: {
      customer_name: `Jerry`,
      customer_internal_id: `1234`,
      card_state: `ACTIVE`,
      card_number: `411111XXXXXX1111`, // Masked for security
      card_expiry: `12/26`,
      card_cvv: `XXX`, // Masked for security
    },
  });

  // Check if the virtual card balance creation was successful
  if (usdBalance.data === null || usdBalance.status !== 201) {
    throw new Error(usdBalance.message);
  }

  // Record the first transaction on this balance, allowing overdraft for setup
  const firstTransaction = await Transactions.create({
    amount: 1000,
    precision: 100,
    reference: GenerateRandomNumbersWithPrefix(`trx`, 4),
    description: `First transaction on this balance`,
    currency: `USD`,
    source: `@World`,
    destination: `@Merchant`,
    allow_overdraft: true,
    meta_data: {
      merchant_name: `Store ABC`,
      customer_name: `Jerry`,
    },
  });

  // Check if the first transaction creation was successful
  if (firstTransaction.data === null || firstTransaction.status !== 201) {
    throw new Error(firstTransaction.message);
  }

  // Record an authorization transaction as inflight (pending approval)
  const reference = GenerateRandomNumbersWithPrefix(`trx`, 4);
  const inflightTransaction = await Transactions.create({
    amount: 1000,
    precision: 100,
    reference,
    description: `Authorization for purchase`,
    currency: `USD`,
    source: `@Merchant`,
    destination: usdBalance.data.balance_id, // Jerry's virtual card balance_id
    inflight: true,
    meta_data: {
      merchant_name: `Store ABC`,
      customer_name: `Jerry`,
    },
  });

  // Check if the inflight transaction creation was successful
  if (inflightTransaction.data === null || inflightTransaction.status !== 201) {
    throw new Error(inflightTransaction.message);
  }

  // Wait 4 seconds to simulate the time for transaction processing
  await sleep(4);

  // Commit the inflight transaction once verified
  const x = await Transactions.updateStatus(
    inflightTransaction.data.transaction_id,
    {
      status: `commit`,
    }
  );

  // Check if the transaction commit was successful
  if (x.data === null || x.status !== 200) {
    throw new Error(x.message);
  }

  // Optionally void the transaction if it fails or is canceled
  await Transactions.updateStatus(inflightTransaction.data.transaction_id, {
    status: `void`,
  });
}

// Execute the main function
main();

To view a detailed explanation of this implementation, see the following: Reconciliation workflows

index.js
const { BlnkInit } = require(`@blnkfinance/blnk-typescript`);
const { BASE_URL } = require(`../util`);
const path = require(`path`);

async function main() {
  // Initialize the Blnk SDK with the base URL configuration
  const blnk = BlnkInit(``, {
    baseUrl: BASE_URL,
  });
  const { Reconciliation } = blnk;

  // Define the path for the reconciliation file
  const filePath = path.join(__dirname, `..`, `..`, `file.csv`);

  // Upload the reconciliation file for the Stripe account
  const reconciliationUpload = await Reconciliation.upload(filePath, `Stripe`);

  // Check if the upload was successful
  if (reconciliationUpload.status !== 200) {
    throw new Error(reconciliationUpload.message);
  }

  // Create a matching rule to reconcile based on the 'amount' field
  const matchingRule = await Reconciliation.createMatchingRule({
    criteria: [
      {
        field: `amount`,
        operator: `equals`,
        allowable_drift: 0.01, // Allowable difference in amount for a match
      },
    ],
    name: `Test Matching Rule`,
    description: `Test Matching Rule Description`,
  });

  // Check if the matching rule creation was successful
  if (matchingRule.status !== 201) {
    throw new Error(matchingRule.message);
  }

  // Start the reconciliation process with specified criteria
  const startReconciliation = await Reconciliation.run({
    dry_run: true, // Run in test mode without making actual changes
    grouping_criteria: `amount`,
    matching_rule_ids: [matchingRule.data.rule_id], // Use the created matching rule
    strategy: `many_to_one`, // Reconciliation strategy
    upload_id: reconciliationUpload.data.upload_id, // Use the uploaded file
  });

  // Check if the reconciliation process started successfully
  if (startReconciliation.status !== 200) {
    throw new Error(startReconciliation.message);
  }
}

// Execute the main function
main();

Need help?

We are very happy to help you make the most of Blnk, regardless of whether it is your first time or you are switching from another tool.

To ask questions or discuss issues, please contact us or join our Discord community.

Get access to Blnk Cloud.

Manage your Blnk Ledger and explore advanced features (access control & collaboration, anomaly detection, secure storage & file management, etc.) in one dashboard.

Issue reporting

If you encounter any issues while installing or using this SDK, please report them on Github.

​Introduction

​Need help?

​Issue reporting

Introduction

Need help?

Issue reporting