メインコンテンツまでスキップ

How money moves through Stripe

A payment touches five objects before it settles in your bank account. Each object records one part of the journey. Read them in order and you can trace any payment from the first attempt to the final payout.

Stages of a payment​

StageObjectWhat it records
1PaymentIntentThe amount the customer tried to pay, and whether the attempt succeeded.
2ChargeThe payment method that moved the money, and the captured amount.
3BalanceTransactionThe fee for the movement, and the net amount that hit the balance.
4BalanceHow much the account can pay out right now.
5PayoutWhat left the account for the bank, and when.

The stages run in order. The objects stay linked, so you can open any stage later and walk back to the original intent.

Stage 1: The intent records the attempt​

A PaymentIntent holds the amount, the currency, and a status. It persists after an unsuccessful attempt, so a customer can retry with another card against the same intent.

StatusMeaningNext step
requires_payment_methodNo usable payment method yet.Attach a method and confirm.
requires_confirmationReady to confirm.Confirm the intent.
requires_actionThe issuer needs the customer to authenticate.Complete the challenge in the client.
processingThe network is still working.Wait for a webhook.
requires_captureAuthorized but not captured.Capture within the authorization window.
succeededMoney moved.Fulfill the order.
canceledThe payment failed permanently.Create a new intent to retry.
警告

The client reports a result, but the server decides. Treat succeeded from the client as a hint. Confirm the state with a webhook or a retrieve call before you fulfill the order.

Stage 2: The charge moves the money​

Confirmation creates a Charge. The charge records the payment method, the amount captured, and the outcome from the card network. One successful intent produces one charge. A charge never changes after it settles.

Authorization and capture can happen together or apart. Set capture_method to manual to authorize now and capture later. A marketplace that charges after fulfillment needs this split. Uncaptured authorizations expire, so capture before the window closes.

Stage 3: The balance transaction records the cost​

Each movement produces a BalanceTransaction. The record lists three amounts:

  • amount. The full movement in the smallest currency unit.
  • fee. What Stripe charged for the movement.
  • net. The amount that actually changes the balance.

A refund adds a second balance transaction with a negative amount. Payouts produce one as well. This ledger is the only reliable source for reconciliation, because the charge record never shows fees.

Stage 4: The balance holds settled funds​

The Balance object splits funds into two arrays:

ArrayMeaning
availableFunds you can pay out or transfer now.
pendingFunds from charges that haven't settled yet.

A third field, refund_and_dispute_prefunding, keeps money reserved for future refunds, disputes, or a negative balance. Each array lists one entry per currency.

注記

The balance shows what you can pay out. It doesn't show what you earned. For revenue reporting, sum the net values from balance transactions over the period.

Stage 5: The payout leaves the account​

A Payout moves available funds to the bank account on file. Your payout schedule sets the timing: daily, weekly, monthly, or manual. Settlement delays vary by country and by the payment method that funded the charge.

A payout covers many charges at once. To reconcile one payout to its source charges, list the balance transactions with payout={payout_id} as the filter.

Worked example​

A customer buys a monthly plan for $21.20. The platform charges the standard card rate of 2.9% plus $0.30.

StageObjectAmountNotes
1PaymentIntent pi_...2120Created with amount=2120, currency=usd.
2Charge ch_...2120The issuer approves the charge.
3BalanceTransaction txn_...amount: 2120fee: 91, net: 2029, type: charge.
4Balanceavailable: 2029Funds appear after the settlement delay.
5Payout po_...2029Paid out with other settled charges.

The fee is 91 cents. A 2.9% rate takes 61.48 cents, the fixed fee adds 30 cents, and the total rounds to 91. The account gains $20.29, not $21.20.

What changes the path​

A declined payment​

A decline ends the attempt without a charge. The intent moves to requires_payment_method and keeps its amount. Retrying with the same intent avoids a duplicate order.

Declines fall into two groups:

  • Hard declines. The issuer rejects the card outright, such as lost_card or stolen_card. Don't retry.
  • Soft declines. The issuer rejects this attempt, such as insufficient_funds. A later retry can succeed.

A refund​

A refund creates a Refund object and a second balance transaction with a negative amount. The refund doesn't return the original processing fee.

Refund typeBalance transactionEffect on balance
Fullamount: -2120, fee: 0, net: -2120Removes the whole charge.
Partialamount: -1000, fee: 0, net: -1000Removes part of the charge.
Two or more partial refundsOne transaction per refundEach refund is its own ledger entry.

The account still pays the original 91-cent fee. A full refund therefore costs $21.20 in returned funds plus that fee.

A dispute​

A chargeback reverses the charge and adds a dispute fee. Stripe withdraws the disputed amount from available when the issuer opens the case. It then charges a fixed dispute fee of $15 in the United States.

A dispute adds three balance transactions. One withdraws the amount, one charges the fee, and one restores the amount if the bank rules in your favor. Track the case through the Dispute object rather than the balance alone.

A partial capture​

A manual capture can take less than the authorized amount. A $50 hold captured at $40 produces a charge for 4000 and releases the remaining $10 back to the customer. One balance transaction records the $40.

Where to go next​