Integrating Stripe Payments in Python Web Applications Using Flask#

Understanding Essential Concepts#

Successful Stripe integration requires familiarity with key components and workflows:

• Payment Gateway: A service, like Stripe, that authorizes and processes online payments. It acts as an intermediary between the merchant’s website, the customer’s bank, and the merchant’s bank.
• API (Application Programming Interface): A set of rules and protocols that allows different software applications to communicate with each other. The Stripe API enables developers to programmatically create charges, manage customers, handle subscriptions, and access other Stripe features from their application’s backend.
• Stripe API Keys: Credentials used to authenticate requests to the Stripe API.
  • Publishable Key: Used on the client-side (frontend) to securely identify the account and create tokens without exposing sensitive information. It typically starts with pk_test_ or pk_live_.
  • Secret Key: Used on the server-side (backend) to make authenticated API calls for creating charges, refunds, etc. It must be kept confidential and never exposed in client-side code. It typically starts with sk_test_ or sk_live_.
• Payment Intents: The recommended API object for handling the lifecycle of a payment. It tracks the payment process, requiring confirmation when additional steps (like 3D Secure authentication) are needed. This modern approach improves handling complex payment flows compared to older methods like direct Charges.
• Stripe Elements: Customizable UI components for building payment forms. They are pre-built, secure, and handle sensitive card details, ensuring PCI compliance for the merchant. Elements securely send payment information directly to Stripe, providing a token or payment method ID to the server without sensitive data touching the application’s backend.
• Webhooks: Automated messages sent by Stripe to a specified endpoint in the application’s backend when certain events occur (e.g., a payment succeeds, a subscription renews, a refund is issued). Webhooks are crucial for handling asynchronous events and updating the application’s state based on actions happening within Stripe’s system.

Why Integrate Stripe with Flask?#

Combining Stripe’s payment processing capabilities with Flask’s simplicity and flexibility provides several advantages:

• Ease of Development: Flask is known for its minimalist design, allowing developers to build web applications quickly. Stripe’s comprehensive API documentation and Python library integrate seamlessly with Flask routes and logic.
• Security: Stripe handles the complexity of PCI compliance by providing secure methods for collecting payment information (like Stripe Elements) and processing transactions, reducing the burden on the application developer. Server-side integration using Flask ensures sensitive API keys remain protected.
• Feature Richness: Stripe offers a wide array of features beyond simple payments, including subscriptions, invoicing, fraud prevention (Radar), and reporting, all accessible via its API and manageable within a Flask application.
• Scalability: Both Flask and Stripe are designed to handle varying levels of traffic and transaction volume, making the combination suitable for applications ranging from small projects to large-scale services.

Prerequisites for Integration#

Before beginning the integration process, certain prerequisites must be in place:

• A working Python environment.
• Flask installed (pip install Flask).
• The official Stripe Python library installed (pip install stripe).
• A Stripe account (test mode is sufficient for development).
• Stripe API keys (publishable and secret keys) obtained from the Stripe Dashboard.
• (Optional but Recommended for webhooks) A tool like ngrok to expose the local development server to the internet for receiving webhook events during testing (pip install ngrok) or a deployed application endpoint.

Step-by-Step Flask and Stripe Integration (Payment Intents)#

This section outlines the process for integrating Stripe to handle a one-time payment using the Payment Intents API and Stripe Elements.

1
my_app/
2
├── app.py
3
└── templates/
4
    └── checkout.html

1
from flask import Flask, render_template, request, jsonify
2
import stripe
3
import os
4
from dotenv import load_dotenv
5

6
# Load environment variables from a .env file
7
load_dotenv()
8

9
app = Flask(__name__)
10

11
# Load Stripe API keys from environment variables
12
stripe.api_key = os.getenv('STRIPE_SECRET_KEY')
13
stripe_publishable_key = os.getenv('STRIPE_PUBLISHABLE_KEY')
14

15
@app.route('/')
16
def index():
17
    return render_template('index.html') # Or redirect to checkout
18

19
@app.route('/checkout')
20
def checkout():
21
    return render_template('checkout.html', stripe_publishable_key=stripe_publishable_key)
22

23
# Add other routes later
24

25
if __name__ == '__main__':
26
    app.run(debug=True)

1
STRIPE_SECRET_KEY=sk_test_YOUR_SECRET_KEY
2
STRIPE_PUBLISHABLE_KEY=pk_test_YOUR_PUBLISHABLE_KEY

1
<!DOCTYPE html>
2
<html>
3
<head>
4
    <title>Welcome</title>
5
</head>
6
<body>
7
    <h1>Welcome!</h1>
8
    <p><a href="/checkout">Go to Checkout</a></p>
9
</body>
10
</html>

1
<!DOCTYPE html>
2
<html>
3
<head>
4
    <title>Checkout</title>
5
    <script src="https://js.stripe.com/v3/"></script>
6
</head>
7
<body>
8
    <h1>Complete Your Purchase</h1>
9
    <form id="payment-form">
10
        <div id="card-element">
11
            <!-- Stripe Elements will create input elements here -->
12
        </div>
13
        <button id="submit">Pay</button>
14
        <div id="payment-message" role="alert">
15
            <!-- Display error or success messages here -->
16
        </div>
17
    </form>
18

19
    <script>
20
        const stripe = Stripe("{{ stripe_publishable_key }}");
21
        const elements = stripe.elements();
22
        const cardElement = elements.create('card');
23
        cardElement.mount('#card-element');
24

25
        const form = document.getElementById('payment-form');
26
        const paymentMessage = document.getElementById('payment-message');
27

28
        form.addEventListener('submit', async function(event) {
29
            event.preventDefault();
30

31
            // Disable button while processing
32
            document.getElementById('submit').disabled = true;
33

34
            // 1. Create a Payment Intent on the server
35
            const response = await fetch('/create-payment-intent', {
36
                method: 'POST',
37
                headers: {
38
                    'Content-Type': 'application/json',
39
                },
40
                body: JSON.stringify({ amount: 1000 }), // Example amount in cents (e.g., $10.00)
41
            });
42

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

45
            if (response.ok) {
46
                // 2. Confirm the card payment using the client secret
47
                const { error, paymentIntent } = await stripe.confirmCardPayment(clientSecret, {
48
                    payment_method: {
49
                        card: cardElement,
50
                    }
51
                });
52

53
                if (error) {
54
                    // Show error to the user
55
                    paymentMessage.textContent = error.message;
56
                    document.getElementById('submit').disabled = false; // Re-enable button
57
                } else {
58
                    // Show a success message or redirect
59
                    if (paymentIntent.status === 'succeeded') {
60
                        paymentMessage.textContent = 'Payment Succeeded!';
61
                        // You would typically redirect the user to a success page
62
                        // window.location.href = '/success';
63
                    } else {
64
                        paymentMessage.textContent = 'Payment status: ' + paymentIntent.status;
65
                    }
66
                }
67
            } else {
68
                 // Handle server-side error creating Payment Intent
69
                const errorData = await response.json();
70
                paymentMessage.textContent = 'Error creating Payment Intent: ' + (errorData.error || 'Unknown error');
71
                document.getElementById('submit').disabled = false; // Re-enable button
72
            }
73
        });
74
    </script>
75
</body>
76
</html>

1
@app.route('/create-payment-intent', methods=['POST'])
2
def create_payment():
3
    try:
4
        data = request.get_json()
5
        amount = data['amount'] # Amount in cents
6

7
        # Create a PaymentIntent with the order amount and currency
8
        intent = stripe.PaymentIntent.create(
9
            amount=amount,
10
            currency='usd', # Or your currency
11
            automatic_payment_methods={
12
                'enabled': True,
13
            },
14
            # Add metadata if needed (e.g., order_id)
15
            metadata={'integration_parameter': 'flask'}
16
        )
17
        return jsonify({
18
            'clientSecret': intent.client_secret
19
        })
20
    except Exception as e:
21
        return jsonify(error=str(e)), 403 # Use 403 or appropriate error code

1
# Use environment variable for webhook secret
2
webhook_secret = os.getenv('STRIPE_WEBHOOK_SECRET')
3

4
@app.route('/webhook', methods=['POST'])
5
def webhook():
6
    payload = request.data
7
    sig_header = request.headers.get('Stripe-Signature')
8
    event = None
9

10
    try:
11
        # Verify webhook signature
12
        event = stripe.Webhook.construct_event(
13
            payload, sig_header, webhook_secret
14
        )
15
    except ValueError as e:
16
        # Invalid payload
17
        return 'Invalid payload', 400
18
    except stripe.error.SignatureVerificationError as e:
19
        # Invalid signature
20
        return 'Invalid signature', 400
21

22
    # Handle the event
23
    if event['type'] == 'payment_intent.succeeded':
24
        payment_intent = event['data']['object'] # contains a stripe.PaymentIntent
25
        print('PaymentIntent was successful!')
26
        # TODO: Implement logic to fulfill the order
27
        # Example: Check payment_intent.metadata for order ID, update database, send email, etc.
28
        print(f"PaymentIntent ID: {payment_intent['id']}, Amount: {payment_intent['amount']}, Currency: {payment_intent['currency']}")
29
        # Access metadata: print(payment_intent.get('metadata', {}).get('order_id'))
30

31
    elif event['type'] == 'payment_method.attached':
32
        payment_method = event['data']['object'] # contains a stripe.PaymentMethod
33
        print('PaymentMethod was attached to a Customer!')
34
        # Can be used for saving cards for future payments
35

36
    # ... handle other event types
37
    # See https://stripe.com/docs/api/events/types
38

39
    return 'Success', 200

1
# ... other keys
2
STRIPE_WEBHOOK_SECRET=whsec_YOUR_WEBHOOK_SECRET

Real-World Considerations and Examples#

• Order Fulfillment: The primary logic for completing a purchase (e.g., updating inventory, creating a database record for the order, sending confirmation emails) should happen within the payment_intent.succeeded webhook handler. This ensures fulfillment occurs only after Stripe confirms the payment has cleared.
• Idempotency: Webhooks can occasionally be delivered more than once. Implement idempotency in your webhook handler to ensure that processing an event multiple times does not cause issues (e.g., accidentally fulfilling an order twice). Stripe provides an idempotency_key in the request header for this purpose, or you can track processed events in your database.
• Error Handling: Implement robust error handling on both the frontend (displaying user-friendly messages for card errors) and the backend (logging API errors, handling invalid requests).
• Customer Management: For recurring payments or saved cards, create Stripe Customer objects and associate Payment Methods with them.
• Metadata: Attach relevant metadata (like your internal order ID, customer ID) to Stripe objects (Payment Intents, Charges, Customers). This helps connect Stripe transactions back to your application’s data and is visible in the Stripe Dashboard. metadata={'order_id': 'ORD12345'}

1
# Example metadata added to PaymentIntent creation
2
intent = stripe.PaymentIntent.create(
3
    amount=amount,
4
    currency='usd',
5
    automatic_payment_methods={'enabled': True},
6
    metadata={'order_id': 'YOUR_INTERNAL_ORDER_ID', 'user_id': 'USER_ID'}
7
)
8

9
# Accessing metadata in webhook
10
if event['type'] == 'payment_intent.succeeded':
11
    payment_intent = event['data']['object']
12
    order_id = payment_intent.get('metadata', {}).get('order_id')
13
    user_id = payment_intent.get('metadata', {}).get('user_id')
14
    print(f"Payment for order {order_id} by user {user_id} succeeded.")
15
    # Use order_id to find and fulfill the order in your database

• Amount Representation: Stripe API amounts are specified in the smallest currency unit (e.g., cents for USD, yen for JPY). Ensure your application logic correctly converts currency amounts (e.g., multiplying dollar amounts by 100).
• HTTPS: Your production webhook endpoint must use HTTPS. Sensitive information could be intercepted otherwise.

Security Best Practices#

• Protect Secret Keys: Never expose your Stripe secret key on the client-side or embed it directly in your code. Use environment variables and load them securely on the server.
• Validate Webhook Signatures: Always verify the Stripe-Signature header in webhook requests using stripe.Webhook.construct_event. This prevents attackers from sending fake webhook events to your application.
• Use HTTPS: Ensure your entire application, especially pages handling payment information and webhook endpoints, is served over HTTPS.
• PCI Compliance: By using Stripe Elements and Stripe.js to handle card details directly in the customer’s browser, sensitive card data never touches your server, significantly reducing your PCI compliance scope.
• Logging and Monitoring: Implement logging for API requests, responses, and webhook events to aid in debugging and monitoring.

Key Takeaways#

• Integrating Stripe with Flask involves both server-side (Flask) and client-side (HTML, JavaScript) development.
• The Stripe Python library simplifies server-side interactions with the Stripe API.
• The Payment Intents API is the modern approach for handling one-time payments, managing the payment lifecycle.
• Stripe Elements provides secure, pre-built UI components for collecting payment details on the frontend, aiding PCI compliance.
• The client_secret acts as a bridge between the server-created Payment Intent and the client-side confirmation.
• Webhooks are essential for reliably handling asynchronous payment events (like payment_intent.succeeded) and triggering backend order fulfillment logic.
• Securely handle API keys using environment variables and validate webhook requests using the provided signature.
• Always use HTTPS for production environments.
• Stripe API amounts are in the smallest currency unit (e.g., cents).