Phase 03 — Product Delivery

ECP Pay uses the Provider Pattern to abstract payment gateways. Ecosystem apps call a single API — the factory selects the active adapter (Internal or Asaas) via feature flag, without the apps knowing which is active.

graph TD
    A["ecp-bank :3333"] -->|X-API-Key| B["ECP Pay API :3335"]
    C["ecp-emps :3334"] -->|X-API-Key| B
    D["ecp-food :3000"] -->|X-API-Key| B
    B --> E["Payment Service"]
    E --> F["Provider Factory"]
    F -->|"feature flag"| G["Internal Adapter"]
    F -->|"feature flag"| H["Asaas Adapter"]
    G --> I[("SQLite")]
    H --> J["Asaas API"]
    B --> K["Admin Panel :5176"]
      

Bounded Contexts

Pix Payment — Full Flow (Internal Provider)

sequenceDiagram
    participant App as App (ecp-food)
    participant Pay as ECP Pay API :3335
    participant Svc as Payment Service
    participant Prov as Internal Adapter
    participant DB as SQLite

    App->>Pay: POST /pay/pix
    Note over Pay: Headers: X-API-Key, X-Idempotency-Key

    Pay->>Pay: Validate API Key (app_registrations)
    Pay->>DB: SELECT WHERE idempotency_key = ?
    DB-->>Pay: null (new)

    Pay->>Svc: createPixPayment(data)
    Svc->>Prov: ProviderFactory.get("internal")
    Prov->>Prov: Generate QR Code + copy-paste

    Note over Svc,DB: Atomic transaction
    Svc->>DB: INSERT transactions (status: pending)
    Svc->>DB: INSERT splits (if defined)
    DB-->>Svc: transactionId

    Prov->>Prov: Configurable delay (3-5s)
    Prov->>DB: UPDATE transactions SET status = paid

    Svc->>App: POST callback_url (status: paid)
    Note over App: Webhook delivery with retry

    Pay-->>App: { id, status: pending, qrCode, copyPaste }
      

Card Payment — Asaas Provider (External)

sequenceDiagram
    participant App as App (ecp-bank)
    participant Pay as ECP Pay API
    participant Svc as Payment Service
    participant Prov as Asaas Adapter
    participant Asaas as Asaas API
    participant DB as SQLite

    App->>Pay: POST /pay/card
    Note over Pay: { amount, card: {number, cvv, ...}, customer }

    Pay->>Pay: Validate API Key + Idempotency
    Pay->>Svc: createCardPayment(data)
    Svc->>Prov: ProviderFactory.get("external")

    Prov->>DB: SELECT card_tokens WHERE customer_document
    alt New card
        Prov->>Asaas: POST /payments (card data)
        Asaas-->>Prov: { id, status, token }
        Prov->>DB: INSERT card_tokens (token, last4, brand)
    else Tokenized card
        Prov->>Asaas: POST /payments (token)
        Asaas-->>Prov: { id, status }
    end

    Svc->>DB: INSERT transactions (status: pending)

    Note over Asaas,Pay: Async webhook
    Asaas->>Pay: POST /pay/webhooks/asaas
    Pay->>DB: INSERT webhook_events (dedup event_id)
    Pay->>DB: UPDATE transactions SET status = paid
    Pay->>App: POST callback_url (status: paid)
      

Provider Switch — Internal ↔ External

sequenceDiagram
    participant Admin as Admin (Browser)
    participant Panel as Admin Panel :5176
    participant API as Admin API
    participant DB as SQLite

    Admin->>Panel: Opens Providers page
    Panel->>API: GET /admin/providers
    API->>DB: SELECT feature_flags WHERE key = PAYMENT_PROVIDER
    DB-->>API: { value: "internal" }
    API-->>Panel: { active: "internal", available: ["internal", "external"] }
    Panel-->>Admin: Two-card with toggle (Internal active)

    Admin->>Panel: Clicks "Activate External"
    Panel-->>Admin: Confirmation modal
    Admin->>Panel: Confirms switch

    Panel->>API: POST /admin/providers/switch
    Note over API: Middleware: requireRole("admin")
    API->>DB: UPDATE feature_flags SET value = "external"
    API->>DB: INSERT audit_logs (action: provider_switch)
    API-->>Panel: { active: "external", switchedAt }

    Panel-->>Admin: Updated banner + confirmation toast
    Note over Admin: All new transactions use Asaas
      

Webhook Delivery — Exponential Backoff Retry

sequenceDiagram
    participant Pay as ECP Pay
    participant DB as SQLite
    participant App as App callback_url

    Note over Pay,App: Transaction status changed

    Pay->>DB: SELECT callback_url FROM transactions
    Pay->>App: POST callback_url (attempt 1)

    alt Success (2xx)
        App-->>Pay: 200 OK
        Pay->>DB: UPDATE: delivery_status = delivered
    else Failure (timeout/5xx)
        App-->>Pay: 500 / timeout

        Note over Pay: Retry 1: wait 30s
        Pay->>App: POST callback_url (attempt 2)
        App-->>Pay: 500 / timeout

        Note over Pay: Retry 2: wait 2min
        Pay->>App: POST callback_url (attempt 3)
        App-->>Pay: 500 / timeout

        Note over Pay: Retry 3: wait 10min
        Pay->>App: POST callback_url (attempt 4)

        alt Success
            App-->>Pay: 200 OK
            Pay->>DB: UPDATE: delivery_status = delivered
        else Final failure
            Pay->>DB: UPDATE: delivery_status = failed
            Note over Pay: Admin can perform manual retry
        end
    end
      

Payment API (app-facing) — /pay

Authentication via X-API-Key header. 9 endpoints.

Admin API (web panel) — /admin

Authentication via JWT Bearer token. 20 endpoints.

10 tables + 16 indexes. SQLite with WAL mode via better-sqlite3. Migration: 001-initial.sql.