Stripe Payment Integration
Production-ready Stripe integration for payments, subscriptions, and webhooks.
Payment Flows
| Flow | Use Case | PCI Burden |
|---|
| Checkout Session | Hosted page, fastest setup | Minimal |
| Payment Intents | Custom UI, full control | Requires Stripe.js |
| Setup Intents | Save card for later | Minimal |
Quick Start - Checkout Session
import stripe
stripe.api_key = "sk_test_..."
session = stripe.checkout.Session.create(
payment_method_types=['card'],
line_items=[{
'price_data': {
'currency': 'usd',
'product_data': {'name': 'Premium Plan'},
'unit_amount': 2000, # $20.00 in cents
'recurring': {'interval': 'month'},
},
'quantity': 1,
}],
mode='subscription',
success_url='https://example.com/success?session_id={CHECKOUT_SESSION_ID}',
cancel_url='https://example.com/cancel',
)
# Redirect to session.url
Custom Payment Intent Flow
# Backend: Create payment intent
def create_payment_intent(amount, customer_id=None):
intent = stripe.PaymentIntent.create(
amount=amount, # In cents
currency='usd',
customer=customer_id,
automatic_payment_methods={'enabled': True},
)
return intent.client_secret
// Frontend: Confirm payment
const stripe = Stripe('pk_test_...');
const {error, paymentIntent} = await stripe.confirmCardPayment(
clientSecret,
{payment_method: {card: cardElement}}
);
Webhook Handling
@app.route('/webhook', methods=['POST'])
def webhook():
payload = request.data
sig = request.headers.get('Stripe-Signature')
try:
event = stripe.Webhook.construct_event(
payload, sig, 'whsec_...'
)
except stripe.error.SignatureVerificationError:
return 'Invalid signature', 400
if event['type'] == 'payment_intent.succeeded':
handle_payment_success(event['data']['object'])
elif event['type'] == 'customer.subscription.deleted':
handle_subscription_canceled(event['data']['object'])
return 'OK', 200
Critical Webhook Events
| Event | When to Handle |
|---|
payment_intent.succeeded | Payment completed |
payment_intent.payment_failed | Payment failed |
customer.subscription.updated | Subscription changed |
customer.subscription.deleted | Subscription canceled |
invoice.payment_succeeded | Subscription payment OK |
Subscription Management
# Create subscription
subscription = stripe.Subscription.create(
customer=customer_id,
items=[{'price': 'price_xxx'}],
payment_behavior='default_incomplete',
expand=['latest_invoice.payment_intent'],
)
# Customer portal for self-service
session = stripe.billing_portal.Session.create(
customer=customer_id,
return_url='https://example.com/account',
)
# Redirect to session.url
Refunds
# Full refund
stripe.Refund.create(payment_intent='pi_xxx')
# Partial refund
stripe.Refund.create(
payment_intent='pi_xxx',
amount=500, # $5.00
reason='requested_by_customer'
)
Test Cards
| Card Number | Result |
|---|
4242424242424242 | Success |
4000000000000002 | Declined |
4000002500003155 | 3D Secure required |
4000000000009995 | Insufficient funds |
Best Practices
- Always use webhooks - Don't rely on client-side confirmation
- Idempotency - Handle webhook events exactly once
- Metadata - Link Stripe objects to your database
- Test mode - Test all flows before production
- PCI compliance - Never handle raw card data server-side
- SCA - Implement 3D Secure for European payments
Common Pitfalls
- Not verifying webhook signatures
- Hardcoding amounts (use cents!)
- Missing webhook event handlers
- No retry logic for API calls
- Skipping test card scenarios
