Create Wallet and Sub Wallets

API To create user Wallets and Sub Wallets.

Overview

Wallets, referred to as Accounts in the API, are financial accounts associated with users and are uniquely identified by an accountNumber. For personal wallets, the tukuTillNumber will be a phone number, while organization wallets will use a numeric identifier for the tukuTillNumber. Each sub-wallet requires its own unique phone number (for personal accounts) or an incremented numeric identifier (for organization accounts). The accountNumber is formed by concatenating fields into the following structure:

• Personal Wallets: <APP_PREFIX><TUKU_TILL_NUMBER WHICH IS PHONE NUMBER>

• Organization Wallets: <APP_PREFIX><TUKU_TILL_NUMBER><WALLET_NUMBER>

The APP_PREFIX (e.g., AAA) is assigned to the app during approval by the bank.

---

Wallet Structure

Each wallet contains the following fields:

Field	Type	Description
accountNumber	string	Full concatenated wallet identifier (e.g., AAA0705035022, AAA000011).
appPrefix	string	Unique 3-letter code assigned to the app (e.g., AAA).
tukuTillNumber	string	A phone number for personal wallets, or a numeric identifier for organizations.
walletNumber	number	Incremented numeric identifier for sub-wallets (used for organizations only).
name	string	Name of the wallet (e.g., "Personal Savings" or "Operations Wallet").
description	string	Description of the wallet’s purpose.
currentBalance	number	Current balance, updated automatically by transactions.
status	string	Wallet status (active, inactive, etc.).
verified	boolean	Indicates whether the wallet is KYC-verified.
userId	string	The user ID to whom this wallet belongs.

---

Endpoints for Wallets

1. Create a Wallet

• Method: POST

• URL: /api/wallets/create

Request Body (Personal Wallet):

{
  "appId": "app123",
  "userId": "user456",
  "name": "Savings Wallet",
  "description": "Personal savings wallet",
  "tukuTillNumber": "[phone]",
  "verified": true
}

Request Body (Organization Wallet):

{
  "appId": "app123",
  "userId": "user789",
  "name": "Operations Wallet",
  "description": "Main wallet for organizational operations",
  "tukuTillNumber": "00001",
  "walletNumber": 2,
  "verified": true
}

Response:

{
  "status": "success",
  "message": "Wallet created successfully.",
  "wallet": {
    "accountNumber": "AAA0000112",
    "appPrefix": "AAA",
    "tukuTillNumber": "00001",
    "walletNumber": 2,
    "name": "Operations Wallet",
    "description": "Main wallet for organizational operations",
    "currentBalance": 0,
    "status": "active",
    "verified": true,
    "userId": "user789"
  }
}

---

2. Retrieve Wallets

• Method: GET

• URL: /api/wallets/get

Request Body:

{
  "appId": "app123",
  "userId": "user456"
}

Response:

{
  "status": "success",
  "wallets": [
    {
      "accountNumber": "AAA0705035022",
      "name": "Savings Wallet",
      "currentBalance": 15000,
      "status": "active"
    },
    {
      "accountNumber": "AAA0000111",
      "name": "Operations Wallet",
      "currentBalance": 5000,
      "status": "active"
    }
  ]
}

---

3. Update Wallet Details

• Method: PUT

• URL: /api/wallets/update

Request Body:

{
  "appId": "app123",
  "accountNumber": "AAA0705035022",
  "name": "Emergency Savings",
  "description": "Updated wallet description"
}

---

4. Delete a Wallet

• Method: DELETE

• URL: /api/wallets/delete

Request Body:

{
  "appId": "app123",
  "accountNumber": "AAA0000112"
}

---

Key Points

1. Personal Wallets: Require a unique phone number as the tukuTillNumber.

2. Organization Wallets: Use a tukuTillNumber (e.g., 00001) and increment walletNumber for sub-wallets.

3. Account Number: Generated by concatenating appPrefix, tukuTillNumber, and walletNumber.

4. Auto-Updated Balance: The currentBalance reflects wallet transactions.

5. KYC Verification: Ensures wallets are compliant with regulatory standards.