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
This commit is contained in:
Claude
@@ -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
|
||||
|
||||
129
docs/skills/stripe-best-practices/SKILL.md
Normal file
129
docs/skills/stripe-best-practices/SKILL.md
Normal file
@@ -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** 💙🔥❄️
|
||||
Reference in New Issue
Block a user