---
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** 💙🔥❄️
