DEV Community: Francisco Macedo

Integrating Stripe Into A One-Product Django Python Shop

Francisco Macedo — Wed, 18 Sep 2024 12:10:37 +0000

In the first part of this series, we created a Django online shop with htmx.

In this second part, we'll handle orders using Stripe.

What We'll Do

We'll integrate Stripe to handle payments securely. This is what we want to achieve:

In the purchase view, we start by creating a Stripe checkout session and redirect the customer to the corresponding URL. This is where we tell Stripe about the product we are selling, its quantity, and where the customer should be redirected to after a successful purchase (the success_url).
The customer fills in their payment details on the Stripe checkout page and completes the payment. Stripe then makes a POST request to a webhook endpoint on our website, where we listen to events and process them accordingly. If the payment is successful, we save the order in our database and notify the customer (and our staff users) about the purchase.
Finally, if the webhook returns a response with a 200 OK HTTP status code, Stripe redirects to the success_url created in the first step.

Setting Up Stripe for Our Django Python Store

We first need to jump over to Stripe and do the following:

1: Create a Stripe Account

Start by creating a Stripe account. For now, you don’t really need to activate your account. You can just work in test mode, which will prevent you from making real payments while testing. Go to the API keys page and retrieve the publishable and secret keys. Save them in your project environment variables (STRIPE_PUBLISHABLE_KEY and STRIPE_SECRET_KEY). We will use these keys to authenticate your Stripe requests.

2: Create Your Product

Create a new product on the products page. Fill out the details and set the payment type to one-off. Your product should look something like this:

Once you press Add product, you should be able to see your product on the product list. If you click on it and scroll down to the Pricing section, you can find the API ID for the price item you created — it should be something like price_3ODP5…. Save it in an environment variable (STRIPE_PRICE_ID): you will need this when creating the Stripe checkout session.

3: Create the Webhook

We need to create a webhook endpoint for Stripe to call when a payment completes. In the webhooks page, choose to test in the local environment. This will allow you to forward the request to a local URL, like http://127.0.0.1:8000. Start by downloading the Stripe CLI. Then, you can:

Log into Stripe

stripe login

Forward events to the webhook endpoint that you will create:

stripe listen --forward-to http://127.0.0.1:8000/webhook
> Ready! Your webhook signing secret is whsec_06531a7ba22363ac038f284ac547906b89e5c939f8d55dfd03a3619f9adc590a (^C to quit)

This ensures that once a purchase is made, Stripe forwards the webhook calls to your local endpoint. The command will log a webhook signing secret, which you should also save as a project environment variable (STRIPE_WEBHOOK_SECRET). This will prove useful for verifying that a request does indeed come from Stripe and that you are handling the right webhook.

By the end of this section, you should have four Stripe environment variables. You can now load them in ecommerce_site/settings.py:

# ecommerce_site/settings.py

import os
from dotenv import load_dotenv
load_dotenv()

STRIPE_PUBLISHABLE_KEY = os.environ.get("STRIPE_PUBLISHABLE_KEY")
STRIPE_SECRET_KEY = os.environ.get("STRIPE_SECRET_KEY")
STRIPE_PRICE_ID = os.environ.get("STRIPE_PRICE_ID")
STRIPE_WEBHOOK_SECRET = os.environ.get("STRIPE_WEBHOOK_SECRET")

Note: We are using python-dotenv to load the environment variables.

Extend the Views

We now need to extend the views to integrate Stripe by creating a checkout session, a successful purchase view, and a webhook view.

1: Create a Stripe Checkout Session

In the purchase view, we'll create a Stripe checkout session if the purchase form is valid:

# ecommerce/views.py
from django_htmx import HttpResponseClientRedirect
from django.conf import settings
import stripe

@require_POST
def purchase(request):
    form = OrderForm(request.POST)
    if form.is_valid():
        quantity = form.cleaned_data["quantity"]

        # replace time.sleep(2) with the following code ⬇️

        # 1 - set stripe api key
        stripe.api_key = settings.STRIPE_SECRET_KEY

        # 2 - create success url
        success_url = (
            request.build_absolute_uri(
                reverse("purchase_success")
            )
            + "?session_id={CHECKOUT_SESSION_ID}"
        )

        # 3 - create cancel url
        cancel_url = request.build_absolute_uri(reverse("home"))

        # 4 - create checkout session
        checkout_session = stripe.checkout.Session.create(
            line_items=[
                {
                    "price": settings.STRIPE_PRICE_ID,
                    "quantity": quantity,
                }
            ],
            mode="payment",
            success_url=success_url,
            cancel_url=cancel_url
        )

        # 5 - redirect to checkout session url
        return HttpResponseClientRedirect(checkout_session.url)
    return render(request, "product.html", {"form": form})

Let’s break this down:

We first set the Stripe API key.
We then create a successful purchase URL pointing to the purchase_success view (which we'll create in the next step). Stripe should automatically populate the CHECKOUT_SESSION_ID.
We create a URL for when a purchase is canceled — for example, when the customer changes their mind. In this case, it’s just the home view.
We create a Stripe checkout session with our price ID (the product identifier) and the quantity the customer wants to purchase.
Stripe returns a session object from which we can extract the URL and redirect the customer. Since this request is coming from htmx, we can’t really use the standard Django redirect function. Instead, we use the django-htmx package, which provides this HttpResponseClientRedirect class.

2: Create the Successful Purchase View

After completing the purchase, Stripe will redirect the customer to our specified success_url. Here, we can handle the post-purchase logic:

from django.shortcuts import redirect

def purchase_success(request):
    session_id = request.GET.get("session_id")
    if session_id is None:
          return redirect("home")

    stripe.api_key = settings.STRIPE_SECRET_KEY
    try:
        stripe.checkout.Session.retrieve(session_id)
    except stripe.error.InvalidRequestError:
        messages.error(request, "There was a problem while buying your product. Please try again.")
        return redirect("home")
    return render(request, "purchase_success.html")

In this view, we first check if the session_id query parameter is present. If it is, we retrieve the corresponding session from Stripe using the secret key and the session_id. We then render the successful purchase template, which looks like this:

# ecommerce/templates/purchase_success.html {% extends "base.html" %} {% block
content %}
<section>
  <header>
    <h2>Thank you for your purchase</h2>
    <p>
      Your purchase was successful. You will receive an email with the details
      of your purchase soon.
    </p>
  </header>
</section>
{% endblock %}

You should also add it to the urlpatterns:

# ecommerce_site/urls.py

# ... same imports as before

urlpatterns = [
    # ... same urls as before
    path("purchase_success", views.purchase_success, name="purchase_success"),  # ⬅️ new
]

3: Create the Webhook View

While the customer is in the purchase process, and before they are redirected to the success view, Stripe will call our webhook endpoint (remember to have the webhook listener running, as explained in the earlier 'Create the Webhook' section of this post):

from django.views.decorators.csrf import csrf_exempt
from django.http import HttpResponse

@csrf_exempt
def webhook(request):
    stripe.api_key = settings.STRIPE_SECRET_KEY
    sig_header = request.headers.get('stripe-signature')
    payload = request.body
    event = None
    try:
            event = stripe.Webhook.construct_event(
                payload, sig_header, settings.STRIPE_WEBHOOK_SECRET
            )
    except stripe.error.SignatureVerificationError:
        # Invalid signature
        return HttpResponse(status=400)

    # Handle the checkout.session.completed event
    if event.type == "checkout.session.completed":
        # TODO: create line orders
        return HttpResponse(status=200)
    return HttpResponse(status=400)

Let’s break this down:

We try to construct a Stripe event from the payload, the signature header, and the webhook secret: the first is used to build the actual event, and the last two variables are relevant to validate the authenticity of the request.
If the signature verification fails, we return a 400 HTTP response. Remember that Stripe is actually calling this endpoint, not our customer, so Stripe will know what to do in this scenario.
We check if the event type is checkout.session.completed, i.e., if a customer successfully paid for our product. For now, we don’t do much else here, but we will process the order in the next step.

Note: A Stripe event can have multiple types but we will only handle completed sessions in this post. However, you can (and should) extend a webhook by following the docs.

You should also add this view to urlpatterns:

# ecommerce_site/urls.py

# ... same imports as before

urlpatterns = [
    # ... same urls as before
    path("webhook", views.webhook, name="webhook"),  # ⬅️ new
]

If everything works well, once you click “buy”, you should be redirected to a Stripe payment page. Since we are in test mode, we can fill in the payment details with dummy data, like a 4242 4242 4242 4242 card:

Once you press Pay, Stripe should call the webhook view and redirect you to the purchase_success view. Congratulations, you have successfully processed a payment with Stripe!

Create the Orders and Notify Users

Once a purchase is completed, we need to do a few things in the webhook view:

Save the order information in our database.
Notify staff users about the recent purchase.
Send a confirmation email to the customer.

Let’s create a LineOrder database model in ecommerce/models.py to store some of the order information:

# ecommerce/models.py

from django.db import models

class LineOrder(models.Model):
    quantity = models.IntegerField()
    name = models.CharField(max_length=255, null=True, blank=True)
    email = models.EmailField(null=True, blank=True)
    shipping_details = models.TextField(null=True, blank=True)
    created_at = models.DateTimeField(auto_now_add=True)

    def __str__(self):
        return f"Order {self.id} - {self.quantity} units"

Remember to create and run the migrations:

python manage.py makemigrations # ⬅️ creates the migration files
python manage.py migrate # ⬅️ applies the migrations in the database

We can now create a function to process the orders and call it from the webhook view:

# ecommerce/views.py

@csrf_exempt
def webhook(request):
    # ...same code as before
        if event.type == "checkout.session.completed":
            create_line_orders(event.data.object) # ⬅️ new
            return HttpResponse(status=200)
        return HttpResponse(status=400)

# new ⬇️
def create_line_orders(session: stripe.checkout.Session):
    line_items = stripe.checkout.Session.list_line_items(session.id)
    for line_item in line_items.data:
        LineOrder.objects.create(
            name=session.customer_details.name,
            email=session.customer_details.email,
            shipping_details=session.shipping_details,
            quantity=line_item.quantity,
        )
    mail.send_mail(
        "Your order has been placed",
        f"""
        Hi {session.customer_details.name},
        Your order has been placed. Thank you for shopping with us!
        You will receive an email with tracking information shortly.

        Best,
        The one product e-commerce Team
        """,
        "from@example.com",
        [session.customer_details.email],
    )

    staff_users = User.objects.filter(is_staff=True)
    mail.send_mail(
        "You have a new order!",
        """
            Hi team!
            You have a new order in your shop! go to the admin page to see it.

            Best,
            The one product e-commerce Team
            """,
        "from@example.com",
        [user.email for user in staff_users],
    )

Let’s break this down:

We first create line order instances from the Stripe session and send a confirmation email to the customer about their purchase.
We then send an email to all staff users telling them to check the admin panel.

You can now register the LineOrder model in the admin panel, so it’s accessible to staff users:

# ecommerce/admin.py
from django.contrib import admin
from ecommerce.models import LineOrder

# Register your models here.
admin.site.register(LineOrder)

When staff users log in to the admin page, they will now be able to check new orders and process them accordingly — in this case, pack and ship mugs to the customer!

Some Tips to Optimize Your Django Store

Here are some tips to further improve on the store you've built:

Write tests - you can see some examples in the GitHub repository.
If you have more products to sell, create a database model for them, and connect the LineOrder through a ForeignKey.
Configure email settings according to Django's email documentation. You can also use libraries such as django-post-office to manage your email templates and queues.
Once you deploy your website, create an actual webhook (not a local listener).
Take a look at the Stripe docs for alternatives to the checkout process we've outlined, including an embedded checkout form.

Wrapping Up

In this two-part series, we successfully built a one-product e-commerce site using Django, htmx, and Stripe. This guide has walked you through setting up your Django project, integrating htmx for seamless user interactions, and incorporating secure payments with Stripe.

We also covered how to handle order processing, including saving order information to your database, notifying staff users of new purchases, and sending confirmation emails to your customers. With these foundations, you can further customize and expand your e-commerce site to suit your specific needs.

Happy coding!

P.S. If you'd like to read Python posts as soon as they get off the press, subscribe to our Python Wizardry newsletter and never miss a single post!

Build a One-Product Shop With the Python Django Framework and Htmx

Francisco Macedo — Wed, 11 Sep 2024 13:18:12 +0000

This is the first of a two-part series using Django, htmx, and Stripe to create a one-product e-commerce website. In this part, we'll start our Django project and integrate it with htmx.

In the second part, we'll handle the orders with Stripe.

Let's get going!

Why Django, htmx, and Stripe?

We'll be using Django, htmx, and Stripe to create our website because:

Django is a Python web framework with a great ORM, templating, and routing system. It has a few features straight out of the box (like authentication) and multiple open source packages available online. We will use Django to build the website.
htmx is a JavaScript library that gives your website a modern feel just by using html attributes — you don’t actually have to write any JavaScript (although you can, of course). We will use htmx to give some interactivity to our page.
Stripe is a payments platform with a great API — it handles payments and credit card information. It also integrates nicely with Google and Apple Pay. We will use Stripe to facilitate product payments.

Here’s how the final product will work:

A user goes to our website and is able to see some information about our product, including its price and description.
Once the user clicks the “buy” button, they are redirected to Stripe’s checkout session.
If the payment is successful, they are redirected to our website again. We save their order information and send a confirmation email to the customer and all staff users to notify them of the recent purchase.

Now let's configure our Django project, create the initial views, and build the purchase form with htmx.

Configure Your Django Python Project

To set up our project, we need to create a virtual environment, activate it, and install the required packages. We can then create our Django project and Django app.

Create a Virtual Environment

Let's start by creating a virtual environment, so we can isolate our dependencies:

python -m venv .venv

Here's how we activate it on Linux/Mac:

source .venv/bin/activate

And on Windows:

.venv\Scripts\activate

Install the Required Packages

Within our activated virtual environment, we need a few packages to make this work:

pip install django stripe django-htmx python-dotenv

Here, we have installed:

Django
Stripe to work with the stripe API.
django-htmx, which provides some helper functionality to work with htmx.
python-dotenv to load environment variables from .env files.

Create the Django Project

In the same directory as our virtual environment, let's create a Django project called ecommerce_site:

django-admin startproject ecommerce_site .

In Django, it's good practice to have code organized by one or more "apps". Each app is a package that does something in particular. A project can have multiple apps, but for this simple shop, we can just have one app that will have most of the code — the views, forms, and models for our e-commerce platform. Let's create it and call it ecommerce:

python manage.py startapp ecommerce

And add this app to our INSTALLED_APPS in ecommerce_site/settings.py:

# ecommerce_site/settings.py

INSTALLED_APPS = [
    # ... the default django apps
    "ecommerce", # ⬅️ new
]

If you’re having trouble with this setup, check out the final product. At this stage, your file structure should look something like this:

ecommerce_site/
├── .venv/  # ⬅️ the virtual environment
├── ecommerce_site/ # ⬅️ the django project configuration
│   ├── __init__.py
│   ├── asgi.py
│   ├── settings.py
│   ├── urls.py
│   └── wsgi.py
├── ecommerce/ # ⬅️ our app setup
│     ├── templates/
│   ├── __init__.py
│   ├── admin.py
│   ├── apps.py
│   ├── models.py
│   ├── tests.py
│   └── views.py
└── manage.py

Create the Templates

Now that we have our project configured, we need to create some base layouts. In the templates directory, add a base.html file — the template that all other templates will inherit from. Add htmx for user interaction, mvp.css for basic styling, and Django generated messages to the template:

<!-- ecommerce/templates/base.html -->

<!DOCTYPE html>
<html lang="en">
  <head>
    <title>One-Product E-commerce Site</title>

    <!-- include htmx ⬇️ -->
    <script
      src="https://unpkg.com/htmx.org@1.9.11"
      integrity="sha384-0gxUXCCR8yv9FM2b+U3FDbsKthCI66oH5IA9fHppQq9DDMHuMauqq1ZHBpJxQ0J0"
      crossorigin="anonymous"
    ></script>

    <!-- include mvp.css ⬇️ -->
    <link rel="stylesheet" href="https://unpkg.com/mvp.css" />
  </head>
  <body hx-headers='{"X-CSRFToken": "{{ csrf_token }}"}' hx-boost="true">
    <header>
      <h1>One-Product E-commerce Site</h1>
    </header>
    <main>
      <section>
        {% if messages %} {% for message in messages %}
        <p><mark>{{ message }}</mark></p>
        {% endfor %} {% endif %}
      </section>
      {% block content %} {% endblock %}
    </main>
  </body>
</html>

Create a home.html template in the same templates directory, for our home view. It should extend the base.html and just populate its content section.

<!-- ecommerce/templates/home.html -->

{% extends "base.html" %} {% block content %}
<section>{% include "product.html" %}</section>
{% endblock %}

In this template, we have included the product.html template. product.html will render some details about our product and a placeholder image. Let’s create it in the same templates directory:

<!-- ecommerce/templates/product.html -->
<form>
  <img src="https://picsum.photos/id/30/400/250" alt="mug" />
  <h3>mug<sup>on sale!</sup></h3>
  <p>mugs are great - you can drink coffee on them!</p>
  <p><strong>5€</strong></p>
  <button type="submit" id="submit-btn">Buy</button>
</form>

Create the Home View

In ecommerce/views.py, we'll create the view that will render the home template:

# ecommerce/views.py

from django.shortcuts import render

def home(request):
    return render(request, 'home.html')

And add it to the urlpatterns in ecommerce_site/urls.py:

# ecommerce_site/urls.py

from django.contrib import admin
from django.urls import path
from ecommerce import views # ⬅️ new

urlpatterns = [
    path("admin/", admin.site.urls),
    path("", views.home, name="home"), # ⬅️ new
]

Now we can run the server with:

python manage.py runserver

If you jump over to http://127.0.0.1:8000 in your browser, you should see something like this:

It might feel like overkill to add a dedicated product.html template instead of just the product details in the home.html template, but product.html will be useful for the htmx integration.

Add the Form and Use Htmx

Great! We now have a view that looks good. However, it doesn’t do much yet. We'll add a form and set up the logic to process our product purchase. Here’s what we want to do:

Allow the user to select how many products (mugs) they want to buy.
When the user clicks “Buy”, make a POST request to a different view called purchase in the backend using hx-post.
In that view, validate the form and wait for 2 seconds to simulate the Stripe integration (we'll cover this in the second part of this guide).
Replace the form content with the purchase view response.
While the order is processing, show a loading message and disable the “Buy” button, so that the user doesn’t accidentally make multiple orders.

Let's go step by step.

1: Add a Quantity Order Form

Let’s first create and add a simple order form to our view allowing a user to select the number of mugs they want. In ecommerce/forms.py, add the following code:

# ecommerce/forms.py

from django import forms

class OrderForm(forms.Form):
        quantity = forms.IntegerField(min_value=1, max_value=10, initial=1)

In ecommerce/views.py, we can initialize the form in the home view:

# ecommerce/views.py

from ecommerce.forms import OrderForm # ⬅️ new

def home(request):
    form = OrderForm() # ⬅️ new - initialize the form
    return render(request, "home.html", {"form": form}) # ⬅️ new - pass the form to the template

And render it in the template:

<!-- ecommerce/templates/product.html -->

<form method="post">
  <!-- Same product details as before, hidden for simplicity -->

  <!-- render the form fields ⬇️ -->
  {{ form }}

  <!-- the same submit button as before ⬇️ -->
  <button type="submit" id="submit-btn">Buy</button>
</form>

2: Make a POST Request To a Different View

When the user clicks "Buy", we want to process the corresponding POST request in a dedicated view to separate the different logic of our application. We will use htmx to make this request. In the same ecommerce/templates/product.html template, let's extend the form attributes:

<!-- ecommerce/templates/product.html -->

<!-- add the hx-post html attribute ⬇️ -->
<form method="post" hx-post="{% url 'purchase' %}">
  <!-- Same product details as before, hidden for simplicity -->

  {{ form }}
  <button type="submit" id="submit-btn">Buy</button>
</form>

With this attribute, htmx will make a POST request to the purchase endpoint and stop the page from reloading completely. Now we just need to add the endpoint.

3: Create the Purchase View

The purchase view can be relatively simple for now:

# ecommerce/views.py
import time # ⬅️ new

# new purchase POST request view ⬇️
@require_POST
def purchase(request):
    form = OrderForm(request.POST)
    if form.is_valid():
        quantity = form.cleaned_data["quantity"]
        # TODO - add stripe integration to process the order
        # for now, just wait for 2 seconds to simulate the processing
        time.sleep(2)
    return render(request, "product.html", {"form": form})

In this view, we validate the form, extract the quantity from the cleaned data, and simulate Stripe order processing. In the end, we return the same template (product.html). We also need to add the view to the urlpatterns:

# ecommerce_site/urls.py

# ... same imports as before

urlpatterns = [
    path("admin/", admin.site.urls),
    path("", views.home, name="home"),
    path("purchase", views.purchase, name="purchase"),  # ⬅️ new
]

We now need to tell htmx what to do with this response.

4: Replace the Form Content With the Purchase View Response

Htmx has a hx-swap attribute which replaces targeted content on the current page with a request's response.
In our case, since the purchase view returns the same template, we want to swap its main element — the <form>:

<!-- ecommerce/templates/product.html -->

<!-- add the hx-swap html attribute ⬇️ -->
<form method="post" hx-post="{% url 'purchase' %}" hx-swap="outerHTML">
  <!-- Same product details as before, hidden for simplicity -->

  {{ form }}
  <button type="submit" id="submit-btn">Buy</button>
</form>

The value outerHTML will replace the entire target element with the response from the purchase view. By default, the htmx target is the same element making the call — in our case, the <form> element.

5: Tell Htmx What to Do When the Request Is Triggered

htmx provides some helper utilities for when a request is processing. In our case, we want to:

Disable the "Buy" button (to avoid a form re-submission) by using the hx-disabled-elt attribute.
Show a loading message on the screen by using the htmx-indicator class. This class changes its element's opacity when the request is triggered.

<!-- ecommerce/templates/product.html -->

<!-- add the hx-disabled-elt html attribute ⬇️ -->
<form
  method="post"
  hx-post="{% url 'purchase' %}"
  hx-swap="outerHTML"
  hx-disabled-elt="#submit-btn"
>
  <!-- Same product details as before, hidden for simplicity -->

  {{ form }}
  <button type="submit" id="submit-btn">Buy</button>

  <!-- add a loading message with the htmx-indicator class ⬇️ -->
  <p class="htmx-indicator"><small>Getting your mug ready...</small></p>
</form>

Once the customer clicks the "Buy" button, htmx will disable that same button (identifiable by its submit-btn id), and show a loading message by changing the opacity of the p.htmx-indicator element.

The Result

Jump over to the browser.

You can see the final result in this GitHub repository.

It doesn’t do much else yet. But, if form validation fails, errors will display directly on the form, without the need to refresh the entire page. If the form succeeds, we will process the Stripe order accordingly. We'll see how to do this in the second part of this guide.

Wrapping Up

We've now set up the basics for our one-product ecommerce site. We've configured our Django project, integrated it with htmx to give our site some interactivity, and set up a basic order form for our product.

In the second part of this guide, we'll handle orders with Stripe, save the results in our database, and notify users after a successful purchase.

Until then, happy coding!

P.S. If you'd like to read Python posts as soon as they get off the press, subscribe to our Python Wizardry newsletter and never miss a single post!