stripe-integration

Stripe Integration Skill

Critical Rule

Always use the latest Stripe API version: 2026-03-25.dahlia unless the user explicitly requests otherwise.

---

Step 1: Choose the Right Stripe API

Building…	Recommended API
One-time payments with hosted UI	Checkout Sessions
Custom payment form embedded in your page	Checkout Sessions + Payment Element
Saving payment method for later	Setup Intents
Marketplace or platform	Accounts v2 (/v2/core/accounts)
Subscriptions / recurring billing	Billing APIs + Checkout Sessions
Embedded banking / financial accounts	Treasury v2

When in doubt, start with Checkout Sessions - it handles PCI compliance, 3D Secure, and local payment methods automatically.

---

Step 2: Initial Setup

Install SDK

# Python
pip install stripe

# Node.js
npm install stripe

# Go
go get github.com/stripe/stripe-go/v76

Configure SDK

# Python
import stripe
stripe.api_key = os.environ["STRIPE_SECRET_KEY"]  # never hardcode
stripe.api_version = "2026-03-25.dahlia"

// TypeScript / Node.js
import Stripe from 'stripe'
const stripe = new Stripe(process.env.STRIPE_SECRET_KEY!, {
  apiVersion: '2026-03-25.dahlia',
})

---

Step 3: One-Time Payments (Checkout Sessions)

// Server: Create session
const session = await stripe.checkout.sessions.create({
  payment_method_types: ['card'],
  line_items: [{
    price_data: {
      currency: 'usd',
      product_data: { name: 'Pro Plan' },
      unit_amount: 2000,  // $20.00 in cents
    },
    quantity: 1,
  }],
  mode: 'payment',
  success_url: 'https://example.com/success?session_id={CHECKOUT_SESSION_ID}',
  cancel_url: 'https://example.com/cancel',
})
return { url: session.url }  // redirect user to this URL

// After payment - verify via webhook, NOT success_url query param

---

Step 4: Subscriptions (Recurring Billing)

Step 4a: Create a Product and Price in Stripe Dashboard (or API)

const price = await stripe.prices.create({
  currency: 'usd',
  unit_amount: 1000,  // $10/month
  recurring: { interval: 'month' },
  product_data: { name: 'Pro Subscription' },
})