Phase 02 — Product Discovery
HITLs #2-#6 Approved PO + Designer + PM ← Ecosystem 🇧🇷 PT

Phase 02 — Product Discovery

Opportunity prioritization, solution hypotheses, prototypes, structured backlog and risk assessment.

Synthetic Personas

3 personas representing the payment gateway users. Built based on the integration, operations and management roles of the ECP ecosystem.

P-01 — Primary Persona (MVP)
Diego Moreira, 29 — Full-Stack Dev of the ECP Ecosystem

Role: Integrator developer | Apps: ecp-bank, ecp-food | Experience: 5 years TypeScript

Context: Needs to integrate payments (Pix, card, boleto) in each ecosystem app. Today reimplements the Asaas integration in each project separately. Tests depend on unstable external gateway sandbox.

Frustrations: Rework with every new app. Asaas sandbox fails and blocks development. No deterministic staging environment. Documentation spread across multiple systems.

Goals: Single API with stable contract. Internal mode for tests without external dependency. Onboarding in hours, not weeks.

“Every time I create a new app in the ecosystem, I reimplement the entire payment integration from scratch. If there was a centralized API, I would do the integration in 1 day instead of 1 week.”

Opportunities: OPP-01, OPP-02, OPP-10, OPP-12 | KRs: KR-01, KR-03, KR-04

P-02 — Primary Persona (MVP)
Patricia Lopes, 33 — Ecosystem Operator / DevOps

Role: Operations and support | Focus: Monitor transactions, investigate failures | Experience: 4 years in fintech ops

Context: Responsible for ensuring ecosystem payments flow smoothly. Investigates transaction failures, reprocesses webhooks and manages the active provider (internal vs Asaas).

Frustrations: To investigate a failure, needs to access logs in 3 different systems. Has no unified view of a transaction's life cycle. No manual webhook retry — requires technical intervention.

Goals: Unified dashboard with ecosystem KPIs. Complete timeline of each transaction. One-click webhook retry. Real-time failure alerts.

“When a transaction fails, it takes me 2 hours to investigate because I need to cross-reference logs from the app, gateway and webhooks. If everything was in one timeline, it would take 5 minutes.”

Opportunities: OPP-06, OPP-13, OPP-14 | KRs: KR-02, KR-05

P-03 — Secondary Persona (Cycle 2)
Ricardo Tavares, 35 — Product Owner / Ecosystem Manager

Role: Product management | Focus: Strategic vision, metrics, costs | Experience: 8 years in digital products

Context: Makes decisions about provider (internal vs Asaas), monitors transaction volumes and costs. Needs consolidated ecosystem view to plan evolutions.

Frustrations: Has no view of transaction volume per app. Does not know how much each real vs simulated transaction costs. No audit of who did what in the admin panel.

Goals: Dashboard with ecosystem metrics. Complete action audit. Provider control with switch history.

“I need to know exactly how many real vs simulated transactions go through the gateway, what the volume per app is, and how much I'm paying in fees to Asaas. Today I have none of those views.”

Opportunities: OPP-06, OPP-08, OPP-09 | KRs: KR-02, KR-05

Key Insights

6 insights extracted from ECP ecosystem analysis, gateway benchmarks (Stripe, Adyen, PagSeguro) and real operational pain points.

INS-01 — High confidence
Reimplementing payment integration in each app is the biggest velocity bottleneck
Each new ecosystem app spends 1–2 weeks integrating with a gateway. A unified API with stable contract reduces this time to hours. The Provider Pattern allows apps not to know which gateway is active.
INS-02 — High confidence
Dependency on external sandbox blocks the development cycle
Asaas sandbox fails intermittently. Payment tests become non-deterministic. Internal mode with deterministic simulation eliminates 100% of external dependency in dev/staging.
INS-03 — High confidence
Investigating failures requires cross-referencing data across multiple systems
Operators need to access app, gateway and database logs to investigate a failure. A unified TransactionTimeline (request → gateway → webhook → callback) reduces investigation from hours to minutes.
INS-04 — High confidence
Retries without idempotency cause duplicate charges
Network failures in production lead apps to resend requests. Without idempotency_key, the gateway creates duplicate transactions. Stripe standard: mandatory X-Idempotency-Key + UNIQUE constraint in database.
INS-05 — Medium confidence
Silently undelivered webhooks compromise reliability
When a callback fails, downstream apps end up with outdated status. Automatic retry with exponential backoff + manual retry via admin panel guarantees eventual delivery.
INS-06 — Medium confidence
Density-first admin panel (Stripe-inspired) is the standard for operational tools
Payment operators need information density, not consumer aesthetics. Stripe/Datadog dashboards are the reference: powerful filters, dense tables, expandable details, correlated timeline.

Prioritized Opportunities (WSJF)

9 opportunities selected for discovery, organized across 3 strategic pillars. Framework: WSJF (Weighted Shortest Job First).

Pillar 1: Core Infrastructure

Unified API, stable contract and provider abstraction — the skeleton on which everything is built.

#IDOpportunityWSJFEffortKRs
1OPP-01Eliminate reimplementation of gateway integration in each app10.0LKR-01, KR-02, KR-03
2OPP-09API contractual stability for consumer apps14.0MKR-01, KR-03
3OPP-08Freedom to negotiate with multiple gateways without rework13.0MKR-03

Pillar 2: Development Velocity

Internal mode, deterministic staging and unified documentation eliminate external dependencies.

#IDOpportunityWSJFEffortKRs
4OPP-10Payment tests depend on unstable Asaas sandbox13.0MKR-04, KR-01
7OPP-12Staging needs to be deterministic and controllable22.0SKR-04
6OPP-02Devs need to understand each gateway API instead of a single contract11.5MKR-01, KR-03

Pillar 3: Production Reliability

Idempotency, guaranteed webhook delivery and complete transaction observability.

#IDOpportunityWSJFEffortKRs
5OPP-14Without idempotency, retries cause duplicate charges13.5MKR-05, KR-02
8OPP-13Callbacks need to be delivered even on temporary failure11.0MKR-05, KR-02
9OPP-06Investigating failures requires accessing logs in multiple systems9.5MKR-02, KR-05
prioritized-opportunities.json

Solution Hypotheses

7 hypotheses formulated by the Product Designer, each with critical assumptions validatable via prototype or interview.

HYP-01 — Core Infrastructure
Unified API with stable contract in Dashboard and Transactions

A unified API layer with versioned contract will give operators real-time visibility of all ecosystem payments, eliminating the need for each app to integrate directly with the gateway.

Assumptions: CA-01 (Dashboard without overload), CA-02 (FilterBar covers 95% of workflows), CA-03 (single contract for Pix/Card/Boleto), CA-04 (source_app attribution sufficient).

HYP-02 — Core Infrastructure
Provider Pattern with ProviderToggle in admin panel

A provider abstraction layer, surfaced by a dedicated Providers page with ProviderToggle, will allow the super admin to switch between Internal and External without impacting downstream apps.

Assumptions: CA-05 (two-card toggle prevents accidents), CA-06 (confirmation modal), CA-07 (status in 3 persistent locations), CA-08 (swap history).

HYP-03 — Development Velocity
Internal Mode with simulation controls in Settings

Internal Mode with simulation controls in the Settings page and contextual actions in the Transactions page will eliminate Asaas sandbox dependency, enabling deterministic testing.

Assumptions: CA-09 (admin panel vs env vars), CA-10 (yellow banner sufficient), CA-11 (contextual simulation buttons), CA-12 (feature flags via Toggle).

HYP-04 — Development Velocity
Unified documentation via Apps page and interactive examples

Accessible documentation from the admin panel (Apps page) with interactive examples using Internal mode will reduce onboarding from weeks to hours.

Assumptions: CA-13 (Apps page as entry point), CA-14 (real payloads as learning material), CA-15 (self-service registration modal).

HYP-05 — Production Reliability
Idempotency visible in admin panel

Showing idempotency_key per transaction, flagging deduplicated requests and duplicates in the timeline will give operators confidence that duplicate charges do not occur.

Assumptions: CA-16 (idempotency_key visible), CA-17 (dedup event in timeline), CA-18 (no dedicated duplicates dashboard).

HYP-06 — Production Reliability
Webhooks page with Received/Sent tabs and manual retry

Dedicated Webhooks page with received/sent tabs, delivery status tracking and one-click retry will give full control over event delivery.

Assumptions: CA-19 (two-tab mental model), CA-20 (attempt count with timing), CA-21 (retry button sufficient), CA-22 (CodeBlock for debugging).

HYP-07 — Production Reliability
TransactionTimeline with complete life cycle

TransactionTimeline component showing the complete cycle (request → gateway → webhook → callback) with correlated timestamps will reduce investigation time from hours to minutes.

Assumptions: CA-23 (clear vertical timeline), CA-24 (elapsed time between events), CA-25 (semantic colors), CA-26 (expandable nodes with payload).

ideation-output.json

Prototypes

📝 Low-fi Prototype (Wireframes) 🎨 High-fi Prototype (Visual)

8 prototyped screens: Dashboard, Transactions, Transaction Detail, Providers, Webhooks, Apps, Settings, Audit Log.

Structured Backlog

3 epics, 13 features and 29 user stories with BDD/Gherkin acceptance criteria.

EP-01
Core Payment Infrastructure
Unified API, Provider Pattern, app authentication, token vault and payment split. Serves KR-01, KR-02 and KR-03.
FT-01
Unified Payment API (Pix, Card, Boleto)
POST /pay/pix, POST /pay/card, POST /pay/boleto, GET /pay/transactions/:id, POST /pay/transactions/:id/refund
US-01 Create Pix charge via API (QR Code + copy-paste)
US-02 Charge credit card via API (new or tokenized)
US-03 Issue registered boleto via API with embedded Pix QR Code
US-04 Query status of any transaction
US-05 Refund transaction fully or partially
FT-02
Provider Pattern with Gateway Abstraction
PaymentProvider interface, AsaasAdapter, InternalAdapter, ProviderFactory with feature flag
US-06 Switch between Internal and Asaas provider via admin panel
US-07 Identical API contract regardless of active provider
FT-03
Authentication and Registration of Consumer Apps
X-API-Key, X-Source-App, rate limiting 100 tx/min per app
US-08 Register new app via admin panel
US-09 Authentication via API key with rate limiting
FT-04
Card Token Vault (Cross-App)
Secure tokenization, never persists sensitive data, reusable across apps
US-10 Tokenize card during charge for future reuse
FT-05
Payment Split per Transaction
Split rules per transaction, validation sum = total, multi-party distribution
US-11 Define split rules when creating transaction
EP-02
Ecosystem Development Velocity
Internal mode, deterministic staging and developer onboarding. Serves KR-04 and KR-01.
FT-06
Internal Mode — Full Payment Simulation
InternalAdapter simulates Pix (auto-approve), Card (deterministic rules), Boleto (mock)
US-12 Pix auto-approved in internal mode
US-13 Card with deterministic rules in internal mode
US-14 Boleto with mock code in internal mode
FT-07
Deterministic Staging Environment
Runtime-editable feature flags, internal mode banner, admin configuration
US-15 Configure simulation parameters via admin panel
US-16 Clear visual banner when internal mode is active
FT-08
App Management and Developer Onboarding
Apps page, self-service registration, request/response payloads as examples
US-17 View registered apps with metrics in admin panel
US-18 See request/response payloads in transaction detail
EP-03
Production Reliability and Operations
Idempotency, webhook retry, observability, audit and RBAC authentication. Serves KR-05 and KR-02.
FT-09
Idempotency and Transaction Deduplication
Mandatory X-Idempotency-Key, UNIQUE constraint, dedup in audit log
US-19 Retries with same idempotency_key return original result
US-20 Idempotency_key and dedup events visible in detail
FT-10
Webhook Delivery with Exponential Backoff Retry
Automatic callbacks, retry 3x (30s, 2min, 10min), manual retry via admin
US-21 Automatic callbacks when transaction status changes
US-22 Failed callbacks retried with exponential backoff
US-23 Manage webhooks with manual retry option in panel
FT-11
Transaction Observability — Timeline and Dashboard
TransactionTimeline, 6 KPI cards, volume/type/success rate charts
US-24 Full transaction timeline in detail
US-25 Dashboard with KPIs and ecosystem charts
US-26 Filter and search transactions with multiple criteria
FT-12
Audit and Structured Logging
Audit log for all admin actions, soft delete policy, structured logging
US-27 Every administrative action recorded in audit log
US-28 Operational actions (reprocess, refund, cancel) in detail
FT-13
Admin Panel Authentication and RBAC
JWT login, 3 roles (admin, operator, viewer), RBAC on all routes
US-29 Login with email/password and role-based access control
backlog-and-risks.json

Cagan's 4 Risks Assessment

Customer Value
Approved approved
OST validated with 15 opportunities mapped to 5 KRs. 7 solution hypotheses with 26 critical assumptions. 3 personas with distinct needs. 9 opportunities prioritized via WSJF covering the full journey from integration to operations.
Business Value
Approved approved
All 5 KRs covered with full coverage. EP-01 + EP-02 serve KR-01 to KR-04. EP-03 serves KR-05 and KR-02. Residual risk: SQLite may be a bottleneck if volume exceeds expectations (AS-03).
Usability
Approved approved
8 screens, 7 flows and 8 interactions validated. Design follows density-first standard (Stripe/Datadog inspiration). Norman's principles applied: status visibility, feedback, constraints. Admin panel is an operational tool, not consumer-facing.
Technical Feasibility
Approved approved
Stack identical to existing ecosystem (TypeScript + Fastify + SQLite + React + Vite). Provider Pattern is a well-documented standard. 29 endpoints, 8 SPA routes, 13 features — feasible scope. RBAC with JWT already proven in ecp-digital-bank.
backlog-and-risks.json