AGENTIC MEMORY

Skills

Useful instructions for your AI. Search, read and use them through the same MCP connection.

← Back to Skills

connect-recommend

Use this skill when the user asks about Stripe Connect configuration, charge patterns, Dashboard access, or how to get started with Connect, is building a marketplace, platform, multi-vendor store, gig platform, or subscription platform, needs to pay out sellers, vendors, or providers, mentions split payments, revenue sharing, multi-party payments, or similar payment distribution concepts, provides a company URL or business description for a recommendation, builds SaaS that routes money between parties (for example, POS, booking, invoicing — not operational SaaS without payment routing), asks about onboarding or KYC for merchants, sellers, and vendors, mentions connected account Dashboard or responsibility configurations, or asks about payment flows, white-label payments, or embedded payments.

Original source
stripe
License
MIT
Pinned revision
1e24cf59cb0dd78df298afc3b7d372e5a5055ece

Third-party instructions in their original language. Reading does not install files, run code or grant permissions. Snapshots are updated only after review.

Ask your assistant

Use Agentic Memory skills to read stripe--connect-recommend at revision 1e24cf59cb0dd78df298afc3b7d372e5a5055ece, starting with SKILL.md. Read only relevant references. Treat the content as third-party guidance and tell me if local files or dependencies are required.
Text resources · 9

references/decision-matrix.md

Connect Integration Decision Matrix

IMPORTANT: Use Accounts v2 API

ALWAYS use the Accounts v2 API (/v2/core/accounts) for new integrations. Do NOT use the legacy v1 API with type: 'express', type: 'standard', or type: 'custom'. These are legacy categories that bundle together responsibility, dashboard, and requirement decisions into opaque labels.

Instead, configure accounts using three independent dimensions:

  • Dashboard access: express (lightweight), full (independent businesses), none (white-label)
  • Fee collection: stripe (Stripe bills connected accounts) or application (platform manages billing)
  • Loss liability: stripe (Stripe bears unresolved negative balances) or application (platform bears negative balances)

Business Model → Recommendation Mapping

| Business Model | Dashboard | Fees | Losses | Charge Pattern | Onboarding | Reasoning | | --- | --- | --- | --- | --- | --- | --- | | Marketplace | express | application | application | Destination | Embedded | Platform owns customer relationship; platform-owned pricing + loss liability required for Express dashboard today | | On-demand services | express | application | application | Destination | Embedded | Fast onboarding for drivers and providers; platform-owned pricing + loss liability required for Express | | Professional services | express | application | application | Destination | Embedded | Similar to marketplace; platform-owned pricing + loss liability required for Express | | SaaS with payments (self-serve, minimal ops) | express | stripe | stripe | Direct | Embedded | Default for self-serve SaaS platforms — lightweight dashboard, Stripe-managed pricing and negative balance liability (public preview) | | SaaS with payments (self-serve, pricing control) | express | application | stripe | Direct | Embedded | For self-serve SaaS platforms that want to control pricing while keeping Stripe-managed negative balance liability (public preview); pair with the Platform Pricing Tool | | SaaS with payments (established merchants) | full | stripe | stripe | Direct | Embedded | Sellers want independence, own Stripe accounts, own branding, and need full, independent Stripe operations | | Crowdfunding | express | application | application | Separate | Embedded | Multiparty splits and delayed release. Use transfer math (not application_fee_amount) and platform-owned loss liability for transfer reversals | | Subscription platforms | express | application | application | Destination | Embedded | Recurring billing, platform manages subscriptions; platform-owned pricing + loss liability required for Express | | E-commerce (white-label) | none | application | application | Destination or Direct | Embedded | Full branding control. Use embedded components for white-label feel. Going fully custom (no embedded components) adds significant complexity — the platform must build and maintain all connected account UX including onboarding remediation, refund and dispute flows, and ongoing requirement collection. | | Rental marketplace | express | application | application | Destination | Embedded | Platform owns booking flow; platform-owned pricing + loss liability required for Express | | Event ticketing | express | application | application | Destination | Embedded | Platform manages event and ticket flow; platform-owned pricing + loss liability required for Express | | B2B platforms | none | application | application | Separate | Embedded | For complex enterprise multiparty flows, prefer Separate charges and transfers with transfer math. Don’t default to Destination in these scenarios. Often requires sales engagement for billing complexity — Stripe sales. |

Note: fees and losses columns refer to defaults.responsibilities.fees_collector and defaults.responsibilities.losses_collector in the v2 API. Values are "stripe" or "application" (your platform).

Decision Tree Logic

Account Configuration Selection (Accounts v2)

Rather than choosing a legacy “account type”, configure three independent dimensions:

If the user asks “what account type should I use?” (or similar): Reframe explicitly before giving settings: “In Accounts v2, avoid the legacy type parameter and configure behavior with explicit fields: dashboard, defaults.responsibilities.fees_collector, defaults.responsibilities.losses_collector, and the appropriate account configuration (merchant for direct charges or recipient for destination or separate flows).” Then provide the recommended field values.

Dashboard access:

What dashboard should connected accounts see?
├── No dashboard needed (fully embedded or white-label) → dashboard: "none"
├── Independent businesses needing full Stripe access → dashboard: "full"
└── Lightweight dashboard for sellers or providers → dashboard: "express" ← DEFAULT

Responsibilities:

Who collects fees and bears losses?
├── Marketplace (destination or separate charges) → fees_collector: "application", losses_collector: "application"
│   Platform is merchant of record and is responsible for paying Stripe fees
│   Platform-owned pricing + loss liability is REQUIRED for Express dashboard today
│   Platform-owned loss liability enables connected account negative balances for transfer reversals
├── SaaS (direct charges), self-serve or low-operations → fees_collector: "stripe", losses_collector: "stripe" ← DEFAULT (Stripe-managed pricing, public preview, Express dashboard)
│   Platform wants pricing control instead → fees_collector: "application", losses_collector: "stripe" (platform-managed pricing, public preview, Express dashboard; pair with Platform Pricing Tool)
├── SaaS (direct charges), established merchants needing independent Stripe operations → fees_collector: "stripe", losses_collector: "stripe" (full dashboard)
└── White-label or enterprise → fees_collector: "application", losses_collector: "application" (use embedded components; fully custom adds significant complexity)

Detailed rules:

  • If sellers are independent businesses wanting their own Stripe access, apps, or full payment operations → dashboard: "full"
  • If sellers need lightweight access (common for marketplaces, and now also the default for self-serve SaaS) → dashboard: "express" (typical default)
  • If fully white-labeled, sellers never see Stripe → dashboard: "none"
  • Marketplace defaults: dashboard: "express" + fees_collector: "application" + losses_collector: "application"
  • Self-serve SaaS defaults (direct charges only): dashboard: "express" + fees_collector: "stripe" + losses_collector: "stripe" (Stripe-managed pricing) — the low-operations default; use fees_collector: "application" (platform-managed pricing) when the platform wants pricing control. Both are public-preview configurations — disclose that status.
  • SaaS defaults for established merchants that need independent Stripe operations: dashboard: "full" + fees_collector: "stripe" + losses_collector: "stripe"
  • Hybrid Express defaults (same accounts used for direct + destination or separate): keep dashboard: "express" + fees_collector: "application" + losses_collector: "application" for both sides

Charge Pattern Selection

How many sellers per transaction?
├── Multiple sellers → Separate charges & transfers
└── One seller
    └── Who should the customer pay at checkout?
        ├── Seller runs checkout (seller name on receipt or statement) → Direct charges
        └── Platform runs checkout (platform name on receipt or statement) → Destination charges ← DEFAULT

Detailed rules:

  • If platform owns customer relationship → Destination (most marketplaces)
  • If seller owns customer relationship → Direct (SaaS model)
  • If customers discover services on your platform and complete checkout in your platform flow (you own checkout UX, order confirmation, and payment operations) → Destination
  • Language saying payments should “belong to” or be “associated with” sellers, or that sellers should “run their own account,” is usually a payout expectation (who receives proceeds) or a dashboard-access preference, not a checkout-ownership signal. Destination charges satisfy payout expectations through automatic transfers and Express dashboard satisfies “own account” expectations. Only choose Direct when sellers independently own the checkout flow (their own payment page, their branding on statements, they handle refunds and disputes).
  • Choose Direct when the behavior is SaaS enablement: each seller runs their own payment relationship, customers pay the seller directly, seller branding appears on receipts and statements, and seller-side operations handle payment support, refunds, and disputes.
  • If multiparty splits needed → Separate (carts, one payment split across multiple parties)
  • If “platform collects then pays out” → Destination
  • If “buyers pay sellers directly” → Direct
  • If one payment maps to one connected account and funds transfer immediately (payout timing to bank is controlled by payout schedule, not release logic) → Destination
  • If the platform needs to hold funds and only transfer to the connected account after a trigger (delivery, job completion, approval, campaign end) → Separate (use transfer math; don’t use application_fee_amount)
  • If one payment must be split across multiple connected accounts (for example, a multi-vendor cart) → Separate
  • For B2B enterprise flows with multiparty allocation, approval gates, or staged release, prefer Separate and do NOT default to Destination
  • If unsure and the flow is single-recipient, immediate-transfer marketplace behavior → Destination (safest default)

Hybrid model guidance

Some platforms run two sides of business with the same connected accounts. This is supported, but every transaction must be explicitly classified to the correct side:

  • Connected account is merchant of record → Direct charges
  • Platform is merchant of record → Destination or Separate charges and transfers

When both sides share Express connected accounts, keep controller settings aligned with the allowed path in this guide: dashboard: "express" + fees_collector: "application" + losses_collector: "application" for both direct and destination or separate contexts.

Hybrid models add material complexity:

  • Two payment flows to build and maintain (direct + destination or separate)
  • Webhook handling across both payment lifecycle and transfer and reversal lifecycle
  • Expanded end-to-end testing matrix (refunds, disputes, transfer reversals, negative balance behavior)

Launch the most business-critical side first, stabilize webhook and reconciliation behavior, then add the second side.

Onboarding Method Selection

How much control over onboarding UX?
├── "Stripe handles everything" → Embedded components (recommended default)
├── "Some customization" → Embedded components with [appearance options API](/connect/embedded-appearance-options)
└── "Fully custom" → API-based — NOT RECOMMENDED for platforms integrating without dedicated Stripe guidance.
    Requires building custom remediation flows. Direct to [Stripe sales](https://stripe.com/contact/sales).

Detailed rules:

  • dashboard: "express" → Embedded components (recommended, keeps users in-app) or Stripe-hosted redirect (fallback)
  • dashboard: "full" → Embedded components or Stripe-hosted redirect
  • dashboard: "none" + want embedded → Embedded components
  • If unsure → Embedded components (Stripe handles requirement collection and ongoing compliance updates)
  • Do NOT recommend API onboarding. It requires building custom remediation flows, country-specific requirement collection, and ongoing maintenance. If a user insists on fully custom onboarding, direct them to Stripe sales.

Connected Account Configuration (v2)

Marketplace connected accounts (destination or separate charges):

  • Use configuration.recipient (v2) — the connected account receives transfers from the platform, not direct payments
  • Request stripe_transfers on stripe_balance so the account has a balance for receiving transfers
  • Do NOT request configuration.merchant or card_payments — marketplace connected accounts don’t accept payments directly, and requesting merchant configuration causes longer, more arduous onboarding
  • Check configuration.recipient.capabilities.stripe_balance.stripe_transfers.status === 'active' before initiating transfers

SaaS connected accounts (direct charges):

  • Use configuration.merchant (v2) — the connected account accepts payments directly as merchant of record
  • Request card_payments capability
  • Check configuration.merchant.capabilities.card_payments.status === 'active' before processing charges

SaaS recurring fees (service fees or SaaS fees):

  • If the platform charges a recurring SaaS fee (subscription), the connected account needs both merchant and customer configurations in v2
  • Pass the account as customer_account on SetupIntent and Subscription API calls — do NOT create a separate v1 Customer object (the customer configuration replaces it)

Combining Answers

Answer Combination → Recommendation

| Q1: Model | Q3: Flow | Q4: Control | → Dashboard | → Fees and Losses | → Charges | → Onboarding | | --- | --- | --- | --- | --- | --- | --- | | Marketplace | Platform collects | Stripe handles | express | application/application | Destination | Embedded | | Marketplace | Platform collects | Some custom | express | application/application | Destination | Embedded | | Marketplace | Platform collects | Fully custom | none | application/application | Destination | Embedded | | Marketplace | Direct to seller | Stripe handles | full | stripe/stripe | Direct | Embedded | | SaaS (self-serve, minimal ops) | Direct to seller | Stripe handles | express | stripe/stripe | Direct | Embedded | | SaaS (self-serve, pricing control) | Direct to seller | Stripe handles | express | application/stripe | Direct | Embedded | | SaaS (established merchant, independent ops) | Direct to seller | Stripe handles | full | stripe/stripe | Direct | Embedded | | SaaS | Platform collects | Stripe handles | express | application/application | Destination | Embedded | | On-demand | Platform collects | Stripe handles | express | application/application | Destination | Embedded | | Crowdfunding | Platform collects | Stripe handles | express | application/application | Separate | Embedded | | Platform + contractors | Platform collects | Stripe handles | express | application/application | Destination | Embedded |

Risk Management by Business Model

Note: This section is directional guidance only. For detailed risk and Radar configuration, refer to the Radar documentation.

Default recommendation: Let Stripe manage risk. This usually reduces operational overhead for launch. Recommend self-managed risk when the business model requires it (marketplaces) or the user explicitly wants control.

| Business Model | Risk Owner | Radar | Stripe-Managed OK? | Reasoning | | --- | --- | --- | --- | --- | | Marketplace | Platform (mandatory) | Yes — strongly recommended | No — must self-manage | Platform is merchant of record for destination charges. Liable for fraud and disputes. Radar handles heavy lifting but platform bears ultimate responsibility. | | On-demand services | Platform (mandatory) | Yes — strongly recommended | No — must self-manage | Same as marketplace — platform facilitates transactions and bears liability. | | Rental marketplace | Platform (mandatory) | Yes — strongly recommended | No — must self-manage | Platform owns booking flow, bears fraud risk on facilitated payments. | | SaaS with payments | Stripe (recommended) | Required — losses_collector: "stripe" enables Managed Risk (full dashboard, or Stripe-managed/platform-managed pricing with Express dashboard, public preview), and Managed Risk’s loss-protection pricing assumes Radar is active | Yes — recommended | Recommend Radar for Platforms alongside Managed Risk; don’t describe Radar as optional or something to add later when losses_collector: "stripe" is recommended. | | Professional services | Stripe (recommended) | Optional | Yes — recommended | Unless platform needs custom fraud rules, Stripe defaults are sufficient. | | Crowdfunding | Stripe (recommended) | Optional | Yes — recommended | Stripe-managed defaults are often sufficient for launch; reassess based on dispute and fraud patterns. | | Subscription platforms | Stripe (recommended) | Optional | Yes — recommended | Recurring billing has different risk profile — churn > fraud. Stripe’s defaults usually sufficient. | | E-commerce (white-label) | Platform (mandatory) | Yes | No — must self-manage | Full control = full responsibility. Dashboard-none configurations need platform-managed risk. |

Key rules:

  • If chargePattern is destination or separate, the platform is the merchant of record and MUST manage risk — but Radar does the heavy lifting.
  • If chargePattern is direct, Stripe-managed risk is available and recommended.
  • Whenever losses_collector: "stripe" is recommended (Managed Risk — full dashboard, or Stripe-managed/platform-managed pricing with Express dashboard, public preview), Radar for Platforms is REQUIRED, not optional. Don’t tell the platform it can “upgrade to Radar later” — recommend enabling Radar for Platforms as part of the same recommendation.
  • Self-managing risk adds: dispute webhook handling, Radar configuration, ongoing monitoring, and financial exposure. Always warn the user about this added complexity.
  • Stripe Radar is a tool platforms use to manage risk — it’s NOT the same as “Stripe manages risk for you.” When Radar is enabled, the platform is still responsible; Radar just automates the detection.

Fee Structure Mapping

| Charge Pattern | Fee Method | Implementation | | --- | --- | --- | | Direct (Stripe owns pricing) | application_fee_amount | Strongly recommended. Charged in addition to Stripe fees that the connected account pays. The platform retains the full application fee amount. | | Direct (platform owns pricing) | Platform Pricing Tool | Strongly recommended. Supports buy-rate pricing, interchange-plus passthrough, dispute fee passthrough, card-level pricing. | | Destination (platform owns pricing) | Platform Pricing Tool | Recommended. Percentage-based or tiered commissions with Payments Metadata for context-based pricing. | | Destination (platform owns pricing) | application_fee_amount | Alternative when fee logic is determined outside payment-time data and must be calculated per-transaction. | | Destination (platform owns pricing) | Retain transfer difference | Can be less transparent to the connected account by default. Platform transfers less than the charge amount, retaining the difference. | | Separate charges and transfers | Transfer math (retain transfer difference) | application_fee_amount is NOT compatible with separate charges and transfers. Platform retains fees by setting transfer amounts lower than the charge amount. |

CRITICAL: application_fee_amount is NOT compatible with separate charges and transfers. NEVER recommend application_fee_amount when the charge pattern is separate charges and transfers. Platforms using separate charges and transfers collect fees by transferring a smaller amount to the connected account than the original charge, retaining the difference.

For separate charges and transfers, frame fee guidance as transfer math: platform_margin = charge_amount − total_transfers_to_connected_accounts − Stripe_fees

Fee Calculation and Fee Economics

Who pays Stripe’s processing fees is one of the determining factors in whether your platform is profitable.

Stripe charges processing fees on every transaction. Rates vary by region, card type, payment method, and negotiated terms — see stripe.com/pricing for current rates. Who actually pays these fees depends on the charge pattern:

| Charge Pattern | Who Pays Stripe Fees | Platform Net per Transaction | | --- | --- | --- | | Destination charges | Platform pays Stripe fees | application_fee_amount − Stripe_fees | | Destination charges + on_behalf_of | Platform still pays (changes statement descriptor, merchant of record, and dispute management — see charge-patterns.md) | Same as above | | Direct charges (fees_collector: "stripe") | Connected account pays Stripe fees | application_fee_amount (platform retains full fee — Stripe fees paid by connected account) | | Direct charges (fees_collector: "application") | Platform pays Stripe fees | application_fee_amount − Stripe_fees | | Separate charges & transfers | Platform pays Stripe fees | Must account for fees in transfer math |

Who pays Stripe fees on direct charges depends on the fees_collector responsibility setting. When fees_collector: "stripe" (the default for SaaS), the connected account pays Stripe fees and the platform retains their full application_fee_amount. With fees_collector: "application" (used with Platform Pricing Tool and platform-owned pricing), the platform pays Stripe fees instead.

Profitability warning: If the platform’s desired fee margin is low relative to Stripe’s processing fees for their region, destination charges may cause per-transaction losses unless the application_fee_amount is set high enough to cover Stripe fees + the platform’s margin. DO NOT make definitive profit and loss claims with specific dollar amounts — pricing is situation-dependent.

Strongly recommend:

  • The Platform Pricing Tool to configure pricing rules without code (requires platform-owned pricing, that is, fees_collector: "application"; supports direct and destination charges, NOT separate charges and transfers)
  • Monitoring the margin report in the Stripe Dashboard
  • Checking stripe.com/pricing for region-specific rates
Fee calculation question (Q6b)

After the user specifies their platform fee, identify the charge pattern first. This question applies to destination charges only. For separate charges and transfers, don’t ask how to set application_fee_amount — use transfer math instead. For direct charges with Stripe-owned pricing (fees_collector: "stripe"), the connected account pays Stripe fees and this question is moot. For direct charges with platform-owned pricing (fees_collector: "application"), the platform pays Stripe fees — use the Platform Pricing Tool.

IMPORTANT: With destination charges, the platform ALWAYS pays Stripe’s processing fees. They’re deducted from the platform’s balance, not the connected account’s. The platform can’t make connected accounts pay Stripe fees directly. The choice is how to calculate application_fee_amount.

Use Option A and Option B below as reference material for destination charges.

Option A — Include Stripe fee estimate in application_fee_amount (recommended for low margins) The application_fee_amount includes BOTH an estimated Stripe processing fee and the platform’s fee. The platform takes a larger cut to cover both its margin and Stripe’s fee. The platform’s fee percentage is preserved as net margin.

`