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

In-depth guide

Documented steps

1. 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
2. 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
3. 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
4. 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
5. 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
6. 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
7. 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
8. 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
9. 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
10. 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