Skip to main content
In this tutorial, you’ll learn how to implement, monitor, and manage scheduled savings deposits with the Blnk ledger. Here’s what we’ll do:
  1. Create a customer savings wallet balance.
  2. Initiate a scheduled deposit transaction. For one-time funding: Wallet Funding Tutorial →.
  3. Update the savings frequency.
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 scheduled savings deposit workflow, here’s our map: Savings application map Explore the map yourself here Read more: Scheduling transactions →

​
Set up your implementation

Based on our map, we’ll implement the following steps:
  1. Initiate a scheduled transaction to Savings Wallet
  2. Monitor the date of the next scheduled deposit to ensure timely execution.
  3. Set up a new scheduled transaction after the current one has been successfully processed.

​
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. A customer savings ledger to organise the customers’ savings balances. Learn how: How to Create a 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;
}

​
Create customer savings balance

Create a balance with the ledger_id of your Customer Savings Ledger to represent your customer savings wallet: 
curl --request POST \
  --url http://localhost:5001/balances \
  --header 'X-blnk-key: <api-key>' \
  --header 'Content-Type: application/json' \
  --data '{
    "ledger_id": "<customer-savings-ledger-id>",
    "identity_id": "<customer-identity-id>",
    "currency": "USD",
    "meta_data": {
        "wallet_type": "savings",
        "schedule_savings": true,
        "savings_frequency": "monthly",
        "savings_amount": 10000,
        "next_scheduled_savings": ""
    }
  }'
This creates a savings balance with a set of default metadata:
  1. This customer balance is subscribed to scheduled deposits.
  2. Schedule frequency is monthly.
  3. The next scheduled savings date can be monitored on the customer balance

​
Initiate scheduled transaction

Schedule a transaction on the ledger with the scheduled_for parameter: 
curl --request POST \
  --url http://localhost:5001/transactions \
  --header 'X-blnk-key: <api-key>' \
  --header 'Content-Type: application/json' \
  --data '{
    "amount": 1000,
    "precision": 100,
    "reference": "SAV_0001",
    "description": "Scheduled savings deposit",
    "currency": "USD",
    "source": "@WorldUSD",
    "destination": "<savings-balance-id>",
    "scheduled_for": "2025-12-25T02:42:19Z",
    "meta_data": {
      "transaction_type": "savings"
    }
  }'
A SCHEDULED transaction is created waiting to be applied on the specified scheduled date.

​
Set up new scheduled transaction

To schedule the next savings deposit, verify that scheduled_savings is still active on the customer’s balance and retrieve its frequency.
Blnk sends a webhook when a scheduled transaction gets applied.
Update balance metadata and create the next scheduled savings transaction: 
# After a scheduled savings transaction is applied, update balance metadata:
curl --request POST \
  --url http://localhost:5001/balances/<savings-balance-id>/metadata \
  --header 'X-blnk-key: <api-key>' \
  --header 'Content-Type: application/json' \
  --data '{
    "meta_data": {
      "next_scheduled_savings": "2026-01-25T02:42:19Z"
    }
  }'

# Then create the next scheduled transaction:
curl --request POST \
  --url http://localhost:5001/transactions \
  --header 'X-blnk-key: <api-key>' \
  --header 'Content-Type: application/json' \
  --data '{
    "amount": 10000,
    "precision": 100,
    "reference": "sch-savings-1709741652384",
    "description": "Scheduled savings deposit",
    "currency": "USD",
    "source": "@WorldUSD",
    "destination": "<savings-balance-id>",
    "scheduled_for": "2026-01-25T02:42:19Z",
    "meta_data": {
      "transaction_type": "savings"
    }
  }'

​
Change savings frequency

To change the savings frequency of a balance, use the Update Metadata endpoint: Update the savings frequency on the customer balance: 
curl --request POST \
  --url http://localhost:5001/balances/<balance-id>/metadata \
  --header 'X-blnk-key: <api-key>' \
  --header 'Content-Type: application/json' \
  --data '{
  "meta_data": {
    "savings_frequency": "daily"
  }
}'

​
Conclusion

In this tutorial, we’ve built a scheduled savings workflow for a wallet app using Blnk. Here’s what we covered:
  • Setting up savings ledgers and customer savings accounts
  • Adding scheduled deposits
  • Automatically rescheduling deposits after they’re completed
  • Handling deposit frequencies and customer preferences
  • Using webhooks to detect completed transactions and schedule new deposits.
With these features, your app offers customers an easy, automated way to save regularly without extra effort. The webhook-based architecture ensures that your system remains resilient and responsive to transaction events.