# core-midtrans-cifo - Epic Breakdown

**Date:** 2025-11-25
**Project Level:** Quick-Flow (2 Stories)

---

## Epic 1: Payment Flow UX Improvements

**Slug:** payment-ux-improvements

### Goal

Improve payment flow user experience for non-tech-savvy users (ibu-ibu awam) by eliminating duplicate VA generation errors, providing clear loading feedback, implementing user-friendly error messages, and guiding users after successful payment completion.

**Business Value:**
- Reduce abandoned transactions by 20%+
- Decrease support tickets by 30%+
- Increase payment completion rate by 10%+
- Improve user trust and satisfaction

**User Value:**
- Clear feedback during payment processing
- No more confusing technical error messages
- Obvious next steps after payment success
- Smooth, anxiety-free payment experience

### Scope

**In Scope:**

✅ **Prevent Duplicate VA Generation**
- Button disable logic during VA generation
- Request debouncing (500ms)
- Loading overlay with clear messaging
- User-friendly error messages in Bahasa Indonesia

✅ **Improve Error Handling**
- Map HTTP 409 → "Kode pembayaran Anda sudah dibuat! Klik di sini untuk melihat"
- Map HTTP 404 → "Terjadi kesalahan. Silakan coba lagi"
- Recovery buttons ("Coba Lagi", "Lihat Kode Pembayaran", "Kembali")

✅ **Post-Payment UX**
- 5-second countdown timer on success page
- Auto-redirect to dashboard after countdown
- Manual "Kembali Sekarang" button for impatient users

✅ **Mobile-First Design**
- All components optimized for mobile devices
- Responsive design with TailwindCSS
- Touch-friendly buttons (minimum 44x44px)

**Out of Scope:**

❌ **Phase 2 Solutions** (future epics):
- Navigation guards (useEffect cleanup)
- Modal-based success page
- Progressive loading states
- Transaction state machine
- Idempotency key implementation

❌ **Backend Changes:**
- Midtrans API modifications
- Database schema changes
- Backend validation logic

❌ **Complete Redesign:**
- Single-page payment flow
- Optimistic UI patterns
- Guided tour/onboarding

### Success Criteria

**User Experience Success:**
1. ✅ Users cannot generate VA multiple times (button disabled during processing)
2. ✅ Users see clear loading feedback ("Sedang membuat kode pembayaran...")
3. ✅ Error messages are in Bahasa Indonesia and user-friendly
4. ✅ Users have clear recovery options on errors
5. ✅ Users know exactly what to do after payment success (countdown + CTA)

**Technical Success:**
1. ✅ Zero HTTP 409 errors from duplicate VA generation
2. ✅ All error messages mapped to user-friendly Indonesian text
3. ✅ Loading overlay prevents interaction during processing
4. ✅ Auto-redirect works correctly after 5-second countdown
5. ✅ All components work on mobile devices (Chrome, Safari)

**Business Success:**
1. ✅ Reduced abandoned transaction rate (measure before/after)
2. ✅ Reduced support tickets related to payment confusion
3. ✅ Increased payment completion rate
4. ✅ Positive user feedback on payment experience

**Acceptance Criteria Coverage:**
- 10 detailed acceptance criteria defined in tech-spec
- All criteria testable and measurable
- Coverage across both user stories

### Dependencies

**External Dependencies:**
- ✅ Midtrans API (existing integration, no changes required)
- ✅ React 19.1.1 (already installed)
- ✅ Framer Motion 12.23.24 (already installed)
- ✅ TailwindCSS 4.1.17 (already installed)

**Internal Dependencies:**
- ✅ Existing payment feature module (`src/features/payment/`)
- ✅ Existing Midtrans service layer (`src/services/`)
- ✅ Existing TailwindCSS design system

**No New Dependencies Required** - All solutions use existing tech stack

**Prerequisites:**
- None - This is Phase 1, no prior work required
- Brownfield codebase analysis completed (problem-solution doc)
- Tech-spec completed and approved

---

## Story Map - Epic 1

```
Epic 1: Payment Flow UX Improvements (7 points)
│
├── Story 1.1: Prevent Duplicate VA/QR/Code Generation & Improve Feedback (5 points)
│   │
│   ├── Create utility functions (debounce, errorMessages)
│   ├── Create LoadingOverlay component
│   ├── Modify payment method component
│   │   ├── Add button disable logic
    │   ├── Add auto-redirect logic
    │   └── Add manual redirect button
    └── Write tests and verify
    
    Dependencies: None (independent of Story 1.1)
    Deliverable: Users have clear guidance after payment success,
                 auto-redirect prevents back button confusion
```

**Implementation Sequence:**
1. **Story 1.1** - Can be implemented first (no dependencies)
2. **Story 1.2** - Can be implemented in parallel or after Story 1.1

**Note:** Stories are independent and can be implemented in any order or in parallel.

---

## Stories - Epic 1

### Story 1.1: Prevent Duplicate VA Generation & Improve Feedback

As a **non-tech-savvy user (ibu-ibu)**,
I want **clear feedback during VA generation and user-friendly error messages**,
So that **I don't accidentally create duplicate payment codes and I understand what to do when errors occur**.

**Acceptance Criteria:**

**AC #1: Button Disable During Processing**
- **Given** user clicks "Generate VA" button
- **When** API request is in progress
- **Then** button is disabled and shows loading spinner
- **And** user cannot click button again
- **And** loading overlay appears with message "Sedang membuat kode pembayaran..."

**AC #2: Debounce Prevents Rapid Clicks**
- **Given** user clicks "Generate VA" button multiple times within 500ms
- **When** debounce is active
- **Then** only one API request is sent
- **And** subsequent clicks within 500ms are ignored

**AC #3: User-Friendly Error Messages**
- **Given** VA generation fails with HTTP 409
- **When** error is displayed to user
- **Then** message shows "Kode pembayaran Anda sudah dibuat! Klik di sini untuk melihat"
- **And** "Lihat Kode Pembayaran" button is displayed
- **And** clicking button navigates to existing VA view

**AC #4: Error Recovery Options**
- **Given** VA generation fails with any error
- **When** error is displayed to user
- **Then** "Coba Lagi" button is displayed
- **And** clicking button retries VA generation
- **And** "Kembali" button is displayed
- **And** clicking button returns to payment method selection

**AC #5: Loading Overlay Prevents Interaction**
- **Given** VA generation is in progress
- **When** loading overlay is displayed
- **Then** user cannot interact with page content
- **And** overlay shows clear message in Bahasa Indonesia
- **And** overlay is responsive on mobile devices

**Prerequisites:** None

**Technical Notes:**
- Use existing React hooks (useState, useEffect)
- Leverage Framer Motion for overlay animations
- Follow existing TailwindCSS design patterns
- No new dependencies required

**Estimated Effort:** 5 points (~2-3 days) - Covers all 3 payment methods (Bank Transfer, GoPay/QRIS, Convenience Store)

---

### Story 1.2: Improve Post-Payment UX

As a **non-tech-savvy user (ibu-ibu)**,
I want **clear guidance on what to do after successful payment**,
So that **I don't get confused and press the back button which causes errors**.

**Acceptance Criteria:**

**AC #6: Countdown Timer Display**
- **Given** user completes payment successfully
- **When** payment success page loads
- **Then** countdown timer shows "Anda akan diarahkan ke dashboard dalam 5 detik..."
- **And** countdown decrements every second (5, 4, 3, 2, 1)
- **And** timer is visible and readable on mobile devices

**AC #7: Auto-Redirect After Countdown**
- **Given** countdown timer reaches 0
- **When** timer completes
- **Then** user is automatically redirected to dashboard/home page
- **And** redirect happens smoothly without errors

**AC #8: Manual Redirect Button**
- **Given** countdown timer is active
- **When** user clicks "Kembali Sekarang" button
- **Then** user is immediately redirected to dashboard/home page
- **And** countdown is cancelled

**AC #9: Mobile-First Responsive Design**
- **Given** user accesses payment flow on mobile device
- **When** countdown and button are displayed
- **Then** all elements are properly sized and positioned for mobile
- **And** all text is readable without zooming
- **And** button is easily tappable (minimum 44x44px)

**AC #10: Bahasa Indonesia Throughout**
- **Given** user views success page
- **When** text is displayed
- **Then** all text is in Bahasa Indonesia
- **And** language is appropriate for non-tech-savvy users
- **And** no technical jargon is used

**Prerequisites:** None

**Technical Notes:**
- Use useEffect with setTimeout for countdown
- Use useNavigate from react-router-dom for redirect
- Follow existing TailwindCSS responsive patterns
- Ensure proper cleanup on component unmount

**Estimated Effort:** 2 points (~1 day)

---

## Implementation Timeline - Epic 1

**Total Story Points:** 7 points

**Estimated Timeline:** 3-4 days (assuming 1.5-2 points per day)

**Recommended Sequence:**
1. Story 1.1 (3 points) - Implement first or in parallel
2. Story 1.2 (2 points) - Implement second or in parallel

**Notes:**
- Stories are independent and can be worked on in parallel by different developers
- Both stories should be completed before deployment to production
- Comprehensive testing required after both stories complete
- Deployment can happen after both stories pass QA

---

**Epic Status:** Draft - Ready for Implementation

**Next Steps:**
1. Review and approve epic and stories
2. Assign stories to developers
3. Begin implementation following tech-spec guidance
4. Track progress in sprint board
5. Deploy to production after QA approval