Appendix B · Glossary of objects and flags
The Platform Refund Ledger · 5 min read
Every Stripe object, parameter, field, balance-transaction type, and event used in this book. Names are exact; citations point to the page that defines each. Cross-references give the chapter with the fullest treatment.
adjustment — Balance transaction type for movements outside the normal charge/refund flow; disputes debit and credit through adjustments whose source is the dispute object. (docs.stripe.com/reports/balance-transaction-types · ch. 5, 7)
amount_refunded — Field on Charge and ApplicationFee: running total refunded so far. (docs.stripe.com/api/charges/object · ch. 1, 4)
amount_reversed — Field on Transfer: running total reversed so far; transfer.amount − amount_reversed is the ceiling on any further reversal. (docs.stripe.com/api/transfers/object · ch. 3)
ApplicationFee — Object representing the platform's cut of a direct or destination charge: amount, amount_refunded, refunded, charge. Exists only where pricing uses application_fee_amount. (docs.stripe.com/api/application_fees/object · ch. 1, 4)
application_fee.refunded — Event fired when an application fee is refunded. (docs.stripe.com/api/events/types · ch. 4, App. C)
application_fee_amount — PaymentIntent / Checkout Session parameter setting the platform's fee on a charge; on destination charges the fee is withheld from the transfer, so transfer.amount is the charge less the fee. (docs.stripe.com/connect/destination-charges · ch. 1)
application_fee (balance transaction type) — Platform earnings from Connect fees, credited to the platform balance. (docs.stripe.com/reports/balance-transaction-types · ch. 7)
application_fee_refund (balance transaction type) — "Platform fees that you have returned to your connected accounts." (docs.stripe.com/reports/balance-transaction-types · ch. 4, 7)
available_on — Balance transaction field: the date funds leave pending and become available; settlement timing lives here. (docs.stripe.com/api/balance_transactions/object · ch. 7, 9)
BalanceTransaction — The immutable record of one movement into or out of an account balance: type, amount, fee, net, status (pending/available), available_on, source. The ground truth this book reconciles against. (docs.stripe.com/api/balance_transactions/object · ch. 7)
Charge — One successful payment. Fields used throughout: amount, application_fee_amount, transfer_data, refunded, amount_refunded, on_behalf_of. (docs.stripe.com/api/charges/object · ch. 1)
charge.refunded — Event fired when a charge is refunded; the input to the chapter 8 audit. (docs.stripe.com/api/events/types · ch. 8, App. C)
charge.dispute.created / charge.dispute.closed — Events marking the start and resolution of a dispute; closed carries the final status (won or lost). (docs.stripe.com/api/events/types · ch. 5, App. C)
connect_collection_transfer — Balance transaction type: after a connected account stays negative for 180 days, Stripe transfers platform funds to zero it out. (docs.stripe.com/connect/account-balances · ch. 3)
controller.losses.payments — Accounts v1 field (stripe or application) naming who is responsible for connected-account negative balances; v2 equivalent: defaults.responsibilities.losses_collector. (docs.stripe.com/connect/account-balances · ch. 3, 5)
debit_negative_balances — Balance setting that lets Stripe debit a connected account's external bank account to clear a negative balance (never their debit card). (docs.stripe.com/connect/account-balances · ch. 3, 5)
Destination charge — Charge created on the platform with transfer_data[destination]; a transfer to the connected account follows capture automatically. Refunds default to the destination keeping transferred funds. (docs.stripe.com/connect/destination-charges · ch. 1, 2)
Direct charge — Charge created on a connected account using the Stripe-Account header; funds settle in the connected account's balance; objects live there too. (docs.stripe.com/connect/direct-charges · ch. 1, 2)
Dispute — Cardholder-initiated challenge: amount, status (needs_response, under_review, won, lost, among others), evidence, evidence_details, balance_transactions. (docs.stripe.com/api/disputes/object · ch. 5)
FeeRefund — Object ("object": "fee_refund") created by refunding an application fee, standalone or via refund_application_fee: amount, fee, balance_transaction. (docs.stripe.com/api/fee_refunds/create · ch. 4)
on_behalf_of — Parameter making a connected account the settlement merchant of a payment; changes statement descriptor, settlement country and currency, and fee structure — but not dispute liability on destination charges. (docs.stripe.com/connect/destination-charges · docs.stripe.com/connect/disputes · ch. 1, 5)
Payout — Movement of funds from a Stripe balance to a bank account: amount, status, arrival_date. Ledger companions: payout, payout_cancel, payout_failure. (docs.stripe.com/api/payouts/object · ch. 7, 9)
reason — Optional Refund parameter: duplicate, fraudulent, or requested_by_customer. (docs.stripe.com/api/refunds/create · ch. 2, 10)
refund_application_fee — Refund parameter (and Transfer-reversal parameter): returns the application fee — fully on a full refund/reversal, otherwise proportionally. Defaults off everywhere; usable only by the application that created the charge; on destination charges must be paired with reversal. (docs.stripe.com/api/refunds/create · docs.stripe.com/api/transfer_reversals/create · ch. 2–6)
Refunds API — POST /v1/refunds; partial refunds allowed repeatedly until a charge is exhausted; errors once fully refunded. Response carries balance_transaction, transfer_reversal, source_transfer_reversal. (docs.stripe.com/api/refunds/create · ch. 2)
reporting_category — Balance transaction field Stripe recommends over raw type for accounting classification. (docs.stripe.com/reports/balance-transaction-types · ch. 7)
reserve_transaction — Balance transaction type: funds held against the platform balance while a connected account it is responsible for sits negative. (docs.stripe.com/connect/account-balances · ch. 3)
Separate charges and transfers — Pattern with a platform charge plus explicit Transfer objects; refunds touch nothing automatically; reconciliation linkage is the platform's own job (source_transaction / transfer_group help). (docs.stripe.com/connect/separate-charges-and-transfers · ch. 1–3)
source_transaction — Transfer parameter tying it to a specific charge; funds become available to the destination only when the source charge's funds do. (docs.stripe.com/connect/separate-charges-and-transfers · ch. 1, 3)
stripe_fee — Balance transaction type for Stripe's own software/service fees, including Connect. (docs.stripe.com/reports/balance-transaction-types · ch. 7)
Stripe-Account header — Authentication header that creates or reads objects on a connected account; its presence defines the direct-charge pattern. (docs.stripe.com/connect/authentication · ch. 1)
Transfer — Funds moved from the platform balance to a connected account: amount, amount_reversed, destination, source_transaction, reversals. (docs.stripe.com/api/transfers/object · ch. 1, 3)
transfer_data[destination] / transfer_data[amount] — PaymentIntent parameters creating a destination charge and optionally fixing the transferred amount (the alternative pricing shape). (docs.stripe.com/connect/destination-charges · ch. 1)
transfer_group — Free-form string associating charges and transfers you create separately; identifies relationships without affecting behavior. (docs.stripe.com/connect/separate-charges-and-transfers · ch. 1)
transfer_refund (balance transaction type) — Reversed transfers: "reversals add to your platform's balance and subtract from the connected account's balance." (docs.stripe.com/reports/balance-transaction-types · ch. 7)
TransferReversal — Object created by POST /v1/transfers/{id}/reversals: amount up to the unreversed remainder, optional proportional refund_application_fee, own balance_transaction, and source_refund / destination_payment_refund links when motivated by a refund. (docs.stripe.com/api/transfer_reversals/create · ch. 3)