/connect-recommend

Recommendation output template and component mapping

Use this reference to generate the recommendation output. It defines the full output structure, section requirements, fee guidance rules, and template formatting.

Output requirements

Output MUST include all of these sections:

• Account configuration (dashboard, fees_collector, losses_collector) with explicit Accounts v2 declaration, no legacy type
• merchant configuration for direct charges
• recipient configuration for destination or separate charges
• Charge pattern with 2-3 sentence rationale
• Seller and provider onboarding flow with onboarding method choice and rationale
• Dashboard access flow and rationale by access mechanism (express login links, full direct dashboard.stripe.com access, none embedded-components-primary interface)
• OAuth scope guidance when connecting existing Stripe accounts (only when user mentions OAuth or existing accounts; see compatibility-matrix section 4a)
• Fee structure with platform fee model, fee-payer recommendation, funds-flow diagram, and stripe.com/pricing link
• Embedded component recommendations tied to charge-pattern compatibility, with required notification_banner and charge-pattern caveats
• Webhook integration section (one sentence only; details deferred to build skill)
• Onboarding status gating using v2 capability paths
• Loss liability explanation separate from risk management
• Use separate headings for negative balance liability and risk management (don’t combine into one paragraph)
• For destination or separate with losses_collector: "application", explain the causal chain in plain language: platform owns negative balance liability, connected-account balances can go negative when needed, and transfer reversals can be used for dispute recovery
• SaaS monetization choices (transaction fees vs recurring SaaS fees), with customer_account guidance only for SaaS billing connected accounts
• application_fee_amount explanation and calculation mode

If any section is missing, add it before moving on.

Canonical recommendation template

## Recommended Connect integration

### A. Account configuration
Accounts API: `/v2/core/accounts`
Legacy account `type`: not used
Dashboard: [express / full / none]
Fee collection: [Stripe / platform]
Negative balance liability: [Stripe / platform]
[2-3 sentence explanation of why these settings fit]

[Include for direct charges only:]
Each connected account needs merchant configuration (`configuration.merchant`) for direct charges.

[Include for destination or separate charges only:]
Each connected account needs recipient configuration (`configuration.recipient`) with `stripe_transfers` on `stripe_balance` requested, so the account can receive transfers from the platform.

### B. Charge pattern: [destination / direct / separate charges and transfers]
[2-3 sentence explanation of why this fits]

### C. {sellerRole} onboarding flow
Onboarding method: [embedded / Stripe-hosted]
[2-3 sentence explanation of why this method was chosen over the alternative.]

[Describe the full onboarding flow: sign up, create account, onboarding with the chosen method, Stripe verification, capability status verification, handling ongoing requirements, checking capability status on an ongoing basis. Only enable live transactions when the necessary capabilities are active.]

### D. Payments dashboard access for {sellerRole}
- If dashboard=express: explain connected accounts access the Express dashboard through platform-generated Express login links, with embedded components for in-app workflows
- If dashboard=full: explain connected accounts log in directly at `dashboard.stripe.com`
- If dashboard=none: explain connected accounts don't use Stripe Dashboard login and embedded components are the primary interface for connected accounts

### E. Embedded components
Recommended [Connect embedded components](https://docs.stripe.com/connect/supported-embedded-components):
- `account_onboarding`
- `notification_banner` [required; keeps connected accounts aware of new requirements so they stay enabled]
- `account_management`
- `payments`
- `payouts`
[Add optional standalone components only when explicitly needed]
[Note any charge-pattern caveats, if relevant]

### F. Webhook integration
Use webhooks for reliable payment confirmation, especially for async payment methods. Always verify incoming webhook signatures before processing event data ([webhook signature verification](https://stripe.com/docs/webhooks/signatures)). Specific events and implementation details are covered in the build skill.

### G. Onboarding status gating
Verify capability statuses with `stripe.v2.core.accounts.retrieve(id)` before enabling payouts and transfers:
- Direct: `configuration.merchant.capabilities.card_payments.status === 'active'`
- Destination or separate: `configuration.recipient.capabilities.stripe_balance.stripe_transfers.status === 'active'`
- Also check payouts capability status in the relevant subtree

### H. Fee structure
- Platform fee model: [percentage / flat / tiered / mixed]
- `application_fee_amount` strategy: [platform fee only | platform fee + estimated Stripe processing fee]
- [Describe the fee structure, whether customers pay the connected account (seller) or platform, whether fees are paid to Stripe or to the platform, and whether anything is transferred from the platform to the seller. Pricing varies by region or payment method — check [stripe.com/pricing](https://stripe.com/pricing).]
- [Funds flow diagram with seller or provider net amount explanation:]

   {customerRole} pays ${amount}
         │
         ▼
  ┌───────────────┐
  │  {platform}   │ ─── keeps {X}% minus processing fees
  └──────┬────────┘
         │ transfer ({amount} minus {X}%)
         ▼
  ┌───────────────┐
  │  {sellerRole} │ ─── receives {amount} minus {X}%
  └───────────────┘

### I. SaaS monetization (if applicable)
State the monetization choice clearly: transaction fees (`application_fee_amount` or Platform Pricing Tool, not both), recurring SaaS or service fees, or both when justified.
Use `customer_account` only when charging recurring SaaS or service fees to connected accounts (v2 SetupIntent/Subscription calls).
Do NOT apply `customer_account` guidance to marketplace subscription or fan-to-creator recurring-payment flows.
Do NOT recommend creating a separate v1 Customer object for SaaS billing connected accounts.

### J. Implementation plan
1. [Account setup tasks]
2. [Onboarding flow tasks]
3. [Payments and fund-flow tasks]
4. [Webhook and readiness-gating tasks]
5. [Go-live checks]

### K. Risk and liability
- Negative balance liability owner: [your platform / Stripe]
- Risk controls owner: [your platform / Stripe]
- [Any required warnings from compatibility checks]

### L. Why this fits your business
- [2-4 bullets linking business model, merchant of record, and operational constraints to the configuration choices above]

### M. Open questions
- [Any unresolved assumptions to confirm before implementation]

Required wording snippets

Recipient configuration wording (destination or separate)

Include this wording (adapted to context) when charge pattern is destination or separate charges and transfers:

“Each connected account needs the recipient configuration (configuration.recipient) with stripe_transfers on stripe_balance requested, so the account can receive transfers from the platform. Marketplace connected accounts should NOT request merchant configuration or card_payments capability — this is unnecessary and causes longer onboarding.”

Webhook section guardrails

• Keep webhook section to one sentence that defers event details to the connect-build skill.
• Do NOT list concrete webhook event names in recommend output.
• Do NOT create a “Required Webhooks” section.
• Do NOT mention embedded components in the webhook section.

Risk and loss liability guidance

Always present loss liability and risk management as separate concepts:

• Loss liability (losses_collector): who is financially responsible for negative balances on connected accounts. losses_collector: "stripe" is the API field that enables Stripe’s public Managed Risk product — a full-service solution covering merchant loss protection, ongoing risk monitoring and detection, risk interventions, negative-balance recovery, and risk operations. Don’t equate losses_collector: "stripe" with Managed Risk as if they were the same thing; describe the field as what enables the broader product.
• Risk management: who detects and prevents fraud (Stripe Radar vs platform-managed). Radar is available regardless of who owns negative balance liability, but it is NOT optional when recommending Managed Risk (see below).

When losses_collector: application (platform owns loss liability), emphasize that Radar is essential — fraudulent charges that slip through come directly out of the platform’s balance. For marketplaces using destination charges, the platform is merchant of record and must manage risk.

Radar requirement for Managed Risk: Whenever a recommendation includes losses_collector: "stripe" (Express with Stripe-managed pricing, Express with platform-managed pricing, or full/Stripe/Stripe SaaS), explicitly recommend enabling Radar for Platforms alongside it. Managed Risk’s loss-protection model assumes Radar is active to catch transaction-level fraud; don’t present Managed Risk as replacing the need for Radar.

Public-preview disclosure

When the final recommendation is dashboard: "express" + fees_collector: "stripe" + losses_collector: "stripe" (Stripe-managed pricing, direct charges) or dashboard: "express" + fees_collector: "application" + losses_collector: "stripe" (platform-managed pricing, direct charges), include in the recommendation output:

• A concise public-preview disclosure stating that this Express + Stripe-managed-negative-balance-liability direct-charge configuration is in public preview.
• A statement that this configuration requires using the current Connect preview API version (not the platform’s pinned GA API version), with a link to the preview changelog so the user can confirm the exact version before implementing.
• A note that this configuration is only available for newly onboarded connected accounts — see “Migration limitation” below.

Keep the disclosure to two or three sentences total.

Migration limitation

The Express + Stripe-managed pricing and Express + platform-managed pricing configurations can only be used for new connected accounts created going forward — existing connected accounts can’t be migrated to either configuration. If the platform already has connected accounts on another configuration (for example, existing Express accounts with platform-owned pricing and losses, or full-dashboard accounts) and wants one of these configurations, clarify that only newly onboarded accounts can use the new configuration; existing accounts keep their current configuration unless the platform pursues a separate account-migration path with Stripe. The dashboard choice (Express versus full) is a permanent, one-way decision made at account creation for each connected account and can’t be changed later, so the platform needs to confirm this before onboarding accounts under either configuration.

Fee guidance rules

• When fees_collector: "stripe" and using direct charges, the connected account is charged the processing fee directly. The application_fee_amount is in addition to that and goes directly to the platform.

• With destination or separate charges, the platform ALWAYS pays Stripe’s processing fees.

• Do NOT hardcode Stripe fee amounts (rates vary by region, card type, method, and negotiated pricing).

• Do NOT make absolute profit and loss guarantees.

• Do NOT recommend application_fee_amount for separate charges and transfers (instead, retain fee by transferring less than charge amount).

• Do NOT set explicit application_fee_amount when Platform Pricing Tool is used (doing so will override tool logic).

• Always link to stripe.com/pricing.

• For platform-owned pricing, recommend Platform Pricing Tool and margin report. Platform Pricing Tool and explicit application_fee_amount are mutually exclusive — don’t recommend both.

• Mention Brazil or Malaysia cross-border fee-collection constraints where relevant.

• For low flat fees on variable amounts, warn about margin compression at larger ticket sizes.

• For very small transactions, warn about currency minimums and fee-to-proceeds effects.

Fee output requirements

These requirements apply only when the recommendation does NOT use the Platform Pricing Tool. When the Platform Pricing Tool is recommended (see “Fee guidance rules” above), skip applicationFeeIncludes and any application_fee_amount math entirely — state that pricing is configured in the Platform Pricing Tool instead, and do not set an explicit application_fee_amount.

When NOT using the Platform Pricing Tool, every recommendation MUST explicitly:

• Name the applicationFeeIncludes value (stripe_fee_estimate or platform_fee_only) and explain what it means for the platform’s margin
• Show a funds flow diagram with the platform fee
• Recommend the single most appropriate fee approach for the scenario; explain both approaches only when the platform’s margin goal or constraints are genuinely unclear (see Funds-flow comparison guidance below)

Low-margin warning template

This section applies unless the platform uses direct charges with Stripe-owned pricing (fees_collector: "stripe"). In that configuration, the connected account pays Stripe fees directly, so this concern doesn’t apply. When recommending the Platform Pricing Tool, retain the low-margin warning and margin explanation, but don’t include explicit application_fee_amount instructions because setting it overrides the tool’s pricing rules.

When platform fee appears low relative to processing fees, keep this order:

1. Warn first: Explicitly state that the selected platform fee might be below Stripe processing fees, so the platform might lose money per transaction when it absorbs fees.
2. Show downside before fix: include one concise illustrative example of net margin without fee passthrough (label assumptions clearly and link to stripe.com/pricing).
3. Then provide the fix:
   • If NOT using the Platform Pricing Tool: recommend margin-preserving application_fee_amount logic (platform fee + estimated Stripe fee) and explain why it preserves margin.
   • If using the Platform Pricing Tool: recommend configuring the tool to include Stripe’s estimated processing fee so the platform’s margin is preserved, and explicitly do NOT set application_fee_amount on the PaymentIntent.
4. Close with validation path: link to stripe.com/pricing and recommend monitoring the margin report.

Suggested warning phrasing:

Warning: Your platform fee may be below Stripe processing fees at standard rates. With this charge pattern, your platform pays Stripe processing fees on every transaction. If you absorb those fees, your net per transaction may be negative. Check stripe.com/pricing for your region and payment-method mix.

Funds-flow comparison guidance

Recommend the option that fits the user’s margin goal. Present both options only when the margin goal or constraints are genuinely unclear.

To disambiguate, ask: “Are you trying to make X% margin, or do you want your users to pay X%?” The answer determines which option to recommend.

When destination or direct flow uses application_fee_amount, choose guidance as follows:

• Margin-preserving recommendation: application_fee_amount = platform fee + estimated Stripe processing fee (still an approximation — actual rates vary by region, card type, and payment method)
• Platform-absorbs-fees recommendation: application_fee_amount = platform fee only
• If unclear: present both options concisely with the tradeoff and call out what assumption decides the recommendation

Onboarding status gating details

Always include gating guidance to prevent transfers and payouts for unready accounts. stripe_balance.payouts is auto-requested when card_payments or stripe_transfers is requested, so do NOT explicitly request stripe_balance.payouts in account create/update calls.

Use:

• configuration.merchant.capabilities.card_payments.status
• configuration.merchant.capabilities.stripe_balance.payouts.status
• configuration.recipient.capabilities.stripe_balance.stripe_transfers.status
• configuration.recipient.capabilities.stripe_balance.payouts.status

Do NOT rely on v1 charges_enabled or payouts_enabled booleans for this flow.

Embedded component template notes

The embedded components section should list the components selected during Step 4b (see SKILL.md for selection logic and charge-pattern compatibility caveats). See Connect embedded components for documentation.