Appendix A · The master checklist
The Platform Refund Ledger · 4 min read
Every chapter closed with items to check on your own platform. They are consolidated here in working order — grouped by theme, tagged by chapter of origin. Work top to bottom once, then keep sections 4, 7, and 8 on a calendar.
1 · Know which money graph you run (ch. 1)
- Classify recent charges by pattern from the data:
charge.transferset → destination; created underStripe-Account→ direct; neither → separate. - Read
transfer.amounton destination charges and confirm it equals the charge less the application fee; a different figure meanstransfer_data[amount]pricing and no fee object — never infer it. - Confirm whether your flows create
ApplicationFeeobjects at all. - If multiple patterns run side by side, verify every refund path branches on the charge, not on an assumption.
2 · Refund paths and their flags (ch. 2, ch. 6)
- Record what
reverse_transferandrefund_application_feeare set to on every code path that issues refunds, including Dashboard-created ones. - Sample five real refunds and confirm a
transfer_reversalid exists wherever policy says one should. - Verify someone consciously chose direct-charge fee behavior rather than inheriting keep-by-default.
- For separate-pattern flows, locate the "reduce a future transfer" logic — or record that it does not exist.
- Fill chapter 6's defaults matrix with last month's refund counts per cell, and map each refund path to its cell.
- Compute effective take rates on partially refunded charges and look for silent increases.
- Confirm no path passes
refund_application_fee: trueon a destination charge without also reversing the transfer. - Sum per-charge expected versus actual reversals with a two-minor-unit tolerance; list every charge outside it.
3 · Transfers, reversals, and balances (ch. 3)
- Compare
amountagainstamount_reversedon recent transfers; list every nonzero gap with its cause. - Record your negative-balance responsibility field (
controller.losses.paymentsor v2 equivalent), date-stamped. - Decide deliberately whether
debit_negative_balancesis enabled on connected accounts' balance settings. - Maintain the list of connected accounts with negative available balances, aged by last transaction date.
- Reconcile every
reserve_transactionandconnect_collection_transferline to a specific account.
4 · Application fees (ch. 4)
- Count collected fees sitting on charges with refunds while
amount_refunded = 0on the fee itself. - Compute expected proportional fee shares — round(refunded ÷ charged × fee) — against amounts actually returned.
- Verify fee behavior derives from refund reason rather than uniform defaults.
- Record any manually issued fee refunds somewhere besides Stripe's audit trail.
- Check seller terms describe the fee behavior the code implements.
5 · Disputes (ch. 5)
- Keep a disputes register: pattern, transfer existence, amount reversed before closure.
- Total recoverable = Σ(transfer.amount − amount_reversed) over closed-lost disputes.
- Confirm who responds to disputes per pattern and where deadlines are monitored.
- Decide early-reversal-on-created versus wait-for-closed against measured win rate.
- Note how
debit_negative_balancesinteracts with dispute recovery in your seller communications.
6 · Reading the ledger (ch. 7)
- Reproduce one full day's three checks by hand before automating anything.
- Group exports by
type, then bysource; confirm every destinationtransferequals its charge less the fee, and that anApplicationFeeobject exists wherever you expect to refund one. - Match every
transfer_refundline to the refund that motivated it. - Match every dispute-sourced
adjustmentline to the disputes register. - Compare pending versus available totals at close of day.
7 · The recurring audit (ch. 8)
- Run the five-step audit over a rolling 90-day window.
- Total missing amounts by leak signature, not just overall.
- Cross-check findings against ledger evidence before acting.
- Document the clamp rule and tolerance inside the spreadsheet.
- Date-stamp every export; re-verify live state immediately before any correction.
8 · Month-end close (ch. 9)
- Match every payout to its full transaction-set sum (Template T1).
- Keep the type-to-account map written, versioned, and current (Template T2).
- Compute the close identity — charges − refunds − Stripe fees ± adjustments = payouts ± change held — and log residuals monthly.
- Post refunds and fee refunds to named contra accounts, never netted into revenue.
- Decompose closing balance into available/pending and platform/seller shares.
9 · Policy on purpose (ch. 10)
- Write down the four dials as they behave today, sourced from code.
- Attach a reason to every refund path; count the paths without one.
- Price the dial choice: compute last quarter under all-reverse and all-absorb counterfactuals.
- Set and document a recovery floor with its justifying arithmetic.
- Diff terms, flag logic, and support macros quarterly; assign each divergence an owner.
- Keep the quarterly diff on a named person's calendar.