Vault Workflow

📋 Overview

Complete workflow for managing user vault accounts and vault transactions. The vault system allows users to create category-specific savings accounts (e.g., Health, Bills, Education), transfer money to/from vault, lock funds for specific periods, and manage vault maturity dates. This workflow covers all vault-related operations including admin configuration, category selection, account creation, balance display, money transfers, and fund locking.

Key Features:

• Category-Based Vaults: Create separate vault accounts for different savings categories
• Admin Configuration: Administrators can create and manage sub wallet categories
• Category Selection: Users can choose from available categories when creating vaults
• Fund Management: Transfer money to/from category-specific vaults
• Lock Management: Lock funds in category-specific vaults with maturity dates

⚙️ Admin Configuration (Prerequisites)

Before users can create vault accounts, administrators must configure sub wallet categories and create corresponding admin wallets for each category.

Step 1: Create Sub Wallet Category (Admin Panel)

Purpose: Create a new sub wallet category from the admin panel settings.

Process:

1. Navigate to admin panel settings
2. Create a new sub wallet category (e.g., "Health", "Bills", "Education")
3. Configure category details including name, description, and image
4. Save the category and note the sub_wallet_category_id

Note: Multiple sub wallet categories can be created as per business requirements.

Step 2: Create Admin Wallet for Category

Purpose: Create an admin wallet for the sub wallet category using the Save Wallet API.

Process:

1. Call the Save Wallet API (Admin endpoint) with the following payload structure:

Create Admin Wallet Request Example

{
    "wallet_name": "Health - Saving Wallet",
    "is_default": false,
    "currency_id": "b57f40b4162e43f1a9512189b8325b42",
    "wallet_type": 3,
    "pool_amount": 0.0,
    "sub_wallet_category_id": "6c4120a34efa417c8674c7074ce23338",
    "user_id": "b0e624e0cd174a53b6e9160afce2d6a5",
    "status": 1
}

Required Parameters:

• wallet_type: 3 (Saving Wallet - fixed)
• is_default: false (fixed)
• status: 1 (fixed)
• user_id: Admin user ID
• wallet_name: Category-specific wallet name (e.g., "Health - Saving Wallet")
• sub_wallet_category_id: Sub wallet category ID for which the admin wallet is being created
• currency_id: Currency identifier
• pool_amount: Initial pool amount (typically 0.0)

Result: Admin wallet is created for the sub wallet category, ready for user vault account creation.

🔄 Workflow Steps

Step 1: Display Available Vault Categories

• Purpose: Show available sub wallet categories to the user for vault creation
• Prerequisites: User must be authenticated and have a valid user ID
• Process:
  1. Call the Get All Sub Wallet Categories API with category_type = 2 and is_active = true
  2. Extract the list of available categories from the response
  3. Display categories to the user (e.g., "Health", "Bills", "Education")
• Result: User can see and select from available vault categories

Get All Sub Wallet Categories API

• Endpoint: GET /gafapay/v3/base/sub_wallet_category
• Query Parameters:
  • category_type: 2 (fixed for vault categories)
  • is_active: true (to show only active categories)

Get All Sub Wallet Categories Request Example

curl --location 'https://api.gafapay.com/gafapay/v3/base/sub_wallet_category?is_active=true&category_type=2' \
--header 'Authorization: Token YOUR_TOKEN' \
--header 'CompanyId: YOUR_COMPANY_ID' \
--header 'RequestID: YOUR_REQUEST_ID'

Get All Sub Wallet Categories Response Example

{
    "success": 1,
    "error": [],
    "data": {
        "sub_wallet_category": [
            {
                "created_date": 1767976686,
                "updated_date": 1767976686,
                "is_active": true,
                "created_by": "69141672b5c4ee0bca209fb2",
                "updated_by": "69141672b5c4ee0bca209fb2",
                "id": "7c1d979357a54a62affd3345fd635127",
                "category_type": 2,
                "name": "Bills",
                "description": "Bills",
                "image": null,
                "status": 1
            },
            {
                "created_date": 1767371364,
                "updated_date": 1767371364,
                "is_active": true,
                "created_by": "69141672b5c4ee0bca209fb2",
                "updated_by": "69141672b5c4ee0bca209fb2",
                "id": "6c4120a34efa417c8674c7074ce23338",
                "category_type": 2,
                "name": "Health",
                "description": "Health",
                "image": null,
                "status": 1
            }
        ]
    }
}

Step 2: Create Vault Account for Selected Category (Save User Wallet)

• Purpose: Create a new vault account for the user for a specific category by associating them with the category's saving wallet
• Prerequisites:
  • User must be authenticated and have a valid user ID
  • User has selected a sub wallet category from Step 1
• Process:
  1. Get Category Wallet: Call the Get All Wallets API with:
     • currency_id: Currency identifier
     • sub_wallet_category_id: Selected category ID from Step 1
  2. Extract Wallet ID: Extract the wallet_id from the response (saving wallet type for the selected category)
  3. Create User Vault Account: Call the Save User Wallet API to create the vault account
  4. Pass Parameters: Pass the category's vault wallet_id, user_id, currency_id, and set is_default = false
• Result: User now has a category-specific vault account associated with their profile

Get Category Wallet Request Example

curl --location 'https://api.gafapay.com/gafapay/v3/transaction/wallet?currency_id=b57f40b4162e43f1a9512189b8325b42&sub_wallet_category_id=7c1d979357a54a62affd3345fd635127' \
--header 'Authorization: Token YOUR_TOKEN' \
--header 'CompanyId: YOUR_COMPANY_ID' \
--header 'RequestID: YOUR_REQUEST_ID'

Step 3: Display Vault Balance

• Purpose: Show the current balance in the user's category-specific vault account
• Prerequisites: User has created a vault account for a specific category
• Process:
  1. Get Category Wallet: Call the Get All Wallets API with:
     • currency_id: Currency identifier
     • sub_wallet_category_id: Category ID for which to display balance
  2. Extract Wallet ID: Extract the wallet_id from the response
  3. Get User Vault Balance: Call the Get All User Wallets API with user_id and wallet_id to get user's vault balance
  4. Extract and Display: Extract the balance information from the response and display it to the user
• Result: User can see their current vault balance for the selected category

Step 4: Add Money to Vault (Deposit)

• Purpose: Transfer money from main wallet to vault account
• Process:
  1. Load Currency and Wallet Details: Follow the Common Transaction Flow
  2. Check Product and Calculate Charges:
     • Call the Get User Profile API
     • Call the Get Profile Product API with product_code: "SWTR" (Sub Wallet Transfer)
     • Call the Calculate Charges API with product_code: "SWTR"
  3. Execute Wallet Transfer:
     • Call the Wallet Transfer Money API
     • Set txn_code: "SWTR" (Sub Wallet Transfer)
     • Configure transfer from main wallet to vault wallet
     • Set meta_data.source_wallet_name: "Gafa Wallet" and meta_data.destination_wallet_name: "Vault+"

Add Money to Vault Request Example

{
    "charges_info": null,
    "txn_amount": 10,
    "payment_mode": 3,
    "note": null,
    "txn_code": "SWTR",
    "company_admin_user_info": {
        "currency_id": "1f1519903ed240578f071aa45cb479f2",
        "credit_type": 1,
        "credit_type_id": "4010122e9d604e798b9a6e961df3e5b4",
        "credit_account_type": 1,
        "credit_account_type_id": "640b793d04e2428dbf19ab10399f4edb",
        "username": "Mouhamad Amine"
    },
    "credit_user_info": {
        "currency_id": "1f1519903ed240578f071aa45cb479f2",
        "credit_type": 1,
        "credit_type_id": "3a3d4e585aeb49e8bf3f3996fca0f82f",
        "credit_account_type": 2,
        "credit_account_type_id": "fb8f09210e0f46b7b4262d77f5b6c273",
        "username": "Suresh Raina"
    },
    "debit_user_info": {
        "currency_id": "1f1519903ed240578f071aa45cb479f2",
        "debit_type": 1,
        "debit_type_id": "4010122e9d604e798b9a6e961df3e5b4",
        "debit_account_type": 2,
        "debit_account_type_id": "fb8f09210e0f46b7b4262d77f5b6c273",
        "username": "Suresh Raina"
    },
    "txn_device_info": {
        "device_name": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/140.0.0.0 Safari/537.36",
        "os_name": "MacIntel",
        "location": {},
        "host_name": "localhost",
        "url": "http://localhost:8000"
    },
    "meta_data": {
        "source_wallet_name": "Gafa Wallet",
        "destination_wallet_name": "Vault+"
    }
}

Step 5: Withdraw Money from Vault

• Purpose: Transfer money from vault account back to main wallet
• Process:
  1. Load Currency and Wallet Details: Follow the Common Transaction Flow
  2. Check Product and Calculate Charges:
     • Call the Get User Profile API
     • Call the Get Profile Product API with product_code: "SWW" (Sub Wallet Withdraw)
     • Call the Calculate Charges API with product_code: "SWW"
  3. Execute Wallet Transfer:
     • Call the Wallet Transfer Money API
     • Set txn_code: "SWW"
     • Configure transfer from vault wallet to main wallet
     • Set meta_data.source_wallet_name: "Vault+" and meta_data.destination_wallet_name: "Gafa Wallet"

Withdraw Money from Vault Request Example

{
    "charges_info": null,
    "txn_amount": 10,
    "payment_mode": 3,
    "note": null,
    "txn_code": "SWW",
    "company_admin_user_info": {
        "currency_id": "1f1519903ed240578f071aa45cb479f2",
        "credit_type": 1,
        "credit_type_id": "4010122e9d604e798b9a6e961df3e5b4",
        "credit_account_type": 1,
        "credit_account_type_id": "640b793d04e2428dbf19ab10399f4edb",
        "username": "Mouhamad Amine"
    },
    "credit_user_info": {
        "currency_id": "1f1519903ed240578f071aa45cb479f2",
        "credit_type": 1,
        "credit_type_id": "4010122e9d604e798b9a6e961df3e5b4",
        "credit_account_type": 2,
        "credit_account_type_id": "fb8f09210e0f46b7b4262d77f5b6c273",
        "username": "Suresh Raina"
    },
    "debit_user_info": {
        "currency_id": "1f1519903ed240578f071aa45cb479f2",
        "debit_type": 1,
        "debit_type_id": "3a3d4e585aeb49e8bf3f3996fca0f82f",
        "debit_account_type": 2,
        "debit_account_type_id": "fb8f09210e0f46b7b4262d77f5b6c273",
        "username": "Suresh Raina"
    },
    "txn_device_info": {
        "device_name": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/140.0.0.0 Safari/537.36",
        "os_name": "MacIntel",
        "location": {},
        "host_name": "localhost",
        "url": "http://localhost:8000"
    },
    "meta_data": {
        "source_wallet_name": "Vault+",
        "destination_wallet_name": "Gafa Wallet"
    }
}

Step 6: Lock Vault Amount

• Purpose: Lock funds in the vault for a specific period to prevent withdrawals
• Process:
  1. Validate Lock Parameters:
     • Ensure vault account exists for the user
     • Validate lock amount is available in vault
     • Set appropriate lock and maturity dates
  2. Create Wallet Lock:
     • Call the Save User Wallet Lock API
     • Pass wallet_id (vault wallet), user_wallet_id, currency_id, locked_amount, locked_date, and maturity_date
  3. Handle Response:
     • If successful, show confirmation message
     • If duplicate lock exists, show appropriate error message

Step 7: Modify Vault Maturity Date

• Purpose: Update the maturity date of an existing vault lock
• Process:
  1. Get Existing Lock Details:
     • Call the Get All User Wallet Locks API to find the lock to modify
  2. Update Lock:
     • Call the Update User Wallet Lock API
     • Pass the lock id and new maturity_date
  3. Handle Response:
     • If successful, show confirmation message
     • If lock not found, show appropriate error message

📡 API References

Core Vault APIs

• Get All Sub Wallet Categories API - Get available vault categories (GET /gafapay/v3/base/sub_wallet_category)
• Get All Wallets API - Get category-specific vault wallet details
• Save User Wallet API - Create category-specific vault account
• Wallet Transfer Money API - Transfer money to/from vault
• Save User Wallet Lock API - Lock vault funds
• Get All User Wallet Locks API - Get vault lock details
• Update User Wallet Lock API - Modify vault lock

Admin Configuration APIs

• Save Wallet API (Admin) - Create admin wallet for sub wallet category
• Sub Wallet Category Management (Admin Panel) - Create and manage sub wallet categories

Common Transaction APIs

• Get Currency Details API - Load currency information
• Get Company Main Wallet API - Get company wallet details
• Get Logged-In User Wallet API - Get user wallet information
• Get User Profile API - Get user profile for charges
• Get Profile Product API - Check product permissions
• Calculate Charges API - Calculate transaction charges

🔄 Flow Logic

Admin Configuration Flow

Admin Panel → Create Sub Wallet Category → Create Admin Wallet for Category → Category Ready

Vault Account Creation Flow

User Request → Get Sub Wallet Categories → User Selects Category → Get Category Wallet → Save User Wallet → Vault Account Created

Vault Balance Display Flow

User Request → Select Category → Get Category Wallet → Get User Wallet → Display Balance

Vault Deposit Flow

User Request → Select Category → Load Currency/Wallet → Check SWTR Product → Calculate Charges → Transfer Money (Main → Category Vault) → Success

Vault Withdrawal Flow

User Request → Select Category → Load Currency/Wallet → Check SWW Product → Calculate Charges → Transfer Money (Category Vault → Main) → Success

Vault Lock Flow

User Request → Validate Parameters → Save Wallet Lock → Lock Created

Vault Lock Update Flow

User Request → Get Existing Lock → Update Lock → Lock Modified

💡 Key Implementation Notes

Transaction Codes

• SWTR: Sub Wallet Transfer (for adding money to vault)
• SWW: Sub Wallet Withdraw (for withdrawing money from vault)

Wallet Types

• Type 3: Saving Wallet (Vault wallet type)

Category Configuration

• Category Type 2: Vault categories (fixed for vault sub wallet categories)
• Sub Wallet Category ID: Required to identify and retrieve category-specific wallets
• Multiple categories can be created (e.g., Health, Bills, Education, Emergency)

Account Types

• Credit Type 1: Company Admin Account
• Credit Type 3: Vault Wallet Account
• Debit Type 1: Company Admin Account
• Debit Type 3: Vault Wallet Account

Meta Data Configuration

• Deposit: source_wallet_name: "Gafa Wallet", destination_wallet_name: "Vault+"
• Withdrawal: source_wallet_name: "Vault+", destination_wallet_name: "Gafa Wallet"

Wallet Retrieval Parameters

• For Category Wallet: Use sub_wallet_category_id + currency_id in Get All Wallets API
• For User Vault Balance: Use wallet_id (from category wallet) + user_id + currency_id in Get All User Wallets API

Error Handling

• Duplicate Vault Account: Handle case where user already has a vault account for the selected category
• Category Not Found: Handle case where selected category doesn't exist or is inactive
• Wallet Not Found: Handle case where admin wallet for category doesn't exist
• Insufficient Balance: Check vault balance before withdrawal
• Lock Conflicts: Prevent duplicate locks for same user/wallet combination
• Invalid Dates: Validate lock and maturity dates

🎯 Use Cases

Category-Specific Savings

• Users can create separate vault accounts for different categories (Health, Bills, Education, etc.)
• Organize savings by purpose and track progress for each category
• Lock funds for specific periods to prevent impulsive spending

Personal Savings Goals

• Create multiple category-specific vault accounts for different savings goals
• Track savings progress with category-specific balance display
• Manage funds separately for different financial objectives

Financial Planning

• Set up structured savings plans with maturity dates for each category
• Create category-specific vault accounts for different savings goals
• Manage long-term financial objectives with organized category structure

Investment Preparation

• Lock funds for investment opportunities within specific categories
• Create time-bound savings for specific investments by category
• Manage investment capital allocation across different categories

Emergency Funds

• Create locked emergency funds with specific maturity dates in dedicated categories
• Ensure funds are available when needed for specific purposes
• Maintain financial discipline through fund locking and category organization

Bills and Expenses

• Create vault accounts specifically for bills and recurring expenses
• Lock funds until bill payment dates
• Track bill-related savings separately from other financial goals