references/decision-matrix.md · 24000
`` Concept: application_fee_amount = estimated Stripe processing fee + platform margin Platform NET = the platform's full fee percentage (margin preserved — Stripe fee covered by the higher application_fee_amount) Connected account receives = charge amount − application_fee_amount
**Option B — Platform fee only (platform absorbs Stripe fees)** The `application_fee_amount` is only the platform’s cut. Stripe processing fees reduce the platform’s net. Only viable when the platform fee is substantially higher than Stripe’s processing fees.
Concept: application_fee_amount = platform fee only Platform NET = platform fee − Stripe processing fee Connected account receives = charge amount − application_fee_amount
**Recommendation output rule:** choose the single most appropriate option for the specific scenario instead of always presenting both. Keep the other option as reference material and show it only when the user asks for alternatives and tradeoffs.
**Decision guidance:** If the platform fee appears low or uncertain relative to processing fees (check [stripe.com/pricing](https://stripe.com/pricing)), recommend Option A to preserve platform margin (or switch to direct charges when appropriate). Use Option B only when fee headroom is clearly high and the platform explicitly accepts absorbing fee variance.
**For destination charges, NEVER say “seller pays Stripe fees” or “connected account pays Stripe fees.”** The platform always pays. The choice is whether to set a higher `application_fee_amount` to preserve the platform’s margin.
**Minimum charge amounts:** Stripe enforces minimum charge amounts by currency. For micro-payment platforms with very small transaction amounts, warn the user that:
- Stripe enforces minimum charge amounts that vary by currency
- On very small charges, the fixed fee component becomes a large percentage of the transaction
- Micro-payments may need batching or alternative approaches to be economically viable
##### Fee guidance principles
When presenting fee recommendations:
- DO NOT hardcode specific processing fee amounts (for example, “2.9% + $0.30”) — these are US-only and vary by region, card type, and payment method
- DO NOT make definitive profit and loss claims (for example, “you WILL lose money”) — say “you may lose money at standard rates”
- DO link to [stripe.com/pricing](https://stripe.com/pricing) for region-specific rates
- DO strongly recommend the [Platform Pricing Tool](https://dashboard.stripe.com/settings/connect/platform_pricing)
- DO recommend monitoring the margin report in the Stripe Dashboard
- DO explain the concept of `application_fee_amount` and what it should include based on the calculation choice
- DO return one recommended fee option for the scenario (don’t always present both Option A and Option B)
- DO prefer margin-preserving recommendations in low-margin or uncertain-margin scenarios
- DO use transfer-math framing for separate charges and transfers (never `application_fee_amount`)
- NEVER say “seller pays Stripe fees” or “connected account pays Stripe fees” for destination charges — the platform always pays
##### Fee sanity checks
- If the Platform Pricing Tool is used, ensure `application_fee_amount` is NOT set on the PaymentIntent — explicit `application_fee_amount` overrides the Platform Pricing Tool.
- `application_fee_amount` is NOT compatible with separate charges and transfers. NEVER recommend it for separate charges and transfers.
- For separate charges and transfers, validate the transfer-math model (`charge_amount − total_transfers − Stripe_fees`) to ensure expected platform margin.
- Platforms based outside Brazil can’t collect application fees from Brazilian connected accounts due to regulatory requirements. Same restriction applies to Malaysia.
- Use `amount` on the ApplicationFee object, not the charge field, for accurate fee reporting.
- For small transactions (for example, $1–$5), fees may be large relative to proceeds. Consider creative ways to combine transactions.
- **Low-complexity margin path:** Direct charges with Stripe-owned pricing. Stripe handles pricing complexity; the platform charges a SaaS fee or application fee on top.
- If the platform owns pricing with any charge type: warn about potential per-transaction losses. Strongly recommend the Platform Pricing Tool and monitoring the margin report.
#### Loss Liability (Negative Balance Liability)
**Loss liability and risk management are TWO SEPARATE decisions.** The current skill MUST NOT conflate them.
| Concept | What it means | Where configured |
| --- | --- | --- |
| **Negative balance liability** | Who is financially LIABLE when disputes and chargebacks create negative balances on connected accounts | Configured when creating the connected account; may require visiting the Stripe Dashboard → Connect platform profile to acknowledge understanding of how negative balance liability works |
| **Risk management** | Who DETECTS and PREVENTS fraud (Radar, rules, monitoring) | Code + Dashboard (Radar settings) |
You can have Stripe own loss liability while still using Radar for fraud detection. Radar is available regardless of loss liability setting.
##### Loss Liability Recommendations by Business Model
**Recommendation depends on charge pattern:**
- **Marketplaces (destination or separate charges):** Platform-owned loss liability. This is **required** for destination charges — it enables connected account balances to go negative, which the platform needs to reverse transfers (for example, for refunds or disputes). Also required for Express dashboard with non-direct charge patterns today.
- **SaaS (direct charges):** Stripe-owned loss liability is the recommended default — SaaS platforms shouldn’t need to bear negative balance liability because the connected account is the merchant of record. This is available with Express dashboard (Stripe-managed or platform-managed pricing, public preview) or full dashboard.
- **Enterprise or white-label:** Platform-owned. Full control = full responsibility.
| Business Model | Recommended Loss Liability | Why |
| --- | --- | --- |
| **Marketplace** | **Platform** | Required for destination charges — enables connected account negative balances for transfer reversals |
| **On-demand services** | **Platform** | Same as marketplace — uses destination charges |
| **Professional services** | **Platform** | Same as marketplace — uses destination charges |
| **Rental marketplace** | **Platform** | Same as marketplace — uses destination charges |
| **Event ticketing** | **Platform** | Same as marketplace — uses destination charges |
| **Crowdfunding** | **Platform** | Uses separate charges — platform-owned loss liability enables flexible transfer reversals |
| **Subscription platforms** | **Platform** | Uses destination charges — platform-owned loss liability required |
| **SaaS with payments** | **Stripe** | SaaS platforms use direct charges — connected account is merchant of record. Available with Express dashboard (Stripe-managed or platform-managed pricing, public preview) or full dashboard. |
| **E-commerce (white-label)** | Platform | Full control = full responsibility (dashboard: none, platform-managed) |
| **B2B platforms** | Platform | Enterprise requirements usually demand full control |
##### Loss Liability Dashboard Setup
Loss liability is configured when creating connected accounts, but the platform must first visit the Stripe Dashboard → Connect platform profile (`dashboard.stripe.com/settings/connect/platform-profile`) to acknowledge understanding of how negative balance liability works.
The platform profile page asks about “Negative balance liability” (formerly called “loss liability”). The choice determines which account configuration combinations are available:
- **Stripe manages losses** → Set `defaults.responsibilities.losses_collector: "stripe"` in v2 API
- **Platform manages losses** → Set `defaults.responsibilities.losses_collector: "application"` in v2 API
When guiding users through this page, always:
1. Explain what loss liability means in plain language with a concrete example
2. Recommend platform-owned for marketplaces using destination or separate charges — required for transfer reversals, and required for Express dashboard with those non-direct charge patterns
3. Recommend Stripe-owned for SaaS platforms using direct charges — this now works with either Express dashboard (Stripe-managed or platform-managed pricing, public preview) or full dashboard
4. Keep this decision separate from Radar and fraud detection
### Integration Antipattern Warnings
> **Read the full compatibility matrix in `compatibility-matrix.md`.** This section is a quick reference.
#### Common Blocked Combinations
These combinations are true antipatterns that Stripe will never support. Do NOT recommend them:
1. **`losses_collector: "stripe"` + destination charges** — Liability and fee behavior don’t align with this charge pattern. Treat as BLOCKED when `losses_collector: "stripe"` is selected.
2. **`losses_collector: "stripe"` + separate charges and transfers (including `on_behalf_of`)** — Same negative balance mechanism as destination charges. Platform can’t recover funds from connected accounts that only receive transfers.
3. **Express dashboard + `losses_collector: "stripe"` + non-direct charges** — Express dashboard with Stripe-managed negative balance liability is only supported for **direct** charges (Stripe-managed pricing with `fees_collector: "stripe"`, or platform-managed pricing with `fees_collector: "application"`), and only as a public-preview capability. For destination charges or separate charges and transfers, this combination remains BLOCKED regardless of `fees_collector`. `express/stripe/application` (Express + Stripe-managed pricing + platform-managed losses) also remains BLOCKED for all charge patterns.
4. **`dashboard: "full"` + destination charges or separate charges and transfers** — Full dashboard has reduced payment and dispute detail for destination and separate charges. Full dashboard provides complete payment and dispute management for direct charges only.
5. **`fees_collector: "stripe"` + `losses_collector: "application"` (Stripe-owned pricing + platform-owned losses)** — This combination is BLOCKED for all charge types and all dashboards. The reverse — `fees_collector: "application"` + `losses_collector: "stripe"` (platform-managed pricing + Stripe-managed losses) — is SALES-GATED for `full` dashboard, BLOCKED for `none` dashboard, and, for `express` dashboard, ALLOWED as a public-preview path (platform-managed pricing) with direct charges only.
6. **(`on_behalf_of` is out of scope for this guide — redirect to docs or sales if encountered.)** **`on_behalf_of` with destination charges for marketplace use cases** — Do NOT use `on_behalf_of` for marketplaces. `on_behalf_of` makes the connected account the merchant of record, but in a marketplace the platform is the merchant of record. If a user requires `on_behalf_of`, direct them to [Stripe Connect docs](https://docs.stripe.com/connect/charges.md) or [Stripe sales](https://stripe.com/contact/sales).
7. **`application_fee_amount` with separate charges and transfers** — NOT compatible. Platforms using separate charges and transfers collect fees by transferring less than the charge amount.
#### Blessed Paths (Safe Defaults)
| Business Model | Dashboard | Fees | Losses | Charge Type | Status |
| --- | --- | --- | --- | --- | --- |
| **Marketplace** | `express` | `application` | `application` | Destination | CAUTION — recommended path; always include Express dispute-visibility warning (see `compatibility-matrix.md`) |
| **Self-serve SaaS, Stripe-managed pricing** | `express` | `stripe` | `stripe` | Direct | ALLOWED (PUBLIC PREVIEW) — low-operations default for self-serve SaaS platforms; disclose public-preview status |
| **Self-serve SaaS, platform-managed pricing** | `express` | `application` | `stripe` | Direct | ALLOWED (PUBLIC PREVIEW) — for self-serve SaaS platforms that want pricing control; pair with the Platform Pricing Tool; disclose public-preview status |
| **SaaS** | `full` | `stripe` | `stripe` | Direct | ALLOWED — connected accounts are independent merchants that need full, independent Stripe operations |
| **Enterprise** | `none` | `application` | `application` | Any | ALLOWED — full platform control |
**Any deviation from these blessed paths must trigger a compatibility check against `compatibility-matrix.md`.** If the user’s choices lead to a BLOCKED combination, don’t present it. Explain why it fails and recommend the nearest allowed alternative.
> **Scope boundary:** This guide supports the blessed paths above. Configurations outside these paths (full+application, `on_behalf_of`, OAuth, non-payments products like Issuing, Treasury, Capital, Tax, or Terminal) must trigger sales-led detection and redirect to docs or sales. `none` dashboard requires platform-owned pricing AND platform-owned losses — no other `none` combination is valid even for sold users.
#### Additional Antipatterns to Watch For
- **OAuth instead of Account Links** — Developers think OAuth is simpler but lose platform control (connected account can disconnect at any time). Recommend Account Links or embedded components.
- **Custom onboarding** (`dashboard: "none"` + API-based) — Ongoing requirement collection burden and country-specific complexity. Only for platforms with dedicated compliance engineering.
- **Dashboard DIY without refund and dispute flows** — Platforms build earnings views but skip refund and dispute management. Connected accounts can’t respond to disputes, leading to auto-losses.
- **Stripe does NOT enforce merchant of record at API level** — Platforms can create charges with any pattern regardless of their onboarding declaration. Code must consistently use the correct charge type for the actual business relationship.