Overview The Wallets API enables management of financial wallets (money sources) for users. Each wallet tracks a balance and can represent cash, bank accounts, or other payment methods.
Base Path: /api/walletsAuthentication: Required (@api_login_required decorator)Get All Wallets Retrieve all wallets belonging to the authenticated user.
Authentication Required. User must be logged in with valid session.
Response Array of wallet objects Wallet ID (8-character UUID)
Wallet name (e.g., “Tiền mặt”, “Ngân hàng ACB”)
Wallet type (e.g., “Tiền mặt”, “Ngân hàng”, “Ví điện tử”)
Example Request curl -X GET https://api.finai.com/api/wallets \ -H "Cookie: session=your-session-cookie"
Example Response [ { "MaNguonTien" : "w9876543" , "TenNguonTien" : "Tiền mặt" , "LoaiNguonTien" : "Tiền mặt" , "SoDu" : 2500000 }, { "MaNguonTien" : "w1234567" , "TenNguonTien" : "Ngân hàng ACB" , "LoaiNguonTien" : "Ngân hàng" , "SoDu" : 15000000 }, { "MaNguonTien" : "w5555555" , "TenNguonTien" : "MoMo" , "LoaiNguonTien" : "Ví điện tử" , "SoDu" : 500000 } ]
Create Wallet Add a new wallet to the user’s account.
Request Body Wallet name (e.g., “Tiền mặt”, “Ngân hàng Vietcombank”)
Wallet type. Common values:
Tiền mặt - CashNgân hàng - Bank accountVí điện tử - E-walletThẻ tín dụng - Credit card Initial balance (defaults to 0)
Example Request curl -X POST https://api.finai.com/api/wallets \ -H "Content-Type: application/json" \ -H "Cookie: session=your-session-cookie" \ -d '{ "name": "Ngân hàng Techcombank", "type": "Ngân hàng", "balance": 10000000 }'
Response Error message (only present on error)
{ "status" : "error" , "message" : "Invalid balance value" }
Error Codes Status Code Description 200 Wallet created successfully 401 Unauthorized (not logged in) 500 Database or validation error
Update Wallet Modify an existing wallet’s details.
Path Parameters Request Body Show Important: Direct Balance Updates
This endpoint allows direct balance modification. For transactional balance changes (income, expenses, transfers), use the Transactions API instead, which automatically updates wallet balances and maintains transaction history. Example Request curl -X PUT https://api.finai.com/api/wallets/w1234567 \ -H "Content-Type: application/json" \ -H "Cookie: session=your-session-cookie" \ -d '{ "name": "Ngân hàng ACB - Chính", "type": "Ngân hàng", "balance": 18000000 }'
Response Error Codes Status Code Description 200 Wallet updated successfully 401 Unauthorized 404 Wallet not found or doesn’t belong to user 500 Database error
Delete Wallet Remove a wallet from the user’s account.
Path Parameters Show ⚠️ Cascade Deletion Warning
Deleting a wallet will affect related transactions. The database is configured with ondelete='CASCADE' for transactions, which means:
All transactions associated with this wallet will be deleted
This action cannot be undone
Ensure users have exported or backed up important transaction data before deletion
Example Request curl -X DELETE https://api.finai.com/api/wallets/w1234567 \ -H "Cookie: session=your-session-cookie"
Response { "status" : "error" , "message" : "Cannot delete wallet with existing transactions" }
Error Codes Status Code Description 200 Wallet deleted successfully 401 Unauthorized 404 Wallet not found 500 Database error or constraint violation
Database Schema Reference from app/models.py:
class Wallet ( db . Model ): __tablename__ = 'nguontien' id = db.Column( 'MaNguonTien' , db.String( 8 ), primary_key = True ) user_id = db.Column( 'MaNguoiDung' , db.String( 8 ), db.ForeignKey( 'nguoidung.MaNguoiDung' , ondelete = 'CASCADE' ), nullable = False ) name = db.Column( 'TenNguonTien' , db.String( 100 ), nullable = False ) type = db.Column( 'LoaiNguonTien' , db.String( 50 )) balance = db.Column( 'SoDu' , db.Float, default = 0.0 ) created_at = db.Column( 'NgayTao' , db.DateTime, default = datetime.now)
Implementation Reference Source: app/routes/foundation.py:10-47
Show Key Implementation Details
Wallet IDs are 8-character UUIDs: str(uuid.uuid4())[:8]
All queries filter by user_id for data isolation
Balance is stored as Float type in database
Vietnamese field names used in database (e.g., MaNguonTien, TenNguonTien)
Returns HTTP 404 when wallet not found or doesn’t belong to user
All database operations wrapped in try-catch with rollback on error
