payments-fees-flow

name	payments-fees-flow
description	Use when working on ERTZU Stripe integration, payment intent creation, manual capture, fee logic, refunds, checkout, bid authorization, or payout assumptions.

Payments Fees Flow

When To Use

Use this skill for src/app/api/stripe/route.ts, buy-now checkout, bid checkout, bid acceptance, order payment status, fees, refunds, webhooks, payout logic, and payment-related schema fields.

ERTZU-Specific Instructions

• Buyers should authorize payment before a bid or buy-now completes.
• A bid should only be charged when a seller accepts and the flow reaches the correct capture point.
• Buy-now should charge the buyer for the server-selected lowest matching ask.
• Seller payout should not occur until ERTZU has received and verified the bottle.
• ERTZU fees, shipping charges, refunds, disputes, and payout timing must be explicit before production.

Files And Areas To Inspect

• src/app/api/stripe/route.ts
• src/app/buy/page.tsx
• src/app/bid/checkout/page.tsx
• src/app/notifications/page.tsx
• src/app/checkout/[id]/page.tsx
• src/lib/i18n.tsx
• supabase/schema-v17-bid-decisions-payment.sql
• supabase/patch-accept-bid-conflict.sql
• supabase/patch-ask-sold-notification.sql
• .env.example

Concrete Checks

• Verify PaymentIntent amount is derived or validated server-side against current product/ask/bid data.
• Verify capture belongs to the authenticated user or valid order/bid participant.
• Verify payment intent IDs cannot be attached to arbitrary bids or orders by direct client updates.
• Verify manual capture timing matches Stripe authorization windows.
• Verify mock mode cannot be mistaken for production readiness.
• Verify STRIPE_SECRET_KEY is documented in env requirements when live mode is used.
• Verify webhook handling exists or is called out as missing before production.
• Verify fee, refund, cancellation, chargeback, seller payout, and verification-failure flows are documented.

Mistakes To Avoid

• Do not trust client-supplied amount_cents.
• Do not capture a PaymentIntent without checking ownership and order/bid state.
• Do not store card data in the app.
• Do not tell users payment is complete if only a mock or pending state exists.
• Do not release seller payout before ERTZU verification.
• Do not ship production payments without webhooks and reconciliation.