Stripe Charge

The three fields people misread, and what they actually say

Almost every charge misreading comes from three boolean-looking fields that mean narrower things than they appear to.

**`paid` does not mean captured.** Stripe documents it as "`true` if the charge succeeded, or was successfully authorized for later capture." That second clause is doing a lot of work. On a deposit taken with a manual capture, `paid` is already true while the money is still an [authorization hold](/glossary/stripe-authorization-hold) and nothing has settled. If you filter a Stripe export on `paid` and treat the result as revenue, you will pull in holds that may never be captured.

**`captured` is a state, not a confirmation.** Stripe describes it as: "If the charge was created without capturing, this Boolean represents whether it is still uncaptured or has since been captured." The amount actually taken lives elsewhere, in `amount_captured`, which Stripe documents as the "Amount in the smallest currency unit captured (can be less than the amount attribute on the charge if a partial capture was made)." So on a partial capture, `amount` and `amount_captured` disagree, and `amount_captured` is the one your books care about. [Stripe partial capture in QuickBooks](/blog/stripe-partial-capture-quickbooks) covers that case in full.

**`refunded` is the trap.** Stripe is blunt about it: "Whether the charge has been fully refunded. If the charge is only partially refunded, this attribute will still be false." A charge with half its value returned to the customer reports `refunded: false`. The partial activity is visible only in `amount_refunded`, documented as the "Amount in the smallest currency unit refunded (can be less than the amount attribute on the charge if a partial refund was issued)." Any reconciliation that reads `refunded` as a general question about whether money went back to the customer will silently miss every partial refund you have ever issued.

The balance transaction is what makes a charge reconcilable

A charge tells you what was attempted and what the result was called. It does not tell you what hit your balance. For that there is one field.

Stripe documents `balance_transaction` as the "ID of the balance transaction that describes the impact of this charge on your account balance (not including refunds or disputes)." That parenthetical matters: the charge points at its own effect on the balance and nothing else. Refunds and disputes create their own separate balance transactions rather than editing this one.

This is why the balance transaction rather than the charge is the reconcilable unit. The charge carries the gross intent. The balance transaction carries the fee, the net, and the date the funds become available. When your QuickBooks total and your Stripe payout disagree, the answer is almost always in the balance transactions, not in the charges.

The mirror image is worth knowing too. A failed bank debit gets a `failure_balance_transaction`, documented as the "ID of the balance transaction that describes the reversal of the balance on your account due to payment failure." A reversal can only exist because something entered the balance first, which is precisely why a failed ACH payment leaves a trail in your books and a declined card leaves none.

When a charge fails, and why nothing reaches your books

A failed charge is still a charge. It has an id, an amount, a customer and a timestamp, and it sits in your Dashboard looking very much like a sale. What it does not have is any effect on your balance.

Three fields explain it. `failure_code` is the "Error code explaining reason for charge failure if available". `failure_message` is the human sentence version, documented as the "Message to user further explaining reason for charge failure if available". And `outcome` carries the assessment, documented as "Details about whether the payment was accepted, and why."

Because a failed charge produces no balance transaction, it produces no accounting record either. That is correct behavior rather than a gap in your sync, though it does not feel that way the first time you notice Stripe showing activity your books do not. [Why a declined Stripe payment never reaches QuickBooks](/blog/stripe-declined-payment-quickbooks) works through the four different things people call a failed payment and how each one books.

One more field belongs here. `disputed` is documented simply as "Whether the charge has been disputed", and a dispute is its own machinery with its own balance transactions rather than an edit to the original charge.

What the charge remembers about how it was paid

A charge carries a snapshot of the instrument used, not just a pointer to it. Stripe documents `payment_method_details` as "Details about the payment method at the time of the transaction."

The phrase "at the time of the transaction" is the useful part. Detaching a saved card or replacing an expired one does not rewrite what an existing charge records, because the brand, the last four and the funding type were copied onto the charge on the day of the sale. When you reconcile something from four months ago, that detail is trustworthy on its own terms. The [Stripe PaymentMethod](/glossary/stripe-payment-method) entry covers the instrument itself and why its type predicts settlement timing and fee shape.