Stripe Money Management

Manage payouts, refunds, disputes, fraud prevention, and balance operations.

Rule Priority Table

Priority	Rule	Impact	Summary
1	currency-use-zero-decimal-correctly	HIGH	Handle zero-decimal currencies (JPY, KRW) without 100x overcharge
2	currency-validate-minimums	HIGH	Validate minimum charge amounts per currency before API call
3	dispute-respond-within-deadline	HIGH	Monitor dispute webhooks and respond before evidence deadline
4	dispute-submit-all-evidence	HIGH	Submit all available evidence fields to maximize win rate
5	dispute-use-early-fraud-warnings	HIGH	Proactively refund on EFW to prevent chargebacks
6	dispute-collect-customer-data	HIGH	Capture IP, email, receipt at purchase time for future disputes
7	refund-handle-failures	HIGH	Implement webhook handler for refund failures
8	refund-provide-reason	MEDIUM	Always specify refund reason for analytics and Radar learning
9	radar-provide-shipping-data	HIGH	Include shipping address for better fraud ML scoring
10	radar-require-3ds-elevated	HIGH	Request 3DS for elevated risk via Radar rules
11	radar-use-radar-sessions	HIGH	Implement Radar Sessions for device fingerprinting
12	payout-use-manual-mode	HIGH	Use manual payouts for precise cash flow control
13	payout-check-balance-first	HIGH	Check available balance before creating payout
14	balance-handle-negative	HIGH	Monitor and handle negative balance scenarios
15	balance-reconcile-daily	MEDIUM	Implement daily balance reconciliation

Capability Decision Tree

What money management task?
|
+-- Sending funds to bank accounts?
|   -> references/payouts.md
|
+-- Returning money to customers?
|   -> references/refunds.md
|
+-- Responding to chargebacks?
|   -> references/disputes.md
|
+-- Preventing fraud?
|   -> references/radar.md
|
+-- Understanding your balance?
|   -> references/balance.md
|
+-- Multi-currency operations?
|   -> references/multi-currency.md

Quick Reference

Payouts

// Check available balance, then create manual payout
const balance = await stripe.balance.retrieve();
const available = balance.available.find((b) => b.currency === 'usd')?.amount ?? 0;

const payout = await stripe.payouts.create({
  amount: 250000, // $2,500
  currency: 'usd',
  method: 'standard', // or 'instant'
  description: 'Weekly payout',
});

Refunds

// Full refund with reason
const refund = await stripe.refunds.create({
  payment_intent: 'pi_xxx',
  reason: 'requested_by_customer',
});

// Partial refund
const partialRefund = await stripe.refunds.create({
  payment_intent: 'pi_xxx',
  amount: 500, // $5.00
  reason: 'requested_by_customer',
});

Dispute Response

// Submit evidence (use draft mode first, then submit)
await stripe.disputes.update('dp_xxx', {
  evidence: {
    customer_name: 'Jenny Rosen',
    customer_email_address: 'jenny@example.com',
    customer_purchase_ip: '192.168.1.1',
    product_description: 'Pro subscription plan',
    receipt: 'file_xxx',
    shipping_tracking_number: '1Z999AA1012345678',
  },
  submit: true,
});

Radar Rules

# Require 3DS for elevated risk
Request 3D Secure if :risk_level: = 'elevated'

# Block high-risk prepaid cards
Block if :card_funding: = 'prepaid' and :amount_in_usd: > 50000

# Block suspicious countries
Block if :card_country: in ('XX', 'YY')

Zero-Decimal Currencies

// JPY: amount IS the actual charge (no cents)
await stripe.paymentIntents.create({ amount: 3000, currency: 'jpy' }); // 3,000 JPY
// USD: amount is in cents
await stripe.paymentIntents.create({ amount: 1999, currency: 'usd' }); // $19.99

Dispute Lifecycle

needs_response (7-21 days) -> under_review (60-75 days) -> won / lost
                            -> warning_closed (inquiry resolved)

Critical Webhooks

Event	Action
payout.paid	Confirm payout deposited
payout.failed	Alert, check bank details, retry
charge.refunded	Update order status
charge.refund.updated	Track refund failure, issue alternative
charge.dispute.created	Begin evidence collection immediately
charge.dispute.closed	Update dispute outcome, track win/loss
radar.early_fraud_warning.created	Proactive refund to prevent dispute
review.opened / review.closed	Manual Radar review actions
balance.available	Monitor for negative balance

References

• references/payouts.md - Standard, instant, manual payouts, schedules, connected account payouts, failures, reversals
• references/refunds.md - Full, partial, by payment method, refund failures, cancellation, balance requirements
• references/disputes.md - Dispute lifecycle, evidence fields by reason, Visa CE 3.0, early fraud warnings, prevention
• references/radar.md - ML fraud scoring, rules engine, velocity checks, Radar Sessions, manual reviews
• references/balance.md - Available vs pending, balance transactions, fee details, reconciliation, negative balances
• references/multi-currency.md - Presentment vs settlement currency, zero-decimal, exchange rates, minimum amounts