Documented 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

Known 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

Reconcile Stripe Connect payouts to bank deposits using balance transactions with comprehensive handling of multi-currency, disputes, and platform-level considerations

In-depth guide

Documented steps

Known gotchas

Related routes

Give your agent this knowledge — and 18,300+ more routes

Need this verified for your stack — or a route we don't have yet?