Skip to main content
skill CX Codex

payment-integration · travisjneuman — Claude Code skill: payments and install

The payment-integration skill covers Stripe and RevenueCat integrations, subscription flows, and webhook handling. Use it when building payments or reviewing PCI scope.

MIT 139 installs ★ 114 updated 2026-10-25

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add travisjneuman/.claude --skill payment-integration -a claude-code
Open on GitHub

What payment-integration does

The skill covers payment processing and subscription billing for web and mobile apps. It explains Stripe Checkout, Elements, and PaymentIntents, subscription state changes, idempotent webhook processing, tax calculation, refunds, usage-based billing, and RevenueCat for mobile purchases. It also addresses pricing pages and failed-payment flows.

The included patterns show how to create a Stripe Checkout session on the server, redirect a client, enable tax and promotion codes, and expose subscription management. A separate webhook pattern treats Stripe events as the payment-status source and uses event IDs to prevent duplicate handling. The Stripe server example requires STRIPE_SECRET_KEY, and testing is meant for Stripe test mode rather than live payment methods.

What it helps with

  • set up Stripe Checkout for subscriptions
  • process Stripe webhooks without duplicate actions
  • sync subscription status with user accounts
  • configure tax, promotion codes, and refunds
  • connect RevenueCat for mobile purchases

Example prompts for the agent

  • Set up a Stripe subscription flow with Checkout, automatic tax, and promotion codes.
  • Design an idempotent Stripe webhook handler that updates a user’s subscription status.
  • Review the PCI scope for a payment flow using Stripe and RevenueCat.

How to install payment-integration

1Skills CLI (Vercel)

npx skills add travisjneuman/.claude --skill payment-integration -a claude-code

2Manually: put the files in place

~/.claude/skills/payment-integration/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/payment-integration/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about payment-integration

How do I install payment-integration in Claude Code?

Run npx skills add travisjneuman/.claude --skill payment-integration -a claude-code. The installed skill is available at ~/.claude/skills/payment-integration/SKILL.md.

What does payment-integration do?

It guides Stripe payment and subscription work, including Checkout, webhooks, tax, refunds, and PCI scope. It also covers RevenueCat for mobile subscriptions.

Why does the skill treat webhooks as the payment-status source?

A client-side payment confirmation is not enough to establish the final state. The server should process the Stripe event and use its ID to avoid handling the same webhook more than once.

Source text

SKILL.md · MIT
---
name: payment-integration
description: Stripe, RevenueCat, subscription billing, webhooks, PCI compliance, and tax. Use when integrating payments or subscriptions, handling payment webhooks, or reviewing billing and PCI scope.
---

# Payment Integration

## Overview

This skill covers implementing payment processing and subscription billing in web and mobile applications. It addresses Stripe integration (Checkout, Elements, PaymentIntents), subscription lifecycle management, webhook handling with idempotency, PCI compliance, metered and usage-based billing, tax calculation, refund processing, and RevenueCat for mobile subscriptions.

Use this skill when adding payment processing, building subscription billing, handling Stripe webhooks, implementing pricing pages, managing payment failures, or integrating mobile in-app purchases.

---

## Core Principles

1. **Never handle raw card data** - Use Stripe Elements or Checkout to keep card numbers off your servers entirely. This keeps you at PCI SAQ-A (the simplest compliance level) rather than SAQ-D.
2. **Webhooks are the source of truth** - Never trust client-side payment confirmation. A successful PaymentIntent on the client means nothing until your webhook handler confirms `payment_intent.succeeded`. Build your system around webhook events.
3. **Idempotency everywhere** - Webhooks can be delivered multiple times. Every webhook handler must be idempotent. Use Stripe's event ID as a deduplication key.
4. **Handle failure gracefully** - Payments fail for many reasons (insufficient funds, expired cards, fraud detection). Build retry flows, dunning emails, and graceful degradation into the subscription lifecycle.
5. **Test with Stripe's test mode** - Use test API keys, test card numbers, and test clocks for subscription lifecycle testing. Never test with real payment methods.

---

## Key Patterns

### Pattern 1: Stripe Checkout for Subscriptions

**When to use:** When you want Stripe to handle the entire checkout UI, including payment form, coupon codes, and tax calculation.

**Implementation:**

```typescript
// Server - Create Checkout Session
// app/api/checkout/route.ts
import Stripe from "stripe";
import { NextRequest, NextResponse } from "next/server";

const stripe = new Stripe(process.env.STRIPE_SECRET_KEY!, {
  apiVersion: "2024-06-20",
});

export async function POST(req: NextRequest) {
  const { priceId, userId, email } = await req.json();

  // Get or create Stripe customer
  let customerId = await getStripeCustomerId(userId);
  if (!customerId) {
    const customer = await stripe.customers.create({
      email,
      metadata: { userId },
    });
    customerId = customer.id;
    await saveStripeCustomerId(userId, customerId);
  }

  const session = await stripe.checkout.sessions.create({
    customer: customerId,
    mode: "subscription",
    line_items: [{ price: priceId, quantity: 1 }],
    success_url: `${process.env.NEXT_PUBLIC_URL}/dashboard?session_id={CHECKOUT_SESSION_ID}`,
    cancel_url: `${process.env.NEXT_PUBLIC_URL}/pricing`,
    subscription_data: {
      metadata: { userId },
      trial_period_days: 14,
    },
    // Enable automatic tax calculation
    automatic_tax: { enabled: true },
    // Allow promo codes
    allow_promotion_codes: true,
    // Collect billing address for tax
    billing_address_collection: "required",
    // Customer portal for self-service management
    customer_update: {
      address: "auto",
      name: "auto",
    },
    // Auto-renewal disclosure next to the pay button + express consent
    // (California ARL, FTC ROSCA). terms_of_service needs a ToS URL set in the Dashboard.
    custom_text: {
      submit: { message: "Renews automatically each month at the listed price after your 14-day trial until you cancel. Cancel anytime online in Billing settings." },
    },
    consent_collection: { terms_of_service: "required" },
  });

  return NextResponse.json({ url: session.url });
}
```

```tsx
// Client - Redirect to Checkout
function PricingCard({ plan }: { plan: PricingPlan }) {
  const [loading, setLoading] = useState(false);

  const handleSubscribe = async () => {
    setLoading(true);
    try {
      const res = await fetch("/api/checkout", {
        method: "POST",
        headers: { "Content-Type": "application/json" },
        body: JSON.stringify({
          priceId: plan.stripePriceId,
          userId: user.id,
          email: user.email,
        }),
      });

      const { url } = await res.json();
      window.location.href = url; // Redirect to Stripe Checkout
    } catch (error) {
      toast.error("Failed to start checkout");
    } finally {
      setLoading(false);
    }
  };

  return (
    <div className="pricing-card">
      <h3>{plan.name}</h3>
      <p className="price">${plan.price}/mo</p>
      <ul>
        {plan.features.map((f) => (
          <li key={f}>{f}</li>
        ))}
      </ul>
      {/* Renewal terms must sit next to the button (California ARL) */}
      <p className="renewal-terms">
        Free for 14 days, then ${plan.price}/mo, renewing automatically until you cancel.
        Cancel anytime online in Billing settings.
      </p>
      <button onClick={handleSubscribe} disabled={loading}>
        {loading ? "Redirecting..." : "Subscribe"}
      </button>
    </div>
  );
}
```

**Why:** Stripe Checkout handles PCI compliance, 3D Secure authentication, tax calculation, promo codes, and localization. Building your own checkout form is hundreds of hours of work and ongoing PCI compliance burden. Use Checkout unless you have a strong reason to build custom UI.

---

### Pattern 2: Webhook Handler with Idempotency

**When to use:** Every Stripe integration. Webhooks are the only reliable way to know payment status.

**Implementation:**

```typescript
// app/api/webhooks/stripe/route.ts
import Stripe from "stripe";
import { NextRequest, NextResponse } from "next/server";
import { headers } from "next/headers";

const stripe = new Stripe(process.env.STRIPE_SECRET_KEY!);

// Process each event type
const eventHandlers: Record<string, (event: Stripe.Event) => Promise<void>> = {
  "checkout.session.completed": async (event) => {
    const session = event.data.object as Stripe.Checkout.Session;
    const userId = session.metadata?.userId ?? session.subscription?.toString();

    await db.user.update({
      where: { stripeCustomerId: session.customer as string },
      data: {
        subscriptionId: session.subscription as string,
        subscriptionStatus: "active",
      },
    });
  },

  "customer.subscription.updated": async (event) => {
    const subscription = event.data.object as Stripe.Subscription;

    await db.user.update({
      where: { stripeCustomerId: subscription.customer as string },
      data: {
        subscriptionStatus: subscription.status,
        planId: subscription.items.data[0].price.id,
        currentPeriodEnd: new Date(subscription.current_period_end * 1000),
        cancelAtPeriodEnd: subscription.cancel_at_period_end,
      },
    });
  },

  "customer.subscription.deleted": async (event) => {
    const subscription = event.data.object as Stripe.Subscription;

    await db.user.update({
      where: { stripeCustomerId: subscription.customer as string },
      data: {
        subscriptionStatus: "canceled",
        planId: null,
      },
    });
  },

  "invoice.payment_failed": async (event) => {
    const invoice = event.data.object as Stripe.Invoice;

    await db.user.update({
      where: { stripeCustomerId: invoice.customer as string },
      data: { subscriptionStatus: "past_due" },
    });

    // Send dunning email
    await sendDunningEmail(invoice.customer as string, {
      amountDue: invoice.amount_due,
      nextRetry: invoice.next_payment_attempt
        ? new Date(invoice.next_payment_attempt * 1000)
        : null,
    });
  },

  "invoice.paid": async (event) => {
    const invoice = event.data.object as Stripe.Invoice;

    await db.user.update({
      where: { stripeCustomerId: invoice.customer as string },
      data: { subscriptionStatus: "active" },
    });
  },
};

export async function POST(req: NextRequest) {
  const body = await req.text();
  const signature = (await headers()).get("stripe-signature")!;

  let event: Stripe.Event;

  // 1. Verify webhook signature (prevents spoofing)
  try {
    event = stripe.webhooks.constructEvent(
      body,
      signature,
      process.env.STRIPE_WEBHOOK_SECRET!
    );
  } catch (err) {
    console.error("Webhook signature verification failed:", err);
    return NextResponse.json({ error: "Invalid signature" }, { status: 400 });
  }

  // 2. Idempotency check - skip already-processed events
  const alreadyProcessed = await db.stripeEvent.findUnique({
    where: { eventId: event.id },
  });

  if (alreadyProcessed) {
    return NextResponse.json({ received: true });
  }

  // 3. Process the event
  const handler = eventHandlers[event.type];
  if (handler) {
    try {
      await handler(event);

      // 4. Record processed event for idempotency
      await db.stripeEvent.create({
        data: {
          eventId: event.id,
          type: event.type,
          processedAt: new Date(),
        },
      });
    } catch (err) {
      console.error(`Error processing ${event.type}:`, err);
      // Return 500 so Stripe retries
      return NextResponse.json({ error: "Processing failed" }, { status: 500 });
    }
  }

  return NextResponse.json({ received: true });
}
```

**Why:** Stripe delivers webhooks at least once, meaning duplicates are possible. The idempotency check (storing processed event IDs) prevents double-processing. Signature verification prevents spoofed webhook attacks. Returning 500 on handler errors triggers Stripe's automatic retry with exponential backoff.

---

### Pattern 3: Customer Portal for Self-Service

**When to use:** Let customers manage their own subscriptions (upgrade, downgrade, cancel, update payment method) without contacting support.

**Implementation:**

```typescript
// Create portal session
// app/api/billing/portal/route.ts
export async function POST(req: NextRequest) {
  const { userId } = await req.json();

  const user = await db.user.findUniqueOrThrow({
    where: { id: userId },
    select: { stripeCustomerId: true },
  });

  if (!user.stripeCustomerId) {
    return NextResponse.json({ error: "No billing account" }, { status: 400 });
  }

  const session = await stripe.billingPortal.sessions.create({
    customer: user.stripeCustomerId,
    return_url: `${process.env.NEXT_PUBLIC_URL}/settings/billing`,
  });

  return NextResponse.json({ url: session.url });
}
```

```typescript
// Configure the portal in Stripe (do this once, via API or Dashboard)
await stripe.billingPortal.configurations.create({
  business_profile: {
    headline: "Manage your subscription",
  },
  features: {
    subscription_update: {
      enabled: true,
      default_allowed_updates: ["price", "quantity"],
      proration_behavior: "create_prorations",
      products: [
        {
          product: "prod_xxx",
          prices: ["price_monthly", "price_annual"],
        },
      ],
    },
    subscription_cancel: {
      enabled: true,
      mode: "at_period_end", // Don't cancel immediately
      cancellation_reason: {
        enabled: true,
        options: [
          "too_expensive",
          "missing_features",
          "switched_service",
          "unused",
          "other",
        ],
      },
    },
    payment_method_update: { enabled: true },
    invoice_history: { enabled: true },
  },
});
```

**Why:** Self-service billing reduces support tickets by 60-80%. Stripe's Customer Portal is a hosted solution that handles plan changes, proration, cancellation with reason capture, payment method updates, and invoice history -- all without building custom UI.

---

### Pattern 4: Usage-Based Billing

**When to use:** When pricing is based on consumption (API calls, storage, compute minutes, seats) rather than flat-rate subscriptions.

**Implementation:**

```typescript
// Report usage to Stripe
async function reportUsage(
  subscriptionItemId: string,
  quantity: number,
  timestamp?: number
): Promise<void> {
  await stripe.subscriptionItems.createUsageRecord(subscriptionItemId, {
    quantity,
    timestamp: timestamp ?? Math.floor(Date.now() / 1000),
    action: "increment", // Add to existing usage (vs "set" to replace)
  });
}

// Background job: aggregate and report usage hourly
async function reportHourlyUsage(): Promise<void> {
  const activeSubscriptions = await db.subscription.findMany({
    where: { status: "active", plan: { billingModel: "usage" } },
    include: { user: true },
  });

  for (const sub of activeSubscriptions) {
    const usage = await getHourlyUsage(sub.userId);

    if (usage > 0) {
      await reportUsage(sub.stripeSubscriptionItemId, usage);

      await db.usageReport.create({
        data: {
          subscriptionId: sub.id,
          quantity: usage,
          reportedAt: new Date(),
        },
      });
    }
  }
}

// Track usage in your application
async function trackApiCall(userId: string, endpoint: string): Promise<void> {
  // Increment usage counter (Redis for speed)
  const key = `usage:${userId}:${getCurrentHour()}`;
  await redis.incr(key);
  await redis.expire(key, 86400 * 7); // Keep for 7 days

  // Check if user is approaching their limit
  const currentUsage = await getCurrentMonthUsage(userId);
  const limit = await getUserPlanLimit(userId);

  if (currentUsage >= limit * 0.8) {
    await sendUsageWarningEmail(userId, currentUsage, limit);
  }

  if (currentUsage >= limit) {
    throw new UsageLimitExceededError(userId, currentUsage, limit);
  }
}
```

**Why:** Usage-based billing aligns cost with value -- customers pay for what they use. Hourly aggregation reduces API calls to Stripe while keeping usage data fresh enough for invoicing. Redis-based tracking provides sub-millisecond usage checks for rate limiting.

---

## Stripe Test Cards Reference

| Number | Scenario |
|---|---|
| `4242 4242 4242 4242` | Successful payment |
| `4000 0000 0000 3220` | 3D Secure required |
| `4000 0000 0000 9995` | Declined (insufficient funds) |
| `4000 0000 0000 0341` | Attaching to customer fails |
| `4000 0025 0000 3155` | Requires authentication |

Use any future expiry date and any 3-digit CVC.

---

## Anti-Patterns

| Anti-Pattern | Why It's Bad | Better Approach |
|---|---|---|
| Trusting client-side payment confirmation | Users can spoof success | Webhook handler is the source of truth |
| Handling raw card numbers on your server | PCI SAQ-D compliance (very expensive) | Use Stripe Elements or Checkout |
| No idempotency in webhook handlers | Double charges, duplicate provisioning | Deduplicate by event ID |
| Canceling subscriptions immediately | Users lose access mid-billing period | Cancel at period end (`cancel_at_period_end`) |
| Hardcoding prices in your app | Can't change pricing without deploy | Store price IDs in database or environment |
| No dunning flow for failed payments | Silent revenue loss (involuntary churn) | Automated retry + dunning emails |
| Testing with real payment methods | Risk of real charges, no test clocks | Use Stripe test mode exclusively |

---

## Checklist

- [ ] Stripe API keys stored in environment variables (never in code)
- [ ] Webhook signature verification enabled
- [ ] Webhook handler is idempotent (event ID deduplication)
- [ ] All subscription status changes handled (created, updated, canceled, past_due)
- [ ] Failed payment dunning flow implemented (email + retry)
- [ ] Customer portal configured for self-service billing
- [ ] Auto-renewal terms (price, frequency, trial end, how to cancel) shown next to the subscribe button; express consent captured; confirmation email repeats them
- [ ] Online cancellation as easy as signup (portal `subscription_cancel` enabled), no forced retention call (California ARL, FTC ROSCA)
- [ ] Test mode used for all development and staging
- [ ] PCI compliance level confirmed (SAQ-A with Stripe Checkout/Elements)
- [ ] Tax calculation enabled (Stripe Tax or external provider)
- [ ] Proration configured for plan changes (upgrade/downgrade)
- [ ] Webhook endpoint registered in Stripe Dashboard
- [ ] Stripe CLI installed for local webhook testing (`stripe listen --forward-to`)

---

## Related Resources

- **Skills:** `authentication-patterns` (user identity for billing), `email-systems` (dunning emails)
- **Skills:** `monitoring-observability` (payment failure alerting)
- **Rules:** `docs/reference/stacks/fullstack-nextjs-nestjs.md` (API route patterns)

© travisjneuman · MIT · travisjneuman/.claude

Similar skills

All skills for Backend and APIs →

payment-integration by other authors comes first.

payment-integration mrgoonie payment-integration is a Claude Code skill for adding payment providers and wiring up checkout and webhooks. It covers subscriptions, QR payments, and orders handled across multiple providers. CX Codex +1 361installs payment-gateway-integration aj-geddes payment-gateway-integration — a Claude Code skill that wires Stripe, PayPal and Square into backends: payments, subscriptions, webhooks, refunds. Also works in Codex, Cursor, Copilot, Gemini CLI and OpenCode. CX Codex +1 531installs payment-processing Seth Hobson payment-processing — a plugin for Claude Code, Codex and Cursor sets up Stripe and PayPal gateway integration, implements checkout flows and subscription billing. Triggers when you work on payment logic in your project. CX Codex ★ 42,780repo stars stripe-integration Seth Hobson The stripe-integration skill covers Stripe Checkout, subscriptions, webhooks, refunds, and saved payment methods. Use it when a project needs one-time or recurring payments. CX Codex +1 13,404installs stripe-integration-expert borghei stripe-integration-expert is a Claude Code skill for building Stripe billing integrations for SaaS, covering subscriptions, webhooks, and local testing with Stripe CLI. CX Codex +1 116installs web-payments alinaqi web-payments — a skill for adding Stripe payment forms to web apps: one-time transactions, recurring subscriptions, webhooks, and customer portal. Use it when you need to accept payments in your project. CX Codex +1 302installs payment-testing kindlmann payment-testing — a testing skill for end-to-end payment flows against Stripe, Adyen, and PayPal sandboxes. Helps automate card declines, 3DS challenges, and webhook verification. CX Codex +1 1,300installs

From the same set117

The whole set →
generic-react-feature-developer generic-react-feature-developer is a Claude Code skill that defines React feature architecture, including directory layout, Zustand, React Query, IndexedDB, and lazy loading. CX Codex +1 139installs svelte-development The svelte-development Claude Code skill covers Svelte 5 and SvelteKit development. It applies to reactive components, SvelteKit routing and server functions, and upgrades from Svelte 4. CX Codex +1 139installs llm-app-development llm-app-development — a skill for Claude Code guides the design of RAG pipelines, autonomous agents, and structured schemas. Triggers when building chatbots, retrieval systems, or LLM-driven tools. CX Codex +1 139installs product-analytics product-analytics architects event tracking, funnels, cohorts, and privacy-compliant instrumentation for PostHog, Amplitude, Mixpanel, and Segment. CX Codex +1 139installs generic-static-feature-developer generic-static-feature-developer guides feature work on plain HTML, CSS and JS sites: vanilla patterns, a GitHub Actions deploy and checks before you commit. CX Codex +1 139installs customer-success customer-success guides engineering workflows for customer support systems, knowledge bases, ticketing integrations, and health metrics. CX Codex +1 138installs test-specialist test-specialist — a Claude Code skill that supplies test patterns for JS/TS, Python, Go, and Rust. Activates only when you explicitly ask for tests or coverage targets. CX Codex +1 138installs battle-card-builder battle-card-builder builds sales battle cards, competitive comparisons, and structured objection scripts using an 8-part framework. CX Codex +1 137installs

Project sponsors

Companies that keep this analytics open