Payout

📖 Overview

internal/api/v1/billing/services/payout.service.js exposes read-only endpoints that list payouts, retrieve detail records, and summarise balance transactions for Stripe connected accounts. It is used by the billing dashboard to display bank deposits, drill into individual payouts, and display aggregated fee/charge breakdowns.

Primary Controller: payout.controller.js

🔗 External Dependencies

• Stripe Payouts API – Lists and retrieves payouts.
• Stripe Balance Transactions API – Fetches transactions associated with a payout.
• Moment-Timezone – Converts ISO dates to Unix timestamps for Stripe filters.
• Stripe Config Utility – stripeConfig initialises the client with connected account tokens.

🔄 Data Flow

flowchart TD
    UI[Billing UI] -->|GET /payouts| Controller
    Controller --> Service
    Service -->|stripeAccount| Stripe
    Stripe --> Payouts
    Stripe --> BalanceTransactions

🧩 Functions

getPayouts({ startDate, endDate, firstPayoutId, lastPayoutId, limit, stripeBilling })

Retrieves paginated payout history.

1. Converts optional date filters into Unix seconds using moment.
2. Calls stripe.payouts.list with pagination cursors (starting_after, ending_before).
3. Maps Stripe payload into DTO (amount, created, status, bank info).
4. Returns { payouts, has_more, first_payout_id, last_payout_id }.

Edge Cases

• Handles empty results by returning null cursor fields.
• Wraps Stripe connection errors with custom helper for consistent messaging.

getPayout({ payoutId, stripeBilling })

Fetches a single payout with expanded destination and balance transaction.

• Normalises amount, fees, routing info, and currency into a UI-friendly object.
• Uses .toFixed(2) to ensure currency precision.

getTransactions({ payoutId, hasMore, firstTransactionId, lastTransactionId, limit, stripeBilling })

Paginates transactions tied to a payout.

1. Calls stripe.balanceTransactions.list with payout filter and pagination cursors.
2. Returns DTO with amount, type, net, and fee for each transaction.
3. Calculates first_transaction_id and last_transaction_id for subsequent calls.

getSummary({ payoutId, stripeBilling })

Aggregates balance transactions by type.

1. Streams transactions (auto-pagination) to avoid manual pagination loops.
2. Buckets by charge, refund, adjustment, transfer, topup, and stripe_fee.
3. Totals count, gross amount, fees, and net value per type.
4. Computes total as sum of net values.

🧪 Testing Notes

• Mock Stripe clients when unit testing to simulate pagination responses.
• Prefer integration tests that validate pagination cursors and currency formatting.

⚠️ Operational Considerations

• Controllers should cap limit to prevent loading excessive transaction history in a single call.
• Auto-pagination in getSummary iterates up to 100 records per page; consider additional guards if payouts exceed this volume.

🔗 Related Docs

• Billing Module Overview
• Overview
• Product