# /specweave-payments:stripe-setup

Complete Stripe integration setup guide with production-ready code templates, security best practices, and testing workflows.

You are a payment integration expert who implements secure, PCI-compliant Stripe payment systems.

## Your Task

Set up complete Stripe payment integration with checkout flows, webhook handling, subscription billing, and customer management.

### 1. Environment Setup

**Install Dependencies**:

```bash
# Node.js
npm install stripe @stripe/stripe-js dotenv

# Python
pip install stripe python-dotenv

# Ruby
gem install stripe dotenv

# PHP
composer require stripe/stripe-php vlucas/phpdotenv
```

**Environment Variables**:

```bash
# .env (NEVER commit this file!)
# Get keys from https://dashboard.stripe.com/apikeys

# Test mode (development)
STRIPE_PUBLISHABLE_KEY=pk_test_51...
STRIPE_SECRET_KEY=sk_test_51...
STRIPE_WEBHOOK_SECRET=whsec_...

# Live mode (production)
# STRIPE_PUBLISHABLE_KEY=pk_live_51...
# STRIPE_SECRET_KEY=sk_live_51...
# STRIPE_WEBHOOK_SECRET=whsec_...

# App configuration
STRIPE_SUCCESS_URL=https://yourdomain.com/success
STRIPE_CANCEL_URL=https://yourdomain.com/cancel
STRIPE_CURRENCY=usd
```

### 2. Backend Setup (Node.js/Express)

**Stripe Client Initialization**:

```typescript
// src/config/stripe.ts
import Stripe from 'stripe';
import dotenv from 'dotenv';

dotenv.config();

if (!process.env.STRIPE_SECRET_KEY) {
  throw new Error('STRIPE_SECRET_KEY is not set in environment variables');
}

export const stripe = new Stripe(process.env.STRIPE_SECRET_KEY, {
  apiVersion: '2023-10-16',
  typescript: true,
  maxNetworkRetries: 2,
  timeout: 10000, // 10 seconds
});

export const STRIPE_CONFIG = {
  publishableKey: process.env.STRIPE_PUBLISHABLE_KEY!,
  webhookSecret: process.env.STRIPE_WEBHOOK_SECRET!,
  successUrl: process.env.STRIPE_SUCCESS_URL || 'http://localhost:3000/success',
  cancelUrl: process.env.STRIPE_CANCEL_URL || 'http://localhost:3000/cancel',
  currency: process.env.STRIPE_CURRENCY || 'usd',
};
```

**Payment Service**:

```typescript
// src/services/payment.service.ts
import { stripe } from '../config/stripe';
import type Stripe from 'stripe';

export class PaymentService {
  /**
   * Create a one-time payment checkout session
   */
  async createCheckoutSession(params: {
    amount: number;
    currency?: string;
    customerId?: string;
    metadata?: Record<string, string>;
  }): Promise<Stripe.Checkout.Session> {
    try {
      const session = await stripe.checkout.sessions.create({
        payment_method_types: ['card'],
        line_items: [
          {
            price_data: {
              currency: params.currency || 'usd',
              product_data: {
                name: 'Payment',
                description: 'One-time payment',
              },
              unit_amount: params.amount, // Amount in cents
            },
            quantity: 1,
          },
        ],
        mode: 'payment',
        success_url: `${process.env.STRIPE_SUCCESS_URL}?session_id={CHECKOUT_SESSION_ID}`,
        cancel_url: process.env.STRIPE_CANCEL_URL,
        customer: params.customerId,
        metadata: params.metadata,
        // Enable automatic tax calculation (optional)
        automatic_tax: { enabled: false },
        // Customer email collection
        customer_email: params.customerId ? undefined : '',
      });

      return session;
    } catch (error) {
      console.error('Failed to create checkout session:', error);
      throw new Error('Payment session creation failed');
    }
  }

  /**
   * Create a payment intent for custom checkout UI
   */
  async createPaymentIntent(params: {
    amount: number;
    currency?: string;
    customerId?: string;
    paymentMethodTypes?: string[];
    metadata?: Record<string, string>;
  }): Promise<Stripe.PaymentIntent> {
    try {
      const paymentIntent = await stripe.paymentIntents.create({
        amount: params.amount,
        currency: params.currency || 'usd',
        customer: params.customerId,
        payment_method_types: params.paymentMethodTypes || ['card'],
        metadata: params.metadata,
        // Automatic payment methods (enables more payment methods)
        automatic_payment_methods: {
          enabled: true,
          allow_redirects: 'never', // or 'always' for redirect-based methods
        },
      });

      return paymentIntent;
    } catch (error) {
      console.error('Failed to create payment intent:', error);
      throw new Error('Payment intent creation failed');
    }
  }

  /**
   * Retrieve a payment intent
   */
  async getPaymentIntent(paymentIntentId: string): Promise<Stripe.PaymentIntent> {
    try {
      return await stripe.paymentIntents.retrieve(paymentIntentId);
    } catch (error) {
      console.error('Failed to retrieve payment intent:', error);
      throw new Error('Payment intent retrieval failed');
    }
  }

  /**
   * Confirm a payment intent (server-side confirmation)
   */
  async confirmPaymentIntent(
    paymentIntentId: string,
    paymentMethodId: string
  ): Promise<Stripe.PaymentIntent> {
    try {
      return await stripe.paymentIntents.confirm(paymentIntentId, {
        payment_method: paymentMethodId,
      });
    } catch (error) {
      console.error('Failed to confirm payment intent:', error);
      throw new Error('Payment confirmation failed');
    }
  }

  /**
   * Create or update a customer
   */
  async createCustomer(params: {
    email: string;
    name?: string;
    phone?: string;
    metadata?: Record<string, string>;
    paymentMethodId?: string;
  }): Promise<Stripe.Customer> {
    try {
      const customer = await stripe.customers.create({
        email: params.email,
        name: params.name,
        phone: params.phone,
        metadata: params.metadata,
        payment_method: params.paymentMethodId,
        invoice_settings: params.paymentMethodId
          ? {
              default_payment_method: params.paymentMethodId,
            }
          : undefined,
      });

      return customer;
    } catch (error) {
      console.error('Failed to create customer:', error);
      throw new Error('Customer creation failed');
    }
  }

  /**
   * Attach a payment method to a customer
   */
  async attachPaymentMethod(
    paymentMethodId: string,
    customerId: string,
    setAsDefault = true
  ): Promise<Stripe.PaymentMethod> {
    try {
      // Attach payment method
      const paymentMethod = await stripe.paymentMethods.attach(paymentMethodId, {
        customer: customerId,
      });

      // Set as default if requested
      if (setAsDefault) {
        await stripe.customers.update(customerId, {
          invoice_settings: {
            default_payment_method: paymentMethodId,
          },
        });
      }

      return paymentMethod;
    } catch (error) {
      console.error('Failed to attach payment method:', error);
      throw new Error('Payment method attachment failed');
    }
  }

  /**
   * List customer payment methods
   */
  async listPaymentMethods(customerId: string): Promise<Stripe.PaymentMethod[]> {
    try {
      const paymentMethods = await stripe.paymentMethods.list({
        customer: customerId,
        type: 'card',
      });

      return paymentMethods.data;
    } catch (error) {
      console.error('Failed to list payment methods:', error);
      throw new Error('Payment method listing failed');
    }
  }

  /**
   * Create a refund
   */
  async createRefund(params: {
    paymentIntentId?: string;
    chargeId?: string;
    amount?: number; // Partial refund amount in cents
    reason?: 'duplicate' | 'fraudulent' | 'requested_by_customer';
    metadata?: Record<string, string>;
  }): Promise<Stripe.Refund> {
    try {
      const refund = await stripe.refunds.create({
        payment_intent: params.paymentIntentId,
        charge: params.chargeId,
        amount: params.amount,
        reason: params.reason,
        metadata: params.metadata,
      });

      return refund;
    } catch (error) {
      console.error('Failed to create refund:', error);
      throw new Error('Refund creation failed');
    }
  }
}

export const paymentService = new PaymentService();
```

**Express API Routes**:

```typescript
// src/routes/payment.routes.ts
import { Router, Request, Response } from 'express';
import { paymentService } from '../services/payment.service';

const router = Router();

/**
 * POST /api/payments/checkout
 * Create a checkout session
 */
router.post('/checkout', async (req: Request, res: Response) => {
  try {
    const { amount, currency, customerId, metadata } = req.body;

    // Validate amount
    if (!amount || amount <= 0) {
      return res.status(400).json({ error: 'Invalid amount' });
    }

    const session = await paymentService.createCheckoutSession({
      amount,
      currency,
      customerId,
      metadata,
    });

    res.json({ sessionId: session.id, url: session.url });
  } catch (error) {
    console.error('Checkout error:', error);
    res.status(500).json({ error: 'Failed to create checkout session' });
  }
});

/**
 * POST /api/payments/intent
 * Create a payment intent for custom UI
 */
router.post('/intent', async (req: Request, res: Response) => {
  try {
    const { amount, currency, customerId, metadata } = req.body;

    if (!amount || amount <= 0) {
      return res.status(400).json({ error: 'Invalid amount' });
    }

    const paymentIntent = await paymentService.createPaymentIntent({
      amount,
      currency,
      customerId,
      metadata,
    });

    res.json({ clientSecret: paymentIntent.client_secret });
  } catch (error) {
    console.error('Payment intent error:', error);
    res.status(500).json({ error: 'Failed to create payment intent' });
  }
});

/**
 * POST /api/payments/customers
 * Create a customer
 */
router.post('/customers', async (req: Request, res: Response) => {
  try {
    const { email, name, phone, metadata } = req.body;

    if (!email) {
      return res.status(400).json({ error: 'Email is required' });
    }

    const customer = await paymentService.createCustomer({
      email,
      name,
      phone,
      metadata,
    });

    res.json({ customerId: customer.id });
  } catch (error) {
    console.error('Customer creation error:', error);
    res.status(500).json({ error: 'Failed to create customer' });
  }
});

/**
 * POST /api/payments/refunds
 * Create a refund
 */
router.post('/refunds', async (req: Request, res: Response) => {
  try {
    const { paymentIntentId, amount, reason, metadata } = req.body;

    if (!paymentIntentId) {
      return res.status(400).json({ error: 'Payment Intent ID is required' });
    }

    const refund = await paymentService.createRefund({
      paymentIntentId,
      amount,
      reason,
      metadata,
    });

    res.json({ refundId: refund.id, status: refund.status });
  } catch (error) {
    console.error('Refund error:', error);
    res.status(500).json({ error: 'Failed to create refund' });
  }
});

/**
 * GET /api/payments/config
 * Get public Stripe configuration
 */
router.get('/config', (req: Request, res: Response) => {
  res.json({
    publishableKey: process.env.STRIPE_PUBLISHABLE_KEY,
  });
});

export default router;
```

### 3. Frontend Setup (React)

**Stripe Provider**:

```typescript
// src/providers/StripeProvider.tsx
import React from 'react';
import { Elements } from '@stripe/react-stripe-js';
import { loadStripe, Stripe } from '@stripe/stripe-js';

// Load Stripe.js outside of component to avoid recreating the instance
let stripePromise: Promise<Stripe | null>;

const getStripe = () => {
  if (!stripePromise) {
    const publishableKey = process.env.NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY || '';
    stripePromise = loadStripe(publishableKey);
  }
  return stripePromise;
};

interface StripeProviderProps {
  children: React.ReactNode;
}

export const StripeProvider: React.FC<StripeProviderProps> = ({ children }) => {
  return (
    <Elements stripe={getStripe()}>
      {children}
    </Elements>
  );
};
```

**Payment Form Component**:

```typescript
// src/components/PaymentForm.tsx
import React, { useState } from 'react';
import {
  useStripe,
  useElements,
  CardElement,
  PaymentElement,
} from '@stripe/react-stripe-js';
import type { StripeError } from '@stripe/stripe-js';

interface PaymentFormProps {
  amount: number;
  currency?: string;
  onSuccess: (paymentIntentId: string) => void;
  onError: (error: string) => void;
  customerId?: string;
  metadata?: Record<string, string>;
}

export const PaymentForm: React.FC<PaymentFormProps> = ({
  amount,
  currency = 'usd',
  onSuccess,
  onError,
  customerId,
  metadata,
}) => {
  const stripe = useStripe();
  const elements = useElements();
  const [loading, setLoading] = useState(false);
  const [error, setError] = useState<string | null>(null);

  const handleSubmit = async (event: React.FormEvent) => {
    event.preventDefault();

    if (!stripe || !elements) {
      // Stripe.js hasn't loaded yet
      return;
    }

    setLoading(true);
    setError(null);

    try {
      // Create payment intent on backend
      const response = await fetch('/api/payments/intent', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({
          amount,
          currency,
          customerId,
          metadata,
        }),
      });

      const { clientSecret } = await response.json();

      // Confirm payment with Stripe.js
      const { error: stripeError, paymentIntent } = await stripe.confirmCardPayment(
        clientSecret,
        {
          payment_method: {
            card: elements.getElement(CardElement)!,
            billing_details: {
              // Add billing details if collected
            },
          },
        }
      );

      if (stripeError) {
        setError(stripeError.message || 'Payment failed');
        onError(stripeError.message || 'Payment failed');
      } else if (paymentIntent && paymentIntent.status === 'succeeded') {
        onSuccess(paymentIntent.id);
      }
    } catch (err) {
      const errorMessage = err instanceof Error ? err.message : 'Payment failed';
      setError(errorMessage);
      onError(errorMessage);
    } finally {
      setLoading(false);
    }
  };

  return (
    <form onSubmit={handleSubmit} className="max-w-md mx-auto p-6">
      <div className="mb-6">
        <label className="block text-sm font-medium text-gray-700 mb-2">
          Card Details
        </label>
        <div className="border border-gray-300 rounded-lg p-3">
          <CardElement
            options={{
              style: {
                base: {
                  fontSize: '16px',
                  color: '#424770',
                  '::placeholder': {
                    color: '#aab7c4',
                  },
                },
                invalid: {
                  color: '#9e2146',
                },
              },
            }}
          />
        </div>
      </div>

      {error && (
        <div className="mb-4 p-3 bg-red-50 border border-red-200 rounded-lg text-red-700 text-sm">
          {error}
        </div>
      )}

      <button
        type="submit"
        disabled={!stripe || loading}
        className="w-full bg-blue-600 text-white py-3 px-4 rounded-lg font-medium hover:bg-blue-700 disabled:bg-gray-400 disabled:cursor-not-allowed transition-colors"
      >
        {loading ? 'Processing...' : `Pay $${(amount / 100).toFixed(2)}`}
      </button>
    </form>
  );
};
```

**Checkout Session Flow**:

```typescript
// src/components/CheckoutButton.tsx
import React, { useState } from 'react';
import { loadStripe } from '@stripe/stripe-js';

const stripePromise = loadStripe(process.env.NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY!);

interface CheckoutButtonProps {
  amount: number;
  currency?: string;
  buttonText?: string;
}

export const CheckoutButton: React.FC<CheckoutButtonProps> = ({
  amount,
  currency = 'usd',
  buttonText = 'Checkout',
}) => {
  const [loading, setLoading] = useState(false);

  const handleCheckout = async () => {
    setLoading(true);

    try {
      // Create checkout session
      const response = await fetch('/api/payments/checkout', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({ amount, currency }),
      });

      const { sessionId } = await response.json();

      // Redirect to Stripe Checkout
      const stripe = await stripePromise;
      if (stripe) {
        const { error } = await stripe.redirectToCheckout({ sessionId });
        if (error) {
          console.error('Checkout error:', error);
        }
      }
    } catch (error) {
      console.error('Checkout error:', error);
    } finally {
      setLoading(false);
    }
  };

  return (
    <button
      onClick={handleCheckout}
      disabled={loading}
      className="bg-blue-600 text-white py-2 px-6 rounded-lg font-medium hover:bg-blue-700 disabled:bg-gray-400 disabled:cursor-not-allowed transition-colors"
    >
      {loading ? 'Loading...' : buttonText}
    </button>
  );
};
```

### 4. Testing

**Test Cards**:

```typescript
// Test card numbers for different scenarios
export const TEST_CARDS = {
  // Success
  VISA_SUCCESS: '4242424242424242',
  VISA_DEBIT: '4000056655665556',
  MASTERCARD: '5555555555554444',

  // Authentication required
  THREE_D_SECURE: '4000002500003155',

  // Failure scenarios
  CARD_DECLINED: '4000000000000002',
  INSUFFICIENT_FUNDS: '4000000000009995',
  LOST_CARD: '4000000000009987',
  STOLEN_CARD: '4000000000009979',
  EXPIRED_CARD: '4000000000000069',
  INCORRECT_CVC: '4000000000000127',
  PROCESSING_ERROR: '4000000000000119',

  // Special cases
  DISPUTE: '4000000000000259',
  FRAUD: '4100000000000019',
};

// Any future expiry date (e.g., 12/34)
// Any 3-digit CVC
// Any postal code
```

**Integration Test**:

```typescript
// tests/integration/payment.test.ts
import { paymentService } from '../../src/services/payment.service';
import Stripe from 'stripe';

describe('Payment Service Integration', () => {
  describe('Payment Intent', () => {
    it('should create a payment intent', async () => {
      const paymentIntent = await paymentService.createPaymentIntent({
        amount: 1000,
        currency: 'usd',
      });

      expect(paymentIntent).toBeDefined();
      expect(paymentIntent.amount).toBe(1000);
      expect(paymentIntent.currency).toBe('usd');
      expect(paymentIntent.status).toBe('requires_payment_method');
    });

    it('should confirm payment intent with test card', async () => {
      // Create payment intent
      const paymentIntent = await paymentService.createPaymentIntent({
        amount: 1000,
        currency: 'usd',
      });

      // Create test payment method
      const stripe = new Stripe(process.env.STRIPE_SECRET_KEY!);
      const paymentMethod = await stripe.paymentMethods.create({
        type: 'card',
        card: {
          number: '4242424242424242',
          exp_month: 12,
          exp_year: 2034,
          cvc: '123',
        },
      });

      // Confirm payment
      const confirmed = await paymentService.confirmPaymentIntent(
        paymentIntent.id,
        paymentMethod.id
      );

      expect(confirmed.status).toBe('succeeded');
    });
  });

  describe('Customer Management', () => {
    it('should create a customer', async () => {
      const customer = await paymentService.createCustomer({
        email: 'test@example.com',
        name: 'Test User',
      });

      expect(customer).toBeDefined();
      expect(customer.email).toBe('test@example.com');
    });

    it('should attach payment method to customer', async () => {
      const stripe = new Stripe(process.env.STRIPE_SECRET_KEY!);

      // Create customer
      const customer = await paymentService.createCustomer({
        email: 'test@example.com',
      });

      // Create payment method
      const paymentMethod = await stripe.paymentMethods.create({
        type: 'card',
        card: {
          number: '4242424242424242',
          exp_month: 12,
          exp_year: 2034,
          cvc: '123',
        },
      });

      // Attach payment method
      const attached = await paymentService.attachPaymentMethod(
        paymentMethod.id,
        customer.id
      );

      expect(attached.customer).toBe(customer.id);
    });
  });

  describe('Refunds', () => {
    it('should create a refund', async () => {
      // First create and confirm a payment
      const paymentIntent = await paymentService.createPaymentIntent({
        amount: 1000,
        currency: 'usd',
      });

      const stripe = new Stripe(process.env.STRIPE_SECRET_KEY!);
      const paymentMethod = await stripe.paymentMethods.create({
        type: 'card',
        card: {
          number: '4242424242424242',
          exp_month: 12,
          exp_year: 2034,
          cvc: '123',
        },
      });

      await paymentService.confirmPaymentIntent(paymentIntent.id, paymentMethod.id);

      // Create refund
      const refund = await paymentService.createRefund({
        paymentIntentId: paymentIntent.id,
        reason: 'requested_by_customer',
      });

      expect(refund).toBeDefined();
      expect(refund.status).toBe('succeeded');
    });
  });
});
```

### 5. Security Checklist

**Backend Security**:
- [ ] NEVER log full card numbers or CVV
- [ ] Use HTTPS only (enforce TLS 1.2+)
- [ ] Validate webhook signatures
- [ ] Implement rate limiting on payment endpoints
- [ ] Store Stripe IDs, not card details
- [ ] Use environment variables for keys
- [ ] Implement idempotency keys for retries
- [ ] Sanitize user inputs
- [ ] Enable CSRF protection
- [ ] Use secure session management

**Frontend Security**:
- [ ] Use Stripe.js (never raw card inputs)
- [ ] Load Stripe.js from CDN (integrity check)
- [ ] Never send card data to your server
- [ ] Implement CSP headers
- [ ] Use HTTPS only
- [ ] Clear sensitive data from memory
- [ ] Disable autocomplete on card fields
- [ ] Implement proper error handling

**Monitoring**:
- [ ] Log all payment attempts
- [ ] Monitor failed payment rates
- [ ] Set up alerts for unusual activity
- [ ] Track refund rates
- [ ] Monitor webhook delivery
- [ ] Implement fraud detection

### 6. Production Deployment

**Pre-launch Checklist**:

1. **Update API Keys**:
   - Switch from test keys (`sk_test_`, `pk_test_`) to live keys
   - Update webhook endpoint with live webhook secret
   - Test with live mode in Stripe Dashboard

2. **Webhook Configuration**:
   ```bash
   # Register webhook in Stripe Dashboard
   # URL: https://yourdomain.com/api/webhooks/stripe
   # Events: payment_intent.succeeded, payment_intent.payment_failed,
   #         customer.subscription.*, charge.refunded
   ```

3. **Enable Radar** (fraud detection):
   - Configure Radar rules in Stripe Dashboard
   - Enable 3D Secure for high-risk payments
   - Set up risk score thresholds

4. **Tax Configuration**:
   - Enable Stripe Tax if needed
   - Configure tax rates by location
   - Set up tax reporting

5. **Business Verification**:
   - Complete business verification in Stripe
   - Add business information
   - Verify bank account for payouts

6. **Monitoring**:
   - Set up Sentry or similar for error tracking
   - Configure log aggregation (Datadog, Splunk)
   - Set up uptime monitoring for webhook endpoint
   - Create alerts for failed payments

## Output Deliverables

When you complete this setup, provide:

1. **Configured Files**:
   - `.env` template with all required variables
   - Backend service with payment methods
   - API routes with error handling
   - Frontend components (PaymentForm, CheckoutButton)

2. **Documentation**:
   - API endpoint documentation
   - Testing guide with test cards
   - Deployment checklist
   - Security audit report

3. **Testing**:
   - Integration tests for payment flows
   - Test scenarios for edge cases
   - Webhook handling tests

4. **Deployment**:
   - Environment-specific configurations
   - Database migration scripts (if storing payment records)
   - Monitoring setup guide

## Resources

- **Stripe Documentation**: https://stripe.com/docs
- **Stripe.js Reference**: https://stripe.com/docs/js
- **Webhook Testing**: Use Stripe CLI (`stripe listen --forward-to localhost:3000/api/webhooks/stripe`)
- **Test Cards**: https://stripe.com/docs/testing

## Best Practices

1. **Always use Stripe.js** for card collection (PCI compliance)
2. **Verify webhooks** with signature validation
3. **Handle errors gracefully** with user-friendly messages
4. **Test thoroughly** with all test cards before production
5. **Monitor payment success rates** and investigate drops
6. **Implement retry logic** for API failures
7. **Use metadata** to link payments to your database records
8. **Never expose secret keys** in frontend code
9. **Implement idempotency** for payment operations
10. **Keep Stripe.js updated** to latest version

Start with test mode, verify all flows work correctly, then switch to live mode with the same code.