WAGERBABE DOCS
All Stories
9-3-debit-customer-accountDoneEpic 9.3

Story 9.3: Debit Customer Account

Status: done

Tasks

  • Task 1: Create DebitAccountRequest Model (AC: 1, 3)
    • 1.1 Create Pydantic model in `server/app/models/transaction.py` or new cashier models file
    • 1.2 Add customer_id field (UUID string)
    • 1.3 Add amount field with Decimal type, gt=0 validator
    • 1.4 Add description field with min_length=1 validator
    • 1.5 Add allow_overdraft boolean field (default=False)
    • 1.6 Add optional external_reference field for tracking
  • Task 2: Create Debit Endpoint (AC: 1, 2, 11, 12)
    • 2.1 Create or update `server/app/api/v1/endpoints/agents/cashier.py` file
    • 2.2 Implement POST /cashier/debit endpoint with get_current_agent dependency
    • 2.3 Parse DebitAccountRequest from request body
    • 2.4 Return structured response with success, transaction_id, balances, timestamp
    • 2.5 Add proper error handling with HTTPException for all error cases
  • Task 3: Agent Ownership Verification (AC: 2, 12)
    • 3.1 Query users table for customer by customer_id
    • 3.2 Verify customer exists (404 if not found)
    • 3.3 Verify customer.agent_id matches current_agent.id (403 if not authorized)
    • 3.4 Retrieve customer account_balance, credit_limit, account_type for overdraft logic
  • Task 4: Overdraft Protection Logic (AC: 4, 5, 6)
    • 4.1 Calculate new_balance = current_balance - debit_amount
    • 4.2 For Credit accounts: Check if new_balance < -credit_limit, raise 400 error with available credit message
    • 4.3 For PostUp accounts: Check if new_balance < 0 AND allow_overdraft=false, raise 400 error with insufficient funds message
    • 4.4 Format error messages with specific amounts (e.g., "Insufficient credit. Available: $5,234.56")
    • 4.5 Allow negative balance for PostUp if allow_overdraft=true (for admin corrections)
  • Task 5: Atomic Database Transaction (AC: 7, 8, 9, 10)
    • 5.1 Begin database transaction using async with database.transaction() or Supabase equivalent
    • 5.2 Create financial_transactions record with all required fields (user_id, agent_id, transaction_type, amount, balance_before, balance_after)
    • 5.3 Update users.account_balance with new_balance
    • 5.4 Create agent_transactions record for agent's tracking
    • 5.5 Commit transaction (rollback on any error)
    • 5.6 Return transaction_id from financial_transactions insert
  • Task 6: Testing & Validation (AC: 1-12)
    • 6.1 Unit test: Verify DebitAccountRequest model validation (positive amount, required fields)
    • 6.2 Integration test: Successful debit for PostUp account with sufficient funds
    • 6.3 Integration test: Successful debit for Credit account within credit limit
    • 6.4 Integration test: Credit account prevents debit exceeding credit_limit
    • 6.5 Integration test: PostUp account prevents overdraft when allow_overdraft=false
    • 6.6 Integration test: PostUp account allows overdraft when allow_overdraft=true
    • 6.7 Integration test: Verify agent ownership check (403 for wrong agent)
    • 6.8 Integration test: Verify customer not found returns 404
    • 6.9 Integration test: Verify transaction audit trail (financial_transactions and agent_transactions created)
    • 6.10 Integration test: Verify atomic transaction (rollback on error)

Progress

Tasks0/6
Acceptance Criteria0
Total Tasks6

Navigation

View Epic 9.3All Stories