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
| Stage | Object | What it records |
|---|---|---|
| 1 | PaymentIntent | The amount the customer tried to pay, and whether the attempt succeeded. |
| 2 | Charge | The payment method that moved the money, and the captured amount. |
| 3 | BalanceTransaction | The fee for the movement, and the net amount that hit the balance. |
| 4 | Balance | How much the account can pay out right now. |
| 5 | Payout | What 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.
| Status | Meaning | Next step |
|---|---|---|
requires_payment_method | No usable payment method yet. | Attach a method and confirm. |
requires_confirmation | Ready to confirm. | Confirm the intent. |
requires_action | The issuer needs the customer to authenticate. | Complete the challenge in the client. |
processing | The network is still working. | Wait for a webhook. |
requires_capture | Authorized but not captured. | Capture within the authorization window. |
succeeded | Money moved. | Fulfill the order. |
canceled | The 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:
| Array | Meaning |
|---|---|
available | Funds you can pay out or transfer now. |
pending | Funds 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.
| Stage | Object | Amount | Notes |
|---|---|---|---|
| 1 | PaymentIntent pi_... | 2120 | Created with amount=2120, currency=usd. |
| 2 | Charge ch_... | 2120 | The issuer approves the charge. |
| 3 | BalanceTransaction txn_... | amount: 2120 | fee: 91, net: 2029, type: charge. |
| 4 | Balance | available: 2029 | Funds appear after the settlement delay. |
| 5 | Payout po_... | 2029 | Paid 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_cardorstolen_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 type | Balance transaction | Effect on balance |
|---|---|---|
| Full | amount: -2120, fee: 0, net: -2120 | Removes the whole charge. |
| Partial | amount: -1000, fee: 0, net: -1000 | Removes part of the charge. |
| Two or more partial refunds | One transaction per refund | Each 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
- Authentication and key management to send the first request.
- Idempotent requests to retry a charge without duplicating it.
- Errors and retries to handle declines, rate limits, and outages.
- Retrieve a balance transaction for the full attribute list.