From f41493689331d7f3699d48acd6c7327a00ee451d Mon Sep 17 00:00:00 2001 From: Claude Date: Thu, 9 Apr 2026 13:03:42 +0000 Subject: [PATCH] feat(skills): Add stripe-best-practices from Anthropic official - Source: anthropics/claude-plugins-official - Modern API guidance (CheckoutSessions over Charges) - Frontend integration priorities - Subscription/billing best practices - Added Firefrost/Arbiter context - Updated SKILLS-INDEX.md Chronicler #73 --- docs/skills/SKILLS-INDEX.md | 24 ++++ docs/skills/stripe-best-practices/SKILL.md | 129 +++++++++++++++++++++ 2 files changed, 153 insertions(+) create mode 100644 docs/skills/stripe-best-practices/SKILL.md diff --git a/docs/skills/SKILLS-INDEX.md b/docs/skills/SKILLS-INDEX.md index 55d5bab..7ac5c1c 100644 --- a/docs/skills/SKILLS-INDEX.md +++ b/docs/skills/SKILLS-INDEX.md @@ -169,6 +169,28 @@ --- +### stripe-best-practices +**Location:** `docs/skills/stripe-best-practices/SKILL.md` +**Source:** skill.fish (anthropics/claude-plugins-official) +**Triggers:** Stripe, payments, checkout, subscriptions, webhooks, billing, Arbiter payments + +**Purpose:** Official Anthropic guidance for Stripe integrations + +**What It Covers:** +- Modern vs deprecated APIs (CheckoutSessions vs Charges) +- Frontend integration priority (hosted checkout preferred) +- Subscription/billing best practices +- Connect platform guidance +- Dynamic payment methods + +**Read This When:** +- Reviewing Arbiter's Stripe integration +- Working on Task #87 (lifecycle handlers) +- Implementing new payment features +- Troubleshooting webhook issues + +--- + ### postgres-patterns **Location:** `docs/skills/postgres-patterns/SKILL.md` **Source:** skill.fish (affaan-m/everything-claude-code) @@ -329,6 +351,8 @@ docs/skills/ │ └── SKILL.md ├── postgres-patterns/ │ └── SKILL.md +├── stripe-best-practices/ +│ └── SKILL.md └── discord-automation/ (skill collection) ├── README.md ├── discord-create-channel.md diff --git a/docs/skills/stripe-best-practices/SKILL.md b/docs/skills/stripe-best-practices/SKILL.md new file mode 100644 index 0000000..a83ac11 --- /dev/null +++ b/docs/skills/stripe-best-practices/SKILL.md @@ -0,0 +1,129 @@ +--- +name: stripe-best-practices +description: | + Best practices for building Stripe integrations. Use when implementing + payment processing, checkout flows, subscriptions, webhooks, or any + Stripe API integration. Reference for Arbiter's payment system. +source: skill.fish (anthropics/claude-plugins-official) +--- + +# Stripe Integration Best Practices + +Official Anthropic guidance for Stripe integrations. + +--- + +## WHEN TO USE + +- Implementing payment processing +- Building checkout flows +- Setting up subscriptions +- Handling webhooks +- Reviewing Arbiter's Stripe integration +- Task #87 (lifecycle handlers) + +--- + +## KEY PRINCIPLES + +### Always Use Modern APIs + +| ✅ Use | ❌ Never Use | +|--------|-------------| +| CheckoutSessions | Charges API | +| PaymentIntents | Sources API | +| SetupIntents | Legacy Card Element | +| Payment Element | Tokens (unless necessary) | + +### API Priority + +1. **CheckoutSessions** — Primary for on-session payments (one-time + subscriptions) +2. **PaymentIntents** — For off-session payments or custom checkout state +3. **SetupIntents** — For saving payment methods for later + +### Frontend Priority + +1. **Stripe-hosted Checkout** — Preferred (what Arbiter uses) +2. **Embedded Checkout** — Good alternative +3. **Payment Element** — Only if advanced customization needed + +--- + +## SUBSCRIPTIONS & BILLING + +For recurring revenue (like Firefrost subscriptions): +- Use **Billing APIs** to plan integration +- Combine with **Stripe Checkout** for frontend +- Follow [Subscription Use Cases](https://stripe.com/docs/billing/subscriptions/overview) + +--- + +## BEST PRACTICES + +### Dynamic Payment Methods +Turn on in dashboard settings instead of passing specific `payment_method_types`. Stripe auto-selects based on user location, wallets, and preferences. + +### Saving Payment Methods +Use **SetupIntent API** — never Sources API. + +### Before Confirming Payment +If you need to inspect card details before payment (e.g., surcharging), use **Stripe Confirmation Tokens** — not `createPaymentMethod` or `createToken`. + +### PCI Compliance +Server-side raw PAN data requires proving PCI compliance. Point users migrating from other processors to Stripe's migration process. + +--- + +## CONNECT PLATFORMS + +If building a platform with fund flows: + +| Charge Type | When to Use | +|-------------|-------------| +| **Direct charges** | Stripe takes risk | +| **Destination charges** | Platform accepts liability | + +- Use `on_behalf_of` parameter to control merchant of record +- Never mix charge types +- Use controller properties (not outdated Standard/Express/Custom terms) + +--- + +## IMPORTANT LINKS + +- [Integration Options](https://stripe.com/docs/payments/online-payments) +- [API Tour](https://stripe.com/docs/api) +- [Go Live Checklist](https://stripe.com/docs/development/checklist) +- [Subscription Use Cases](https://stripe.com/docs/billing/subscriptions/overview) + +--- + +## FIREFROST CONTEXT + +**Arbiter's Current Implementation:** +- ✅ Uses Stripe Checkout (hosted) — correct approach +- ✅ Uses webhooks for subscription events +- Stripe keys in `.env` on Command Center + +**Task #87 (Lifecycle Handlers):** +- Cancellation handling +- Grace period management +- Chargeback processing +- Should follow these best practices + +**Subscription Tiers:** +| Tier | Price | Type | +|------|-------|------| +| Awakened | $1 | One-time | +| Elemental | $5/mo | Monthly | +| Knight | $10/mo | Monthly | +| Master | $15/mo | Monthly | +| Legend | $20/mo | Monthly | +| Sovereign | $50 | One-time | + +--- + +**Source:** skill.fish — anthropics/claude-plugins-official +**Added:** 2026-04-09 by Chronicler #73 + +**Fire + Frost + Foundation = Where Love Builds Legacy** 💙🔥❄️