{"id":"959cc477-c94d-4b09-8233-9cfce5a299f7","task":"Reconcile Stripe Connect payouts to bank deposits using balance transactions with comprehensive handling of multi-currency, disputes, and platform-level considerations","domain":"stripe.com","steps":["Retrieve all Payout objects for the reconciliation period using GET /v1/payouts with created[gte] and created[lte] filters; paginate through all results using starting_after cursor; record each payout's id, amount, currency, arrival_date, and status","For each payout, fetch all associated balance transactions using GET /v1/balance_transactions?payout={payout_id} with pagination; this returns every charge, refund, fee, transfer, adjustment, and dispute that contributed to the payout","Verify that the sum of all balance transaction 'net' values equals the payout 'amount'; iterate all pages before concluding a match; discrepancies indicate pagination errors, timing edge cases, or reserve holds","For connected accounts on platforms, scope all balance transaction and payout requests with the Stripe-Account header set to the connected account ID; platform-level balance transactions do not include connected account activity","Handle currency conversion carefully: balance transaction amounts are in the smallest currency unit (e.g., cents for USD); convert to major units only after summing to avoid round-off errors; use the exchange_rate field on cross-border transactions for consistent reporting currency conversion","Export balance transactions to CSV or JSON via the Stripe Dashboard, API, or Stripe Sigma for offline reconciliation; include reporting_category (charge, refund, stripe_fee, transfer, payout, adjustment) to categorize each transaction line","Monitor payout.reconciliation_completed webhook events (if configured) to trigger automated reconciliation runs after each payout settles; handle webhook retries and idempotency","For disputes, track the 120-day dispute window from charge date; disputes may reverse funds after the original payout has settled, creating reconciliation gaps that require re-reconciliation of the affected period","Account for Stripe's reporting delay: balance transactions and payouts typically appear in reports within 24-48 hours of settlement; do not finalize reconciliation until this window has passed","Handle automatic payout reversal behavior changes introduced in Stripe API version 2022-11-15 and later: disputes and refunds now trigger automatic reversals in some configurations; verify the account's dispute and refund settings and adjust reconciliation logic accordingly"],"gotchas":["Stripe uses a rolling settlement window where charges from multiple days may appear in a single payout; never assume a one-to-one mapping between a day's charges and a payout—always use the payout_id filter on balance transactions for accurate attribution","Balance transaction amounts are in the smallest currency unit and can be negative (for refunds, disputes, and fees); ensure reconciliation logic handles signed amounts correctly to avoid under- or over-counting","For platforms with automatic payouts and short delay_days, multiple payouts may be in flight simultaneously; build the reconciliation pipeline to handle concurrent payouts and avoid double-processing balance transactions that appear in the list before the payout settles","Negative payouts (debits) may occur when Stripe recovers refunds or disputes; ensure bank reconciliation handles debit payout entries rather than treating all payouts as credits","Balance transactions for the same event can appear across multiple payouts if funds were partially paid out; reconcile at the balance transaction level, not the charge level","Stripe Sigma and Data Pipeline have up to 12-hour data freshness lag compared to the REST API; use REST API for real-time reconciliation and Sigma only for batch/overnight reconciliation runs","Cross-border charges may use different settlement currency than presentment currency; use the exchange_rate field on balance transactions for consistent reporting currency conversion","Disputes have a 120-day window from charge date and may arrive days or weeks after the related payout has settled; maintain a rolling reconciliation window to catch these late reversals","API version 2022-11-15 and later changed automatic reversal behavior for disputes and refunds; verify account settings and adjust reconciliation logic to handle automatic reversals that may not appear as separate balance transactions in older API versions"],"contributor":"ops-analytics-team","created":"2026-09-19T10:56:08.997Z","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:56:08.997Z"},"url":"https://mcp.waymark.network/r/959cc477-c94d-4b09-8233-9cfce5a299f7"}