Payout Management

Source: internal/api/v1/store/Controllers/payout.js

Overview

The Payout controller provides read-only access to Stripe payout records for connected accounts. It enables merchants to track payout history and view detailed transaction breakdowns for each payout.

Key Capabilities

• List payouts with pagination and filtering
• Retrieve individual payout details
• Fetch all balance transactions for a payout
• Track payout status and amounts

---

MongoDB Collections

Collection	Operations	Purpose
_store.payout	Read	Payout tracking
_accounts	Read	Account/business info population

---

Service Methods

getPayouts

Lists all payouts for the connected account.

Endpoint: GET /store/payouts

Authorization: Requires payments_enabled = true

Query Parameters:

{
  page: number,
  limit: number,
  filter: object  // Optional: additional MongoDB filters
}

Response: Paginated payout list

Filtering:

{
  account: req.auth.account_id,
  connected_account: req.auth.account.stripe_connected_account
}

Populated Fields:

• Account business information (name, email, phone, address, social, website)

---

getPayout

Retrieves a single payout with all associated balance transactions.

Endpoint: GET /store/payouts/:id

Authorization: Requires payments_enabled = true

Response: Payout object with all_transactions array

Business Logic:

// Fetch payout from MongoDB
const payout = await Payout.findOne({
  _id: id,
  account: req.auth.account_id,
  connected_account: stripe_connected_account,
});

// Fetch ALL balance transactions from Stripe (paginated)
let has_more = true;
let transactions = [];
do {
  const trans = await stripe.balanceTransactions.list(
    {
      payout: payout.stripe_id,
      limit: 100,
      starting_after: transactions[transactions.length - 1]?.id,
    },
    { stripeAccount: connected_account },
  );

  transactions = transactions.concat(trans.data);
  has_more = trans.has_more;
} while (has_more);

payout.all_transactions = transactions;

Transaction Types: Includes charges, refunds, adjustments, application fees, etc.

---

Business Logic Flows

Payout Transaction Aggregation

graph TD
    A[Request Payout Details] --> B[Find Payout in MongoDB]
    B --> C{Found?}
    C -->|No| D[Return 404]
    C -->|Yes| E[Fetch Stripe Transactions]
    E --> F[Page 1: 100 transactions]
    F --> G{has_more?}
    G -->|Yes| H[Fetch Next Page]
    H --> G
    G -->|No| I[Return Payout + Transactions]

---

Edge Cases & Business Rules

1. Read-Only Operations

Payouts are managed entirely by Stripe's payout schedule. No create/update/delete operations available.

2. Balance Transaction Pagination

Payouts can contain thousands of transactions. The controller automatically fetches all pages:

let transactions = [];
do {
  const trans = await stripe.balanceTransactions.list({
    payout: payout_id,
    limit: 100,
    starting_after: last_transaction_id,
  });
  transactions = transactions.concat(trans.data);
} while (trans.has_more);

3. Connected Account Only

All payout operations require:

• payments_enabled = true
• Valid stripe_connected_account
• Account and connected_account must match

4. Payout Status

Stripe payout statuses:

• pending: Scheduled but not yet sent
• in_transit: Sent to bank, awaiting arrival
• paid: Successfully arrived at bank
• failed: Transfer failed
• canceled: Payout cancelled

5. Error Handling

Transaction fetch errors are logged but don't fail the request:

try {
  // Fetch transactions
} catch (err) {
  logger.error({
    initiator: 'internal/store/payouts',
    error: err,
    message: 'COULD NOT RETRIEVE TRANSACTIONS',
  });
}
// Continue without transactions

---

Transaction Breakdown

Balance transactions include:

Revenue:

• charge: Payment from customer
• payment: Alternative payment (not card-based)

Deductions:

• refund: Customer refunds
• adjustment: Manual adjustments
• application_fee: DashClicks platform fees
• stripe_fee: Stripe processing fees

Other:

• transfer: Transfers between accounts
• payout: The payout itself
• payout_failure: Failed payout

---

Related Documentation

• Account - External account management
• Reporting - Payout analytics
• Webhooks - Payout event synchronization