From 389d6f5982d7e0c9716f603b155ad68311c9b4c3 Mon Sep 17 00:00:00 2001 From: Ashwin Mathews Date: Sat, 14 Mar 2026 00:15:49 -0700 Subject: [PATCH 1/4] stripe skills init --- plugins/stripe/skills/.gitkeep | 0 .../skills/stripe-best-practices/SKILL.md | 27 +++ .../references/billing.md | 23 +++ .../references/connect.md | 47 +++++ .../references/payments.md | 62 ++++++ .../references/treasury.md | 15 ++ plugins/stripe/skills/upgrade-stripe/SKILL.md | 177 ++++++++++++++++++ 7 files changed, 351 insertions(+) create mode 100644 plugins/stripe/skills/.gitkeep create mode 100644 plugins/stripe/skills/stripe-best-practices/SKILL.md create mode 100644 plugins/stripe/skills/stripe-best-practices/references/billing.md create mode 100644 plugins/stripe/skills/stripe-best-practices/references/connect.md create mode 100644 plugins/stripe/skills/stripe-best-practices/references/payments.md create mode 100644 plugins/stripe/skills/stripe-best-practices/references/treasury.md create mode 100644 plugins/stripe/skills/upgrade-stripe/SKILL.md diff --git a/plugins/stripe/skills/.gitkeep b/plugins/stripe/skills/.gitkeep new file mode 100644 index 00000000..e69de29b diff --git a/plugins/stripe/skills/stripe-best-practices/SKILL.md b/plugins/stripe/skills/stripe-best-practices/SKILL.md new file mode 100644 index 00000000..c7eb81c1 --- /dev/null +++ b/plugins/stripe/skills/stripe-best-practices/SKILL.md @@ -0,0 +1,27 @@ +--- +name: stripe-best-practices +description: Guides Stripe integration decisions — API selection (Checkout Sessions vs PaymentIntents), Connect platform setup (Accounts v2, controller properties), billing/subscriptions, Treasury financial accounts, integration surfaces (Checkout, Payment Element), and migrating from deprecated Stripe APIs. Use when building, modifying, or reviewing any Stripe integration — including accepting payments, building marketplaces, integrating Stripe, processing payments, setting up subscriptions, or creating connected accounts. +--- + +Latest Stripe API version: **2026-02-25.clover**. Always use the latest API version and SDK unless the user specifies otherwise. + +## Integration routing + +| Building... | Recommended API | Details | +|---|---|---| +| One-time payments | Checkout Sessions | [references/payments.md](references/payments.md) | +| Custom payment form with embedded UI | Checkout Sessions + Payment Element | [references/payments.md](references/payments.md) | +| Saving a payment method for later | Setup Intents | [references/payments.md](references/payments.md) | +| Connect platform or marketplace | Accounts v2 (`/v2/core/accounts`) | [references/connect.md](references/connect.md) | +| Subscriptions or recurring billing | Billing APIs + Checkout Sessions | [references/billing.md](references/billing.md) | +| Embedded financial accounts / banking | v2 Financial Accounts | [references/treasury.md](references/treasury.md) | + +Read the relevant reference file before answering any integration question or writing code. + +## Key documentation + +When the user's request does not clearly fit a single domain above, consult: + +- [Integration Options](https://docs.stripe.com/payments/payment-methods/integration-options.md) — Start here when designing any integration. +- [API Tour](https://docs.stripe.com/payments-api/tour.md) — Overview of Stripe's API surface. +- [Go Live Checklist](https://docs.stripe.com/get-started/checklist/go-live.md) — Review before launching. diff --git a/plugins/stripe/skills/stripe-best-practices/references/billing.md b/plugins/stripe/skills/stripe-best-practices/references/billing.md new file mode 100644 index 00000000..ef520ad6 --- /dev/null +++ b/plugins/stripe/skills/stripe-best-practices/references/billing.md @@ -0,0 +1,23 @@ +# Billing / Subscriptions + +## Table of contents +- When to use Billing APIs +- Recommended frontend pairing +- Traps to avoid + +## When to use Billing APIs + +If the user has a recurring revenue model (subscriptions, usage-based billing, seat-based pricing), use the Billing APIs to [plan their integration](https://docs.stripe.com/billing/subscriptions/designing-integration.md) instead of a direct PaymentIntent integration. + +Review the [Subscription Use Cases](https://docs.stripe.com/billing/subscriptions/use-cases.md) and [SaaS guide](https://docs.stripe.com/saas.md) to find the right pattern for the user's pricing model. + +## Recommended frontend pairing + +Combine Billing APIs with Stripe Checkout for the payment frontend. Checkout Sessions support `mode: 'subscription'` and handle the initial payment, trial management, and proration automatically. + +For self-service subscription management (upgrades, downgrades, cancellation, payment method updates), recommend the [Customer Portal](https://docs.stripe.com/customer-management/integrate-customer-portal.md). + +## Traps to avoid + +- Do not build manual subscription renewal loops using raw PaymentIntents. Use the Billing APIs which handle renewal, retry logic, and dunning automatically. +- Do not use the deprecated `plan` object. Use [Prices](https://docs.stripe.com/api/prices.md) instead. diff --git a/plugins/stripe/skills/stripe-best-practices/references/connect.md b/plugins/stripe/skills/stripe-best-practices/references/connect.md new file mode 100644 index 00000000..39eeb49e --- /dev/null +++ b/plugins/stripe/skills/stripe-best-practices/references/connect.md @@ -0,0 +1,47 @@ +# Connect / Platforms + +## Table of contents +- Accounts v2 API +- Controller properties +- Charge types +- Integration guides + +## Accounts v2 API + +For new Connect platforms, ALWAYS use the [Accounts v2 API](https://docs.stripe.com/connect/accounts-v2.md) (`POST /v2/core/accounts`). This is Stripe's actively invested path and ensures long-term support. + +**Traps to avoid:** Do not use the legacy `type` parameter (`type: 'express'`, `type: 'custom'`, `type: 'standard'`) in `POST /v1/accounts` for new platforms unless the user has explicitly requested v1. + +## Controller properties + +Configure connected accounts using `controller` properties instead of legacy account types: + +| Property | Controls | +|---|---| +| `controller.losses.payments` | Who is liable for negative balances | +| `controller.fees.payer` | Who pays Stripe fees | +| `controller.stripe_dashboard.type` | Dashboard access (`full`, `express`, `none`) | +| `controller.requirement_collection` | Who collects onboarding requirements | + +Use `defaults.responsibilities`, `dashboard`, and `configuration` as described in [connected account configuration](https://docs.stripe.com/connect/accounts-v2/connected-account-configuration.md). + +Always describe accounts in terms of their responsibility settings, dashboard access, and [capabilities](https://docs.stripe.com/connect/account-capabilities.md) to describe what connected accounts can do. + +**Traps to avoid:** Do not use the terms "Standard", "Express", or "Custom" as account types. These are legacy categories that bundle together responsibility, dashboard, and requirement decisions into opaque labels. Controller properties give explicit control over each dimension. + +## Charge types + +Choose one charge type per integration — do not mix them. For most platforms, start with destination charges: + +- **Destination charges** — Use when the platform accepts liability for negative balances. Funds route to the connected account via `transfer_data.destination`. +- **Direct charges** — Use when the platform wants Stripe to take risk on the connected account. The charge is created on the connected account directly. + +Use `on_behalf_of` to control the merchant of record, but only after reading [how charges work in Connect](https://docs.stripe.com/connect/charges.md). + +**Traps to avoid:** Do not use the Charges API for Connect fund flows — use PaymentIntents or Checkout Sessions with `transfer_data` or `on_behalf_of`. Do not mix charge types within a single integration. + +## Integration guides + +- [SaaS platforms and marketplaces guide](https://docs.stripe.com/connect/saas-platforms-and-marketplaces.md) — Choosing the right integration shape. +- [Interactive platform guide](https://docs.stripe.com/connect/interactive-platform-guide.md) — Step-by-step platform builder. +- [Design an integration](https://docs.stripe.com/connect/design-an-integration.md) — Detailed risk and responsibility decisions. diff --git a/plugins/stripe/skills/stripe-best-practices/references/payments.md b/plugins/stripe/skills/stripe-best-practices/references/payments.md new file mode 100644 index 00000000..06be6931 --- /dev/null +++ b/plugins/stripe/skills/stripe-best-practices/references/payments.md @@ -0,0 +1,62 @@ +# Payments + +## Table of contents +- API hierarchy +- Integration surfaces +- Payment Element guidance +- Saving payment methods +- Dynamic payment methods +- Deprecated APIs and migration paths +- PCI compliance + +## API hierarchy + +Use the [Checkout Sessions API](https://docs.stripe.com/api/checkout/sessions.md) (`checkout.sessions.create`) for on-session payments. It supports one-time payments and subscriptions and handles taxes, discounts, shipping, and adaptive pricing automatically. + +Use the [PaymentIntents API](https://docs.stripe.com/payments/paymentintents/lifecycle.md) for off-session payments, or when the merchant needs to model checkout state independently and just create a charge. + +**Integrations should only use Checkout Sessions, PaymentIntents, SetupIntents, or higher-level solutions (Invoicing, Payment Links, subscription APIs).** + +## Integration surfaces + +Prioritize Stripe-hosted or embedded Checkout where possible. Use in this order of preference: + +1. **Payment Links** — No-code. Best for simple products. +2. **Checkout** ([docs](https://docs.stripe.com/payments/checkout.md)) — Stripe-hosted or embedded form. Best for most web apps. +3. **Payment Element** ([docs](https://docs.stripe.com/payments/payment-element.md)) — Embedded UI component for advanced customization. + - When using the Payment Element, back it with the Checkout Sessions API (via `ui_mode: 'custom'`) over a raw PaymentIntent where possible. + +**Traps to avoid:** Do not recommend the legacy Card Element or the Payment Element in card-only mode. If the user asks for the Card Element, advise them to [migrate to the Payment Element](https://docs.stripe.com/payments/payment-element/migration.md). + +## Payment Element guidance + +For surcharging or inspecting card details before payment (e.g., rendering the Payment Element before creating a PaymentIntent or SetupIntent): use [Confirmation Tokens](https://docs.stripe.com/payments/finalize-payments-on-the-server.md). Do not recommend `createPaymentMethod` or `createToken` from Stripe.js. + +## Saving payment methods + +Use the [Setup Intents API](https://docs.stripe.com/api/setup_intents.md) to save a payment method for later use. + +**Traps to avoid:** Do not use the Sources API to save cards to customers. The Sources API is deprecated — Setup Intents is the correct approach. + +## Dynamic payment methods + +Advise users to enable dynamic payment methods in the Stripe Dashboard rather than passing specific [`payment_method_types`](https://docs.stripe.com/api/payment_intents/create#create_payment_intent-payment_method_types.md) in the PaymentIntent or SetupIntent. Stripe automatically selects payment methods based on the customer's location, wallets, and preferences when the Payment Element is used. + +## Deprecated APIs and migration paths + +Never recommend the Charges API. If the user wants to use the Charges API, advise them to [migrate to Checkout Sessions or PaymentIntents](https://docs.stripe.com/payments/payment-intents/migration/charges.md). + +Do not call other deprecated or outdated API endpoints unless there is a specific need and absolutely no other way. + +| API | Status | Use instead | Migration guide | +|---|---|---|---| +| Charges API | Never use | Checkout Sessions or PaymentIntents | [Migration guide](https://docs.stripe.com/payments/payment-intents/migration/charges.md) | +| Sources API | Deprecated | Setup Intents | [Setup Intents docs](https://docs.stripe.com/api/setup_intents.md) | +| Tokens API | Outdated | Setup Intents or Checkout Sessions | — | +| Card Element | Legacy | Payment Element | [Migration guide](https://docs.stripe.com/payments/payment-element/migration.md) | + +## PCI compliance + +If a PCI-compliant user asks about sending server-side raw PAN data, advise them that they may need to prove PCI compliance to access options like [payment_method_data](https://docs.stripe.com/api/payment_intents/create#create_payment_intent-payment_method_data.md). + +For users migrating PAN data from another acquirer or payment processor, point them to [the PAN import process](https://docs.stripe.com/get-started/data-migrations/pan-import.md). diff --git a/plugins/stripe/skills/stripe-best-practices/references/treasury.md b/plugins/stripe/skills/stripe-best-practices/references/treasury.md new file mode 100644 index 00000000..6b39ef9d --- /dev/null +++ b/plugins/stripe/skills/stripe-best-practices/references/treasury.md @@ -0,0 +1,15 @@ +# Treasury / Financial Accounts + +## Table of contents +- v2 Financial Accounts API +- Legacy v1 Treasury + +## v2 Financial Accounts API + +For embedded financial accounts (bank accounts, account and routing numbers, money movement), use the [v2 Financial Accounts API](https://docs.stripe.com/api/v2/core/vault/financial-accounts.md) (`POST /v2/core/vault/financial_accounts`). This is required for new integrations. + +For Treasury concepts and guides, see the [Treasury overview](https://docs.stripe.com/treasury.md). + +## Legacy v1 Treasury + +Do not use the [v1 Treasury Financial Accounts API](https://docs.stripe.com/api/treasury/financial_accounts.md) (`POST /v1/treasury/financial_accounts`) for new integrations. Existing v1 integrations continue to work. diff --git a/plugins/stripe/skills/upgrade-stripe/SKILL.md b/plugins/stripe/skills/upgrade-stripe/SKILL.md new file mode 100644 index 00000000..8c7a8ce2 --- /dev/null +++ b/plugins/stripe/skills/upgrade-stripe/SKILL.md @@ -0,0 +1,177 @@ +--- +name: upgrade-stripe +description: Guide for upgrading Stripe API versions and SDKs +alwaysApply: false +--- + +The latest Stripe API version is 2026-02-25.clover - use this version when upgrading unless the user specifies a different target version. + +# Upgrading Stripe Versions + +This guide covers upgrading Stripe API versions, server-side SDKs, Stripe.js, and mobile SDKs. + +## Understanding Stripe API Versioning + +Stripe uses date-based API versions (e.g., `2026-02-25.clover`, `2025-08-27.basil`, `2024-12-18.acacia`). Your account's API version determines request/response behavior. + +### Types of Changes + +**Backward-Compatible Changes** (do not require code updates): +- New API resources +- New optional request parameters +- New properties in existing responses +- Changes to opaque string lengths (e.g., object IDs) +- New webhook event types + +**Breaking Changes** (require code updates): +- Field renames or removals +- Behavioral modifications +- Removed endpoints or parameters + +Review the [API Changelog](https://docs.stripe.com/changelog.md) for all changes between versions. + +## Server-Side SDK Versioning + +See [SDK Version Management](https://docs.stripe.com/sdks/set-version.md) for details. + +### Dynamically-Typed Languages (Ruby, Python, PHP, Node.js) + +These SDKs offer flexible version control: + +**Global Configuration:** +```python +import stripe +stripe.api_version = '2026-02-25.clover' +``` + +```ruby +Stripe.api_version = '2026-02-25.clover' +``` + +```javascript +const stripe = require('stripe')('sk_test_xxx', { + apiVersion: '2026-02-25.clover' +}); +``` + +**Per-Request Override:** +```python +stripe.Customer.create( + email="customer@example.com", + stripe_version='2026-02-25.clover' +) +``` + +### Strongly-Typed Languages (Java, Go, .NET) + +These use a fixed API version matching the SDK release date. Do not set a different API version for strongly-typed languages because response objects might not match the strong types in the SDK. Instead, update the SDK to target a new API version. + +### Best Practice + +Always specify the API version you're integrating against in your code instead of relying on your account's default API version: + +```javascript +// Good: Explicit version +const stripe = require('stripe')('sk_test_xxx', { + apiVersion: '2026-02-25.clover' +}); + +// Avoid: Relying on account default +const stripe = require('stripe')('sk_test_xxx'); +``` + +## Stripe.js Versioning + +See [Stripe.js Versioning](https://docs.stripe.com/sdks/stripejs-versioning.md) for details. + +Stripe.js uses an evergreen model with major releases (Acacia, Basil, Clover) on a biannual basis. + +### Loading Versioned Stripe.js + +**Via Script Tag:** +```html + +``` + +**Via npm:** +```bash +npm install @stripe/stripe-js +``` + +Major npm versions correspond to specific Stripe.js versions. + +### API Version Pairing + +Each Stripe.js version automatically pairs with its corresponding API version. For instance: +- Clover Stripe.js uses `2026-02-25.clover` API +- Acacia Stripe.js uses `2024-12-18.acacia` API + +You cannot override this association. + +### Migrating from v3 + +1. Identify your current API version in code +2. Review the changelog for relevant changes +3. Consider gradually updating your API version before switching Stripe.js versions +4. Stripe continues supporting v3 indefinitely + +## Mobile SDK Versioning + +See [Mobile SDK Versioning](https://docs.stripe.com/sdks/mobile-sdk-versioning.md) for details. + +### iOS and Android SDKs + +Both platforms follow **semantic versioning** (MAJOR.MINOR.PATCH): +- **MAJOR**: Breaking API changes +- **MINOR**: New functionality (backward-compatible) +- **PATCH**: Bug fixes (backward-compatible) + +New features and fixes release only on the latest major version. Upgrade regularly to access improvements. + +### React Native SDK + +Uses a different model (0.x.y schema): +- **Minor version changes** (x): Breaking changes AND new features +- **Patch updates** (y): Critical bug fixes only + +### Backend Compatibility + +All mobile SDKs work with any Stripe API version you use on your backend unless documentation specifies otherwise. + +## Upgrade Checklist + +1. Review the [API Changelog](https://docs.stripe.com/changelog.md) for changes between your current and target versions +2. Check [Upgrades Guide](https://docs.stripe.com/upgrades.md) for migration guidance +3. Update server-side SDK package version (e.g., `npm update stripe`, `pip install --upgrade stripe`) +4. Update the `apiVersion` parameter in your Stripe client initialization +5. Test your integration against the new API version using the `Stripe-Version` header +6. Update webhook handlers to handle new event structures +7. Update Stripe.js script tag or npm package version if needed +8. Update mobile SDK versions in your package manager if needed +9. Store Stripe object IDs in databases that accommodate up to 255 characters (case-sensitive collation) + +## Testing API Version Changes + +Use the `Stripe-Version` header to test your code against a new version without changing your default: + +```bash +curl https://api.stripe.com/v1/customers \ + -u sk_test_xxx: \ + -H "Stripe-Version: 2026-02-25.clover" +``` + +Or in code: + +```javascript +const stripe = require('stripe')('sk_test_xxx', { + apiVersion: '2026-02-25.clover' // Test with new version +}); +``` + +## Important Notes + +- Your webhook listener should handle unfamiliar event types gracefully +- Test webhooks with the new version structure before upgrading +- Breaking changes are tagged by affected product areas (Payments, Billing, Connect, etc.) +- Multiple API versions coexist simultaneously, enabling staged adoption + From 93d78e5fc397ec00794006067ff87835998d199f Mon Sep 17 00:00:00 2001 From: Ashwin Mathews Date: Sat, 14 Mar 2026 00:21:56 -0700 Subject: [PATCH 2/4] plugin and mcp --- plugins/stripe/.codex-plugin/plugin.json | 2 ++ plugins/stripe/.mcp.json | 8 ++++++++ 2 files changed, 10 insertions(+) create mode 100644 plugins/stripe/.mcp.json diff --git a/plugins/stripe/.codex-plugin/plugin.json b/plugins/stripe/.codex-plugin/plugin.json index 232abaa5..ed7de335 100644 --- a/plugins/stripe/.codex-plugin/plugin.json +++ b/plugins/stripe/.codex-plugin/plugin.json @@ -9,6 +9,8 @@ "repository": "https://github.com/openai/plugins", "license": "MIT", "keywords": [], + "skills": "./skills/", + "mcpServers": "./.mcp.json", "apps": "./.app.json", "interface": { "displayName": "Stripe", diff --git a/plugins/stripe/.mcp.json b/plugins/stripe/.mcp.json new file mode 100644 index 00000000..b8250f93 --- /dev/null +++ b/plugins/stripe/.mcp.json @@ -0,0 +1,8 @@ +{ + "mcpServers": { + "stripe": { + "type": "streamable_http", + "url": "https://mcp.stripe.com" + } + } +} From 0b4e5f72e45ce6ec6d355aa949b081aaae450c26 Mon Sep 17 00:00:00 2001 From: Ashwin Mathews Date: Wed, 18 Mar 2026 15:49:24 -0700 Subject: [PATCH 3/4] remove mcp --- plugins/stripe/.codex-plugin/plugin.json | 1 - plugins/stripe/.mcp.json | 8 -------- 2 files changed, 9 deletions(-) delete mode 100644 plugins/stripe/.mcp.json diff --git a/plugins/stripe/.codex-plugin/plugin.json b/plugins/stripe/.codex-plugin/plugin.json index ed7de335..a255d7d2 100644 --- a/plugins/stripe/.codex-plugin/plugin.json +++ b/plugins/stripe/.codex-plugin/plugin.json @@ -10,7 +10,6 @@ "license": "MIT", "keywords": [], "skills": "./skills/", - "mcpServers": "./.mcp.json", "apps": "./.app.json", "interface": { "displayName": "Stripe", diff --git a/plugins/stripe/.mcp.json b/plugins/stripe/.mcp.json deleted file mode 100644 index b8250f93..00000000 --- a/plugins/stripe/.mcp.json +++ /dev/null @@ -1,8 +0,0 @@ -{ - "mcpServers": { - "stripe": { - "type": "streamable_http", - "url": "https://mcp.stripe.com" - } - } -} From 122918976c82d6fea061199f9a3366dbec460b2b Mon Sep 17 00:00:00 2001 From: Ashwin Mathews Date: Wed, 18 Mar 2026 15:50:51 -0700 Subject: [PATCH 4/4] rm gitkeep --- plugins/stripe/skills/.gitkeep | 0 1 file changed, 0 insertions(+), 0 deletions(-) delete mode 100644 plugins/stripe/skills/.gitkeep diff --git a/plugins/stripe/skills/.gitkeep b/plugins/stripe/skills/.gitkeep deleted file mode 100644 index e69de29b..00000000