The Platform Refund Ledger

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)

  1. Classify recent charges by pattern from the data: charge.transfer set → destination; created under Stripe-Account → direct; neither → separate.
  2. Read transfer.amount on destination charges and confirm it equals the charge less the application fee; a different figure means transfer_data[amount] pricing and no fee object — never infer it.
  3. Confirm whether your flows create ApplicationFee objects at all.
  4. 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)

  1. Record what reverse_transfer and refund_application_fee are set to on every code path that issues refunds, including Dashboard-created ones.
  2. Sample five real refunds and confirm a transfer_reversal id exists wherever policy says one should.
  3. Verify someone consciously chose direct-charge fee behavior rather than inheriting keep-by-default.
  4. For separate-pattern flows, locate the "reduce a future transfer" logic — or record that it does not exist.
  5. Fill chapter 6's defaults matrix with last month's refund counts per cell, and map each refund path to its cell.
  6. Compute effective take rates on partially refunded charges and look for silent increases.
  7. Confirm no path passes refund_application_fee: true on a destination charge without also reversing the transfer.
  8. 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)

  1. Compare amount against amount_reversed on recent transfers; list every nonzero gap with its cause.
  2. Record your negative-balance responsibility field (controller.losses.payments or v2 equivalent), date-stamped.
  3. Decide deliberately whether debit_negative_balances is enabled on connected accounts' balance settings.
  4. Maintain the list of connected accounts with negative available balances, aged by last transaction date.
  5. Reconcile every reserve_transaction and connect_collection_transfer line to a specific account.

4 · Application fees (ch. 4)

  1. Count collected fees sitting on charges with refunds while amount_refunded = 0 on the fee itself.
  2. Compute expected proportional fee shares — round(refunded ÷ charged × fee) — against amounts actually returned.
  3. Verify fee behavior derives from refund reason rather than uniform defaults.
  4. Record any manually issued fee refunds somewhere besides Stripe's audit trail.
  5. Check seller terms describe the fee behavior the code implements.

5 · Disputes (ch. 5)

  1. Keep a disputes register: pattern, transfer existence, amount reversed before closure.
  2. Total recoverable = Σ(transfer.amount − amount_reversed) over closed-lost disputes.
  3. Confirm who responds to disputes per pattern and where deadlines are monitored.
  4. Decide early-reversal-on-created versus wait-for-closed against measured win rate.
  5. Note how debit_negative_balances interacts with dispute recovery in your seller communications.

6 · Reading the ledger (ch. 7)

  1. Reproduce one full day's three checks by hand before automating anything.
  2. Group exports by type, then by source; confirm every destination transfer equals its charge less the fee, and that an ApplicationFee object exists wherever you expect to refund one.
  3. Match every transfer_refund line to the refund that motivated it.
  4. Match every dispute-sourced adjustment line to the disputes register.
  5. Compare pending versus available totals at close of day.

7 · The recurring audit (ch. 8)

  1. Run the five-step audit over a rolling 90-day window.
  2. Total missing amounts by leak signature, not just overall.
  3. Cross-check findings against ledger evidence before acting.
  4. Document the clamp rule and tolerance inside the spreadsheet.
  5. Date-stamp every export; re-verify live state immediately before any correction.

8 · Month-end close (ch. 9)

  1. Match every payout to its full transaction-set sum (Template T1).
  2. Keep the type-to-account map written, versioned, and current (Template T2).
  3. Compute the close identity — charges − refunds − Stripe fees ± adjustments = payouts ± change held — and log residuals monthly.
  4. Post refunds and fee refunds to named contra accounts, never netted into revenue.
  5. Decompose closing balance into available/pending and platform/seller shares.

9 · Policy on purpose (ch. 10)

  1. Write down the four dials as they behave today, sourced from code.
  2. Attach a reason to every refund path; count the paths without one.
  3. Price the dial choice: compute last quarter under all-reverse and all-absorb counterfactuals.
  4. Set and document a recovery floor with its justifying arithmetic.
  5. Diff terms, flag logic, and support macros quarterly; assign each divergence an owner.
  6. Keep the quarterly diff on a named person's calendar.