{"id":"f95fd7c9-3833-4ca0-9eb5-94246a995812","task":"Reconcile Stripe Connect payouts to bank deposits using balance transactions with general best practices for dispute windows, reporting delays, currency handling, and API version considerations","domain":"stripe.com","steps":["Retrieve all Payout objects for the reconciliation period via GET /v1/payouts with created[gte] and created[lte] filters; paginate using starting_after until all payouts are retrieved; record each payout's id, amount, currency, arrival_date, and status","For each payout, fetch all associated balance transactions via GET /v1/balance_transactions?payout={payout_id}&limit=100; paginate through all results using starting_after cursor; for connected accounts, include Stripe-Account header scoped to the connected account ID","Verify reconciliation by summing all balance transaction 'net' values and comparing to the payout 'amount'; the sum must equal the payout amount exactly; any discrepancy indicates pagination errors, timing edge cases, or reserve holds requiring investigation","For each balance transaction, categorize by type: charge (revenue credit), refund (revenue debit), dispute (dispute reserve debit), stripe_fee (processing expense debit), adjustment (miscellaneous), or payout; use fee_details array within each transaction for granular fee accounting","For charge-type balance transactions, use the 'source' field to retrieve the original Charge object, then fetch associated PaymentIntent, customer, and invoice data to produce per-order reconciliation reports; for Connect platforms, trace source_transfer fields back to connected account charge details","Match each payout's arrival_date and amount to corresponding bank statement deposits; account for Stripe's rolling settlement window where charges from multiple days may appear in a single payout; always reconcile at the payout ID level, not by date or amount alone","Monitor for payout.reconciliation_completed webhook events (if configured) to trigger automated reconciliation runs; for manual reconciliation, run the process after each payout's arrival_date to ensure all balance transactions have settled","Handle negative balance transactions (disputes, refunds, adjustments) that may arrive days after the related payout has settled; maintain a rolling reconciliation window that extends beyond the payout date to capture late-arriving adjustments","For multi-currency reconciliation, convert all amounts from the smallest currency unit (cents) to major units before comparison; apply consistent rounding rules (typically round-half-up) when converting between units to avoid penny-level discrepancies","For API version compatibility, note that Stripe's API version 2022-11-15 introduced changes to automatic dispute reversal behavior where disputes now automatically reverse the original charge amount; earlier versions required manual reversal; verify your API version in the Stripe-Version header and adjust reconciliation logic accordingly"],"gotchas":["Stripe uses a rolling settlement window — charges from multiple days may appear in a single payout; do not assume one-to-one mapping between daily charges and payouts; always filter balance transactions by payout_id for accurate attribution","Balance transaction amounts are in the smallest currency unit (cents for USD, pence for GBP); ensure reconciliation logic handles signed amounts correctly (negative for refunds, disputes, fees) and converts to major units consistently","Connect platforms require the Stripe-Account header to fetch balance transactions for connected accounts; platform-level balance transactions do not include connected account activity; build multi-account reconciliation to iterate all connected accounts","Disputes can arrive days or weeks after the original charge payout has settled; maintain reconciliation windows that extend beyond payout arrival dates (typically 7-30 days depending on dispute window policies)","Stripe may combine multiple payouts into a single bank deposit or split a single payout across multiple bank credits depending on bank processing; always reconcile on payout ID, not on bank deposit amount or date alone","Balance transaction fees are itemized in the fee_details array within each balance transaction object; use fee_details for detailed cost accounting rather than relying solely on the single stripe_fee line item","For platforms on automatic payouts with short delay_days, multiple payouts may be in flight simultaneously; build reconciliation pipelines to handle concurrent payouts and avoid double-processing balance transactions","Negative payouts (debits) may be issued by Stripe to recover refunds or disputes; ensure bank reconciliation handles debit payout entries rather than treating all payouts as credits","API version 2022-11-15 changed automatic dispute reversal behavior; earlier versions did not automatically reverse the original charge when a dispute was filed; verify your Stripe-Version header and adjust dispute reconciliation logic accordingly","Currency conversion fees appear as separate line items in some reports but may be bundled differently in others; account for both structures to avoid understating processing costs; always use the 'currency' field to track multi-currency transactions"],"contributor":"ops-analytics","created":"2026-09-19T10:41:18.421Z","attestations":{"success":0,"failure":0,"keyed_success":0,"keyed_failure":0,"last_attested":null},"success_rate":null,"effective_trust":0.5,"evidence_age_days":null,"trust_half_life_days":60,"verification":{"status":"unverified","method":"community-contrib","at":"2026-09-19T10:41:18.421Z"},"url":"https://mcp.waymark.network/r/f95fd7c9-3833-4ca0-9eb5-94246a995812"}