Complete6. Request Lifecycle (Sequence Diagram)Diagrams

6.1 Remittance Initiation Flow

sequenceDiagram
    participantautonumber
    actor Client
    participant CORS as CORS Middleware
    participant ReqID as Request ID Middleware
    participant IP as Client IP Middleware(Web/Mobile)
    participant RouterRL as HonoRate RouterLimiter
    participant Auth as Auth Middleware
    participant RLRoute as Rate Limiter
    participant FG as Feature Gate
    participant Handler asTransactions Route Handler
    participant DB as Database
    participant ErrHPISP as ErrorOpen HandlerBanking PISP

    Client->>CORS:RL: HTTPPOST Request
    CORS->>CORS: Check origin, set CORS headers
    CORS->>ReqID: next()
    ReqID->>ReqID: Extract/generate x-request-id
    ReqID->>IP: next()
    IP->>IP: Extract client IP from headers
    IP->>Router: next()

    Router->>Router: Match route (/v1/*transactions/remittance
    or /api/*)

    alt Public route (health, rates)
        Router->>Handler: Direct execution
    else Authenticated route
        Router->>Auth: authMiddleware / adminMiddleware / merchantMiddleware
        Auth->>DB: Verify JWT + session
        alt Token invalid
            Auth-->>Client: 401 Unauthorized
        else Token valid
            Auth->>Auth: Set c.user
            Auth-RL->>RL: Check rate limitrate_limits (inline)10/IP, 3/user per 60s)
    alt Rate limit exceeded
        RL-->>Client: 429 Too Many Requests
    else Within limitend
    RL->>FG:Auth: CheckForward featurerequest
    flagAuth->>Auth: Extract JWT from Bearer header / cookie
    Auth->>DB: SELECT session WHERE token_hash = ? AND revoked = 0
    Auth->>DB: SELECT user WHERE id = ? AND deleted_at IS NULL
    Auth-->>Route: user context {userId, role, kycStatus}

    Route->>Route: Validate body: recipientId, amount (if100-50000), applicable)bankAccountId
    alt FeatureValidation disabledfails
        FG-Route-->>Client: 400 validation_error
    end
    alt kyc_status != 'approved'
        Route-->>Client: 403 kyc_required
    end

    Route->>DB: SELECT * FROM recipients WHERE id = ? AND user_id = ?
    alt Recipient not found
        Route-->>Client: 404 Featurerecipient_not_found
    notend
    available
                else Feature enabled
                    FG->>Handler: Execute route logic
                    Handler-Route->>DB: Query/mutationSELECT Handler-rate FROM exchange_rates WHERE to_currency = ?
    Route->>DB: SELECT * FROM bank_accounts WHERE id = ? AND user_id = ? AND is_primary = 1

    Route->>Route: Calculate fee (0.5%), total cost, receive amount
    alt balance < totalCost
        Route-->>Client: JSON403 responseinsufficient_balance
    end

    endRoute->>DB: endBEGIN endTRANSACTION
    NoteRoute->>DB: overUPDATE Handler,ErrH:bank_accounts IfSET anybalance error= isbalance thrown- Handler-totalCostInOere WHERE balance >= ?
    Route->>DB: INSERT INTO transactions (status='processing', idempotency_key=?)
    Route->>DB: INSERT INTO audit_log (action='transaction.create')
    Route->>DB: INSERT INTO notifications (title='Overføring startet')
    Route->>DB: COMMIT

    Route->>PISP: POST /v1/payments/cross-border-credit-transfers
    PISP-->>ErrH:Route: Unhandled{paymentId, errortransactionStatus: ErrH->>ErrH:"RCVD", LogscaRedirect}

    + Sentry report
    ErrH-Route-->>Client: 500201 Internal{transactionId, Serverstatus: Error"processing", scaRedirect}

6.2 QR Payment Flow

sequenceDiagram
    autonumber
    actor Client as Client (Mobile)
    participant Route as Transactions Route
    participant DB as Database

    Client->>Route: POST /v1/transactions/qr-payment {merchantId, amount}
    Route->>DB: Verify JWT session
    Route->>DB: SELECT * FROM merchants WHERE id = ? AND status = 'active'
    alt Merchant not found
        Route-->>Client: 404 merchant_not_found
    end
    Route->>DB: SELECT * FROM bank_accounts WHERE user_id = ? AND is_primary = 1

    Route->>Route: Calculate fee = amount * merchant.fee_rate
    Route->>Route: Calculate total = amount + fee

    Route->>DB: BEGIN TRANSACTION
    Route->>DB: UPDATE bank_accounts SET balance = balance - total
    Route->>DB: INSERT INTO transactions (type='qr_payment', status='completed')
    Route->>DB: INSERT INTO audit_log (action='qr_payment.create')
    Route->>DB: INSERT INTO notifications (title='Betaling registrert')
    Route->>DB: COMMIT

    Route-->>Client: 201 {transactionId, status: "completed", merchantName}

Input7. ValidationState Diagrams

Input

stateDiagram-v2
    validation[*] is--> notprocessing: middlewarePOST /v1/transactions/remittance (PISP initiated)

    processing --> completed: PISP webhook — itpayment isconfirmed aby collectionbank
    ofprocessing utility--> functionsfailed: PISP webhook — payment rejected (insufficient funds, SCA timeout, SCA cancelled)
    processing --> failed: 5-minute SCA timeout — no callback received

    completed --> [*]
    failed --> [*]

Note: QR payments go directly from creation to completed (synchronous in middleware/validation.tsMVP called— directlyno byPISP routewebhook handlers.for domestic transfers in mock mode).

State Transition Rules:

8. Error Handling Strategy

8.1 Error Classification

8.2 Error Response Format

{
  "error": "kyc_required",
  "message": "Du må fullføre identitetsverifisering før du kan sende penger.",
  "details": []
}

8.3 Retry & Fallback Strategy

PISP API call failure:
  → Retry with exponential backoff: [1s, 2s, 4s]
  → Max retries: 3
  → Circuit breaker: Open after 3 failures in 60s window → 60s cooldown
  → Fallback: Return 502 to client — payment cannot proceed without PISP
  → Alert: Sentry alert if circuit remains open > 5 minutes
  → Idempotency: PISP call uses X-Request-ID = idempotency_key to prevent double-payment on retry

9. Concurrency & Thread Safety

10. Performance Considerations

Known bottlenecks:

• PISP API latency: 200-2000ms external call — mitigated by async SCA redirect pattern
• Exchange rate reads: High frequency but 6 rows only — fully cached in PostgreSQL buffer pool

11. Dependencies

Internal Dependencies

External Dependencies

Cross-References12. Configuration Parameters

13. Testing Approach

Key test scenarios:

• Security ArchitectureRemittance — Trustsuccess boundaries,path STRIDE,(mock application security controlsPISP)
• Authentication Remittance — JWT,KYC sessionnot management,approved BankID→ OIDC403
• API ReferenceRemittance — Endpointamount specifications< and100 securityNOK requirements→ 422
• Login Authentication FlowRemittance — BankIDamount OIDC> authentication50,000 detailNOK → 422
•  Remittance — recipient not found → 404
•  Remittance — duplicate request (idempotency key) → 409 with existing transaction
•  QR payment — success path
•  QR payment — merchant inactive → 404
•  Disclosure — calculates fee, exchange rate, receive amount correctly
•  PISP circuit breaker — 3 failures → open → 502 (integration test, Phase 2)
•  Concurrent payment — balance race condition handled correctly (Phase 2)

Approval