Setting the file. One moment.
Subchapter 1.8
references/terminology-rules.mdMarkdown6 KBView on GitHub
When generating text that will be shown to the user, follow these rules strictly. They apply to all output including warning blocks, explanations, recommendation text, and transition summaries.
This plugin is a public artifact. Never expose internal shorthand codes, internal taxonomy labels, or internal-only references in output.
Always describe configurations using human-readable field values: dashboard type + fee ownership + negative balance liability ownership + charge pattern.
Use full, user-friendly terminology in prose. Prefer complete terms such as “connected account,” “merchant of record,” “separate charges and transfers,” and “interchange-plus pricing.” Use API field names only when needed for implementation clarity (for example, on_behalf_of).
Use neutral framing for payout timing: “hold funds before releasing” or “delivery-gated payout.”
Describe pricing outcomes as margin mechanics and tradeoffs. Don’t guarantee profitability.
This skill is scoped to Stripe Connect integration guidance.
Legacy account type names can be mentioned only when explaining migration from v1 to v2. For new integrations, always recommend Accounts v2 dimensions instead of legacy account type labels.
Stripe’s public docs define two Connect business model categories. Use these when speaking to the user:
When explaining the business classification, focus on the funds flows required, for example, in a marketplace, the platform collects payments from customers, takes a cut, and distributes the remainder to sellers; the platform’s name appears on the customer’s bank statement. In a SaaS platform, the seller collects payments directly under the seller’s own business name.
Do NOT use:
The decision matrix’s finer categories (on-demand services, professional services, rental marketplace, and more) are internal aids for config selection. Use them during analysis but present the user-facing label when speaking to the user.
When users are unfamiliar with “merchant of record,” explain it in plain language:
Use this as a behavioral signal in discovery:
When showing configuration values, ALWAYS pair them with a human-readable label. The human-readable label comes first; the technical name is parenthetical.
| Raw config term | Human-readable label |
|---|---|
losses_collector: application | Negative balance liability: your platform |
losses_collector: stripe | Negative balance liability: Stripe |
fees_collector: application | Fee collection: your platform manages pricing |
fees_collector: stripe | Fee collection: Stripe bills connected accounts |
dashboard=express | Dashboard: Express (lightweight view for sellers) |
dashboard=full | Dashboard: Full Stripe Dashboard (independent access) |
dashboard=none | Dashboard: none (you build all seller-facing UIs) |
Don’t use “Platform-owned” or “Stripe-owned” as standalone labels — these are confusing when addressing the platform user directly. Instead say:
Use “negative balance liability” (not “loss liability” or “who pays for losses”). When explaining, say: “When a customer disputes a charge, the disputed amount may create a negative balance. Negative balance liability determines which party — your platform or Stripe — absorbs those negative balances.”
Do NOT use “who pays” framing — it is too vague. The concept is specifically about liability for negative balances on connected accounts.
Use neutral compatibility wording in user-facing output. Say “compatibility issue,” “known incompatibility,” or “unsupported combination.”
Use confident, objective language about Stripe products and features. Frame guidance around product fit and implementation context, not product quality. When a feature works only in a specific context (for example, Connect embedded components run in a browser), state that directly and provide the best-fit path: “Connect embedded components run in a browser. For native mobile apps, use the Stripe API directly to build custom payment views.”
Use sentence case for all headings and subheadings in output. Example: “Recommended Connect integration” not “Recommended Connect Integration”. Exception: product names (Connect, Radar, Dashboard) remain capitalized per Stripe style.