Stripe

You are integrating Stripe as a payment gateway into a [Django / Next.js / etc.] application.

## Setup
1. Install the Stripe SDK: `pip install stripe` (Python) or `npm install stripe` (Node.js)
2. Store your API keys in environment variables — NEVER hardcode them:
   - `STRIPE_PUBLIC_KEY` (publishable key, starts with `pk_`)
   - `STRIPE_SECRET_KEY` (secret key, starts with `sk_`)
   - `STRIPE_WEBHOOK_SECRET` (webhook signing secret, starts with `whsec_`)
3. Validate keys on application startup to catch test/live mismatches early.

## Recommended Integration: Stripe Checkout (Hosted)
For most use cases, use Stripe Checkout — it's PCI-compliant out of the box, handles 3D Secure, and supports 40+ payment methods:

```python
import stripe
stripe.api_key = settings.STRIPE_SECRET_KEY

session = stripe.checkout.Session.create(
    payment_method_types=['card'],
    line_items=[{
        'price_data': {
            'currency': 'usd',
            'product_data': {'name': 'Product Name'},
            'unit_amount': 2000,  # $20.00 in cents
        },
        'quantity': 1,
    }],
    mode='payment',  # or 'subscription' for recurring
    success_url='https://yourdomain.com/success?session_id={CHECKOUT_SESSION_ID}',
    cancel_url='https://yourdomain.com/cancel',
    metadata={'order_id': 'your_internal_id'},
)
```

## Webhook Handling (Critical)
Never rely solely on the success redirect — always confirm payment via webhooks:

1. Register your webhook endpoint in the Stripe Dashboard
2. Listen for `checkout.session.completed` and `payment_intent.succeeded`
3. ALWAYS verify the webhook signature:
```python
import stripe

def webhook_handler(request):
    payload = request.body
    sig_header = request.META.get('HTTP_STRIPE_SIGNATURE')
    try:
        event = stripe.Webhook.construct_event(payload, sig_header, settings.STRIPE_WEBHOOK_SECRET)
    except (ValueError, stripe.error.SignatureVerificationError):
        return HttpResponse(status=400)
    
    if event['type'] == 'checkout.session.completed':
        session = event['data']['object']
        # Fulfill the order using session.metadata['order_id']
    
    return HttpResponse(status=200)
```
4. Implement idempotency: track processed event IDs to prevent duplicate fulfillment
5. Return 200 quickly, then process asynchronously

## Security Best Practices
- Use Stripe Elements or Checkout — never collect raw card data on your server
- Enable Radar for automated fraud screening (included with standard pricing)
- Set up 3D Secure (Stripe handles this automatically with Checkout)
- Use HTTPS everywhere — Stripe rejects HTTP endpoints
- Implement Content Security Policy headers allowing Stripe's domains
- Use idempotency keys for all state-changing API calls to prevent duplicate charges

## Testing
- Use test mode keys (prefix `sk_test_` / `pk_test_`)
- Test card numbers: `4242424242424242` (success), `4000000000000002` (decline)
- Use Stripe CLI for local webhook testing: `stripe listen --forward-to localhost:8000/webhooks/stripe/`
- Test edge cases: failed payments, expired cards, 3DS challenges, disputes

## Common Gotchas
- Metadata does NOT auto-copy across all related objects — explicitly pass it
- Amounts are in the smallest currency unit (cents for USD, so $10 = 1000)
- International cards add 1.5% + optional 1% currency conversion on top of base rate
- Webhook endpoints must respond within 20 seconds or Stripe will retry
- Don't forget to handle `payment_intent.payment_failed` for declined payments