Building a Wallet Management System with Blnk • Blnk Developer Documentation

This tutorial will guide you through implementing a simple wallet management system using the Blnk Ledger. By the end, you’ll have built a system that can:

Create customer wallets.
Link wallets to customer identities.
Support deposits and withdrawals from wallets.
Create purpose-specific wallets (e.g. card balances).
Enable transfers between wallets.

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 wallet management system, here’s how funds will flow:

Explore the map yourself here This map shows three key components:

@World: Represents external funding sources and withdrawal destinations.
Main Wallet: The customer’s primary wallet for deposits and withdrawals.
Card Wallet: A second wallet for card-related transactions.

From our map, we can verify that:

Customers can deposit money from external sources to their main wallet.
Customers can withdraw money from their main wallet to external destinations.
Customers can transfer money from their main wallet to their card wallet.

Set up your implementation

Based on our map, we’ll implement the following steps:

Create a customer ledger to organise all customer wallets.
Create customer identity for storing user information.
Create a main wallet and link it to the identity.
Implement deposit functionality.
Implement withdrawal functionality.
Create a card wallet and link it to the same identity.
Fund the card wallet from the main wallet.

Prerequisites

Before starting, ensure you have:

A running Blnk Core instance (e.g. at http://localhost:5001).
An API key for Blnk (replace YOUR_API_KEY in the code examples). Required for authenticated requests.
Optionally, you can connect your Blnk Core to your Blnk Cloud workspace to view your ledger data.

Create customer ledger

You can also create separate ledgers for different wallet types, e.g., Customer Main Ledger and Customer Card Ledger, to keep your balances more organized.

Create a ledger to organize all customer wallets - main and card wallets:

curl -X POST "http://localhost:5001/ledgers" \
  -H "X-blnk-key: <api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Customer Wallets Ledger",
    "meta_data": {
        "description": "Ledger for managing customer wallets",
        "application": "Wallet Management System"
    }
  }'

async function createCustomerLedger() {
  
  
  const customerLedger = await blnk.Ledgers.create({
    name: "Customer Wallets Ledger",
    meta_data: {
      description: "Ledger for managing customer wallets",
      application: "Wallet Management System"
    }
  });
  
  console.log("Customer Ledger created:", customerLedger.data.ledger_id);
  return customerLedger.data.ledger_id;
}

func createCustomerLedger() (string, error) {
    client := getClient()
    ledger, _, err := client.Ledger.Create(blnkgo.CreateLedgerRequest{
        Name: "Customer Wallets Ledger",
        MetaData: blnkgo.MetaData{
            "description": "Ledger for managing customer wallets",
            "application": "Wallet Management System",
        },
    })
    if err != nil {
        return "", err
    }
    fmt.Println("Customer Ledger created:", ledger.LedgerID)
    return ledger.LedgerID, nil
}

customer_ledger = blnk.ledgers.create({
  "name": "Customer Wallets Ledger",
  "meta_data": {
    "description": "Ledger for managing customer wallets",
    "application": "Wallet Management System",
  },
})

print("Customer Ledger created:", customer_ledger.data["ledger_id"])

Always save the ledger_id in your database. You’ll use this ID to create balances for the customer wallets.

Create customer identity

Create a customer identity to store user profile information:

curl -X POST "http://localhost:5001/identities" \
  -H "X-blnk-key: <api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "identity_type": "individual",
    "first_name": "Alice",
    "last_name": "Johnson",
    "email_address": "alice@example.com",
    "phone_number": "+1234567890",
    "meta_data": {
        "customer_id": "CUST-001",
        "registration_date": "2024-02-25T10:30:00Z"
    }
  }'

async function createCustomerIdentity(customerData) {
  
  
  const identity = await blnk.Identity.create({
    identity_type: "individual",
    first_name: customerData.firstName,
    last_name: customerData.lastName,
    email_address: customerData.email,
    phone_number: customerData.phone,
    meta_data: {
      customer_id: customerData.customerId,
      registration_date: new Date().toISOString()
    }
  });
  
  console.log("Customer Identity created:", identity.data.identity_id);
  return identity.data.identity_id;
}

func createCustomerIdentity(customerData CustomerData) (string, error) {
    client := getClient()
    identity, _, err := client.Identity.Create(blnkgo.Identity{
        IdentityType: blnkgo.Individual,
        FirstName:    customerData.FirstName,
        LastName:     customerData.LastName,
        EmailAddress: customerData.Email,
        PhoneNumber:  customerData.Phone,
        MetaData: blnkgo.MetaData{
            "customer_id":       customerData.CustomerID,
            "registration_date": time.Now().UTC().Format(time.RFC3339),
        },
    })
    if err != nil {
        return "", err
    }
    fmt.Println("Customer Identity created:", identity.IdentityID)
    return identity.IdentityID, nil
}

identity = blnk.identity.create({
  "identity_type": "individual",
  "first_name": "Alice",
  "last_name": "Johnson",
  "email_address": "alice@example.com",
  "phone_number": "+1234567890",
  "meta_data": {
    "customer_id": "CUST-001",
    "registration_date": "2024-02-25T10:30:00Z",
  },
})

print("Customer Identity created:", identity.data["identity_id"])

Always save the identity_id in your database. You’ll use this ID to link balances to this identity or query all balances owned by this identity.

Create main wallet

Create a balance to represent the customer main wallet and link to the customer identity:

curl -X POST "http://localhost:5001/balances" \
  -H "X-blnk-key: <api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "ledger_id": "<customer-wallets-ledger-id>",
    "identity_id": "<customer-identity-id>",
    "currency": "USD",
    "meta_data": {
        "wallet_type": "main",
        "purpose": "general",
        "status": "active"
    }
  }'

async function createMainWallet(ledgerId, identityId, currency) {
  
  
  const mainWallet = await blnk.LedgerBalances.create({
    ledger_id: ledgerId,
    identity_id: identityId,
    currency: currency,
    meta_data: {
      wallet_type: "main",
      purpose: "general",
      status: "active"
    }
  });
  
  console.log("Main Wallet created:", mainWallet.data.balance_id);
  return mainWallet.data.balance_id;
}

func createMainWallet(ledgerID, identityID, currency string) (string, error) {
    client := getClient()
    balance, _, err := client.LedgerBalance.Create(blnkgo.CreateLedgerBalanceRequest{
        LedgerID:   ledgerID,
        IdentityID: identityID,
        Currency:   currency,
        MetaData: blnkgo.MetaData{
            "wallet_type": "main",
            "purpose":     "general",
            "status":      "active",
        },
    })
    if err != nil {
        return "", err
    }
    fmt.Println("Main Wallet created:", balance.BalanceID)
    return balance.BalanceID, nil
}

main_wallet = blnk.ledger_balances.create({
  "ledger_id": ledger_id,
  "identity_id": identity_id,
  "currency": currency,
  "meta_data": {
    "wallet_type": "main",
    "purpose": "general",
    "status": "active",
  },
})

print("Main Wallet created:", main_wallet.data["balance_id"])

Always store the balance_id in your database and associate it with the customer. You’ll use this ID for all future transactions involving this wallet.

Funding the main wallet

Use an internal balance to represent external deposit sources-such as bank accounts, cards, and other funding methods-responsible for funding a customer’s wallet. Record a deposit from an external source to fund the main wallet:

curl -X POST "http://localhost:5001/transactions" \
  -H "X-blnk-key: <api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "precise_amount": 100000,
    "precision": 100,
    "reference": "DEP-20250225-103000",
    "description": "Initial deposit",
    "currency": "USD",
    "source": "@WorldUSD",
    "destination": "<customer-main-balance-id>",
    "allow_overdraft": true,
    "meta_data": {
        "transaction_type": "deposit",
        "channel": "bank_transfer"
    }
  }'

async function depositToWallet(customerBalanceID, amount, uniqueReference, description) {
  
  
  const deposit = await blnk.Transactions.create({
    precise_amount: amount * 100,
    precision: 100,
    reference: uniqueReference,
    description: description || "Deposit to wallet",
    currency: "USD",
    source: "@WorldUSD",
    destination: customerBalanceID,
    allow_overdraft: true, // Enable for the external source
    meta_data: {
      transaction_type: "deposit",
      channel: "bank_transfer"
    }
  });
  
  console.log("Deposit transaction created:", deposit.data.transaction_id);
  return deposit.data.transaction_id;
}

func depositToWallet(customerBalanceID string, amount float64, uniqueReference, description string) (string, error) {
    client := getClient()
    if description == "" {
        description = "Deposit to wallet"
    }
    deposit, _, err := client.Transaction.Create(blnkgo.CreateTransactionRequest{
        ParentTransaction: blnkgo.ParentTransaction{
            PreciseAmount: amount * 100,
            Precision:   100,
            Reference:   uniqueReference,
            Description: description,
            Currency:    "USD",
            Source:      "@WorldUSD",
            Destination: customerBalanceID,
            MetaData: blnkgo.MetaData{
                "transaction_type": "deposit",
                "channel":          "bank_transfer",
            },
        },
        AllowOverdraft: true,
    })
    if err != nil {
        return "", err
    }
    fmt.Println("Deposit transaction created:", deposit.TransactionID)
    return deposit.TransactionID, nil
}

deposit = blnk.transactions.create({
  "precise_amount": 100000,
  "precision": 100,
  "reference": "DEP-20250225-103000",
  "description": "Initial deposit",
  "currency": "USD",
  "source": "@WorldUSD",
  "destination": customer_balance_id,
  "allow_overdraft": True,
  "meta_data": {
    "transaction_type": "deposit",
    "channel": "bank_transfer",
  },
})

print("Deposit transaction created:", deposit.data["transaction_id"])

Setting allow_overdraft to true enables the transaction to proceed even if the source balance lacks sufficient funds.

Withdrawals from the main wallet

You can use the same internal balance to represent external withdrawal destinations to balance out your ledger, or you can allocate a separate internal balance specifically for withdrawals. Record a withdrawal from the main wallet to an external destination:

curl -X POST "http://localhost:5001/transactions" \
  -H "X-blnk-key: <api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "precise_amount": 10000,
    "precision": 100,
    "reference": "WDR-20250225-104500",
    "description": "Wallet withdrawal",
    "currency": "USD",
    "source": "<customer-main-balance-id>",
    "destination": "@WorldUSD",
    "meta_data": {
        "transaction_type": "withdrawal",
        "channel": "atm"
    }
  }'

async function withdrawFromWallet(customerBalanceID, amount, uniqueReference, description) {
  
  
  const withdrawal = await blnk.Transactions.create({
    precise_amount: amount * 100,
    precision: 100,
    reference: uniqueReference,
    description: description || "Withdrawal from wallet",
    currency: "USD",
    source: customerBalanceID,
    destination: "@WorldUSD",
    meta_data: {
      transaction_type: "withdrawal",
      channel: "bank_transfer"
    }
  });
  
  console.log("Withdrawal transaction created:", withdrawal.data.transaction_id);
  return withdrawal.data.transaction_id;
}

func withdrawFromWallet(customerBalanceID string, amount float64, uniqueReference, description string) (string, error) {
    client := getClient()
    if description == "" {
        description = "Withdrawal from wallet"
    }
    withdrawal, _, err := client.Transaction.Create(blnkgo.CreateTransactionRequest{
        ParentTransaction: blnkgo.ParentTransaction{
            PreciseAmount: amount * 100,
            Precision:   100,
            Reference:   uniqueReference,
            Description: description,
            Currency:    "USD",
            Source:      customerBalanceID,
            Destination: "@WorldUSD",
            MetaData: blnkgo.MetaData{
                "transaction_type": "withdrawal",
                "channel":          "bank_transfer",
            },
        },
    })
    if err != nil {
        return "", err
    }
    fmt.Println("Withdrawal transaction created:", withdrawal.TransactionID)
    return withdrawal.TransactionID, nil
}

withdrawal = blnk.transactions.create({
  "precise_amount": 10000,
  "precision": 100,
  "reference": "WDR-20250225-104500",
  "description": "Wallet withdrawal",
  "currency": "USD",
  "source": customer_balance_id,
  "destination": "@WorldUSD",
  "meta_data": {
    "transaction_type": "withdrawal",
    "channel": "bank_transfer",
  },
})

print("Withdrawal transaction created:", withdrawal.data["transaction_id"])

Creating a card balance

To create a card balance and link it to the customer:

curl -X POST "http://localhost:5001/balances" \
  -H "X-blnk-key: <api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "ledger_id": "<customer-wallets-ledger-id>",
    "identity_id": "<customer-identity-id>",
    "currency": "USD",
    "meta_data": {
        "wallet_type": "card",
        "purpose": "card_payments",
        "status": "active",
        "card_details": {
            "masked_number": "xxxx-xxxx-xxxx-1234",
            "expiry": "12/25",
            "type": "virtual"
        }
    }
  }'

async function createCardWallet(ledgerId, identityId, currency) {
  
  
  const cardWallet = await blnk.LedgerBalances.create({
    ledger_id: ledgerId,
    identity_id: identityId,
    currency: currency,
    meta_data: {
      wallet_type: "card",
      purpose: "card_payments",
      status: "active",
      card_details: {
        masked_number: "xxxx-xxxx-xxxx-1234",
        expiry: "12/25",
        type: "virtual"
      }
    }
  });
  
  console.log("Card Wallet created:", cardWallet.data.balance_id);
  return cardWallet.data.balance_id;
}

func createCardWallet(ledgerID, identityID, currency string) (string, error) {
    client := getClient()
    balance, _, err := client.LedgerBalance.Create(blnkgo.CreateLedgerBalanceRequest{
        LedgerID:   ledgerID,
        IdentityID: identityID,
        Currency:   currency,
        MetaData: blnkgo.MetaData{
            "wallet_type": "card",
            "purpose":     "card_payments",
            "status":      "active",
            "card_details": map[string]interface{}{
                "masked_number": "xxxx-xxxx-xxxx-1234",
                "expiry":        "12/25",
                "type":          "virtual",
            },
        },
    })
    if err != nil {
        return "", err
    }
    fmt.Println("Card Wallet created:", balance.BalanceID)
    return balance.BalanceID, nil
}

card_wallet = blnk.ledger_balances.create({
  "ledger_id": ledger_id,
  "identity_id": identity_id,
  "currency": currency,
  "meta_data": {
    "wallet_type": "card",
    "purpose": "card_payments",
    "status": "active",
    "card_details": {
      "masked_number": "xxxx-xxxx-xxxx-1234",
      "expiry": "12/25",
      "type": "virtual",
    },
  },
})

print("Card Wallet created:", card_wallet.data["balance_id"])

Funding the card from main wallet

Record a transaction between both balances to fund your card balance:

curl -X POST "http://localhost:5001/transactions" \
  -H "X-blnk-key: <api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "precise_amount": 20000,
    "precision": 100,
    "reference": "TRF-20250225-110000",
    "description": "Transfer to card wallet",
    "currency": "USD",
    "source": "<customer-main-balance-id>",
    "destination": "<customer-card-balance-id>",
    "meta_data": {
        "transaction_type": "internal_transfer",
        "purpose": "fund_card"
    }
  }'

async function transferToCardWallet(mainBalanceID, cardBalanceID, amount, uniqueReference, description) {
  
  
  const transfer = await blnk.Transactions.create({
    precise_amount: amount * 100,
    precision: 100,
    reference: uniqueReference,
    description: description || "Transfer to card wallet",
    currency: "USD",
    source: mainBalanceID,
    destination: cardBalanceID,
    meta_data: {
      transaction_type: "internal_transfer",
      purpose: "fund_card"
    }
  });
  
  console.log("Transfer transaction created:", transfer.data.transaction_id);
  return transfer.data.transaction_id;
}

func transferToCardWallet(mainBalanceID, cardBalanceID string, amount float64, uniqueReference, description string) (string, error) {
    client := getClient()
    if description == "" {
        description = "Transfer to card wallet"
    }
    transfer, _, err := client.Transaction.Create(blnkgo.CreateTransactionRequest{
        ParentTransaction: blnkgo.ParentTransaction{
            PreciseAmount: amount * 100,
            Precision:   100,
            Reference:   uniqueReference,
            Description: description,
            Currency:    "USD",
            Source:      mainBalanceID,
            Destination: cardBalanceID,
            MetaData: blnkgo.MetaData{
                "transaction_type": "internal_transfer",
                "purpose":          "fund_card",
            },
        },
    })
    if err != nil {
        return "", err
    }
    fmt.Println("Transfer transaction created:", transfer.TransactionID)
    return transfer.TransactionID, nil
}

transfer = blnk.transactions.create({
  "precise_amount": 20000,
  "precision": 100,
  "reference": "TRF-20250225-110000",
  "description": "Transfer to card wallet",
  "currency": "USD",
  "source": main_balance_id,
  "destination": card_balance_id,
  "meta_data": {
    "transaction_type": "internal_transfer",
    "purpose": "fund_card",
  },
})

print("Transfer transaction created:", transfer.data["transaction_id"])

Conclusion

You should now have a fully functional and scalable wallet management system. As your application grows, you can expand its capabilities with features like transaction history, scheduled transfers, balance monitors, and webhooks to enhance performance and user experience.

Start Here

Ledgers

Ledger balances

Transactions

Reconciliation

Identities

Metadata

Search

Webhooks

API keys

Guides

Configuration

Advanced

Migration guides

Building a Wallet Management System

Designing your map

Set up your implementation

Prerequisites

Create customer ledger

Create customer identity

Create main wallet

Funding the main wallet

Withdrawals from the main wallet

Creating a card balance

Funding the card from main wallet

Conclusion

​Designing your map

​Set up your implementation

​Prerequisites

​Create customer ledger

​Create customer identity

​Create main wallet

​Funding the main wallet

​Withdrawals from the main wallet

​Creating a card balance

​Funding the card from main wallet

​Conclusion

Designing your map

Set up your implementation

Prerequisites

Create customer ledger

Create customer identity

Create main wallet

Funding the main wallet

Withdrawals from the main wallet

Creating a card balance

Funding the card from main wallet

Conclusion