The integration of Stripe payments in Django

What is Stripe payment?

Let's start with the most fundamental questions: What is Stripe? What is Stripe payment?

Stripe is a platform that offers online payment processing. It also supports credit cards.

It's simply an intermediary between the customer (e.g., of an online store) and the seller, between the buyer's and seller's banks.

Is it another gateway, like so many, on the USA market? Not necessarily, but we'll talk about the details in a moment.

Stripe offers a service that guarantees both parties a fast, easy, and, above all, secure transaction.

As a payment service provider, Stripe offers multiple payment methods – including deferred payments or recurring billing.

Completing a particular transaction, obviously, involves making a payment.

Stripe's reach sets it apart from the rest of the competition.

The U.S.-based brand offers support for more than 130 currencies, making it an optimal solution for companies that sell their products to international markets.

Stripe is ideal for companies where offering payments in foreign currencies is an important part of competing. For those for whom currency exchanges are a daily practice, a necessity, and a daily worry about the cost of currency conversions.

In terms of currency conversion costs, Stripe is considered a very competitive and attractively affordable solution.

Stripe offers payment processing in various business models, including:

• E-Commerce (B2C)
• Platform B2B
• Virtual Wallet
• Fund-raisers
• Support of non-profit organizations
• Software as a Service (SaaS)

In addition, Stripe's Payments API supports the majority of universal payment systems, namely:

• Alipay
• Apple Pay
• Google Pay
• WeChat Pay.

Why should we use Stripe?

A measure of the quality of the services, products, programs, and solutions offered by Stripe is its:

• Fast and easy integration process – the registration and verification process is pretty quick and doesn't require meeting very restrictive criteria.
• The integrated system within which various forms of payment processing are possible.
• Flexibility and adaptability of Stripe APIs to individual needs.
• Extensive libraries that provide developers with functionalities along with documentation.
• Advanced reporting tools.

Subscriptions (recurring payments) in Stripe

In addition to single transactions, Stripe also offers Recurring Payments, which are most commonly used for SaaS and PaaS services.

With Stripe, we can easily implement a subscription fee-based business model in our application.

This is done without the need for a complex interface and logic that is necessary for the user to handle recurring payments conveniently.

And we would like to use this example of subscription support to show how to easily and pleasantly start your adventure with Stripe in applications based on the Django framework.

Payment integration in Django

Recurring payments, by definition, are more complicated than single transactions. They're inherently asynchronous, and what is asynchronous usually requires more work and is more difficult to test and later maintain.

In the remainder of this article, we'll show how to implement a subscription model in a Django-based application while explaining the basics of Stripe workflow.

We won't cover the basics of Django here, such as view creation, routing, or configuration. We assume you are a Python developer and have created more than one application in Django. So, let's focus on the interesting thing – Stripe.

Disclaimer:

The code shown below must not be used in the production version of an application.

In this snippet of code, we do not include error and exception handling, and we do not customize security requirements, which are often individual.

We also left out many scenarios and use cases of a smaller significance. The task we set for ourselves in preparing the following code is to show the general principles of integration of Stripe in a Django application.

Our team would never use such code in the production version of an application.

Preparation

We can work on an existing Django application or create a new project – the integration will not require us to make any complicated changes to the architecture or install dependencies that will interfere with the application.

The only thing we need to add to our virtual environment is the official `stripe` library for Python:

pip install stripe

The next step will be to create a Stripe account. The registration process itself is straightforward and requires no additional comments, especially since we aren't making a production account, and additional business verification won't be necessary.

Instead, we need to perform the following steps after registration in order to work with the Stripe API (you will not find information about this in the official documentation, and we would like to save you the time of investigating the causes of errors):

• Name the company by clicking on the top left corner next to the Activate account button.
• Fill in the links on the terms of service and privacy policy of our account settings (Settings > Billing > Customer portal).

We will also need the Stripe CLI tool for further testing, which makes working in a local environment much more pleasant. How? You can find out in this article: https://stripe.com/docs/stripe-cli

Next, we need to add to the settings of our Django application two parameters necessary to communicate with the Stripe API. The naming of the setting keys is not essential and should be treated as a suggestion:

STRIPE_API_KEY = ********
STRIPE_HOOKS_SECRET = ********

We can get the value for `STRIPE_API_KEY` by going to Developers > API keys in the Stripe dashboard and copying the Secret key value. We will fill in `STRIPE_HOOKS_SECRET` later, and at this stage, we can set it to an empty character string.

The final step will be to create test data in our Stripe account. For this, you can use a simple Django CLI command that will create a product and three subscription packages:

import stripe
from django.conf import settings
from django.core.management import BaseCommand

class Command(BaseCommand):
    def handle(self, *args, **options):
        stripe.api_key = settings.STRIPE_API_KEY
        product = stripe.Product.create(name='Awesome Service')
        for i in range(1, 4):
            stripe.Price.create(
                product=product['id'],
                currency='usd',
                unit_amount=i * 1000,
                recurring={'interval': 'month'},
                lookup_key=f'service_{i}',
                nickname=f'Service level {i}',
            )

You can also create test data using the Stripe administration panel. Unfortunately, in the panel, we can't specify the `lookup_key` value for individual price packages, which causes some implementation issues since identification in queries will have to be based on the price package ID, which Stripe does not recommend.

We have the environment prepared and can move on to perform the integration itself.

Package selection view

We'll first create a simple view that allows the user to select the price package of our subscription and start the payment process.

In the view, we download all the pricing options for the first active product in our Stripe account:

def index(request):
    active_products = stripe.Product.list(active=True)
    prices = stripe.Price.list(product=active_products['data'][0]['id'])
    return render(request, 'subscriptions/index.html', {
        'prices': prices['data'],
    })

The view template is also very simple – we display a radio select for the user to choose a subscription package:

{% extends 'base.html' %}
{% block body %}
  <h1>Checkout page</h1>
  <form action="{% url 'create-checkout-session' %}" method="post">
    {% csrf_token %}
    {% for obj in prices %}
      {% widthratio obj.unit_amount 100 1 as price %}
      <label>
        <input type="radio" name="lookup_key" value="{{ obj.lookup_key }}" {% if forloop.first %}checked{% endif %}>
        {{ obj.nickname }} for {{ price|floatformat:2 }} {{ obj.currency|upper }} per {{ obj.recurring.interval }}
      </label><br>
    {% endfor %}
    <p>
      <button>Checkout</button>
    </p>
  </form>
{% endblock %}

The package selection form will be sent to the `create-checkout-session` view, which will be presented in the next step. We will display the view based on the price package data directly from the Stripe API, where the price is provided in cents, so we need to do a simple conversion.

Django templates don't provide the ability to perform division in templates, so to avoid writing our own tag, we will use the built-in `{% withration %}` tag, which corresponds to dividing the number of cents by 100.

When we enter the view address in the browser, we should get the following result:

Transaction initiation view

The selected price package (to be precise, the `lookup_key` of the selected package) is passed to this view via POST.

We retrieve the package ID, then open a Stripe checkout session and direct the user to the resulting generated URL, where the user is redirected to a Stripe-hosted payment page and makes a payment outside our system.

def create_checkout_session(request):
    prices = stripe.Price.list(
        lookup_keys=[request.POST['lookup_key']],
        expand=['data.product']
    )
    success_url = request.build_absolute_uri(reverse('success')) + '?session_id={CHECKOUT_SESSION_ID}'
    cancel_url = request.build_absolute_uri(reverse('cancel'))
    checkout_session = stripe.checkout.Session.create(
        payment_method_types=['card'],
        line_items=[{'price': prices.data[0].id, 'quantity': 1}],
        mode='subscription',
        success_url=success_url,
        cancel_url=cancel_url,
    )
    return redirect(checkout_session.url)

The `stripe.checkout.Session.create` method, in our case, should receive the following parameters:

• `payment_method_types` – list of payment methods available to the user
• `line_items` – a collection of pricelist items that will be included in the payment
• `mode` – payment mode, we are interested in recurring payment
• `success_url` – an URL to which the user will be redirected after successful payment. Be sure to include the placeholder `{CHECKOUT_SESSION_ID}`, which will be replaced on the Stripe side with the session key needed to obtain transaction and user data.
• `cancel_url` – URL to which the user will be redirected if the payment fails; for some reason, it can be the same as `success_url`.

After successful payment in Stripe, the user is redirected back to our application at the address indicated in the `success_url`. We will examine the view available at this address in the next step.

The successful payment view

The successful payment view is a success page that the user sees after a successful payment receives the `session_id` parameter in the query string (according to the template we passed in the previous step).

This is precisely the point at which we can link the `customer ID` from Stripe to our user in Django – it will be needed to receive user subscription events and `portal session` generation, which we'll talk about next.

To simplify things, we won't save the `customer ID`, but will pass it to the template, where we'll allow the user to proceed to subscription management in Stripe.

def success(request):
    checkout_session = stripe.checkout.Session.retrieve(request.GET['session_id'])
    return render(request, 'subscriptions/success.html', {
        'customer': checkout_session.customer,
    })

And here is the template code:

{% extends 'base.html' %}
{% block body %}
  <h1>Success!</h1>
  <form action="{% url 'create-portal-session' %}" method="post">
    {% csrf_token %}
    <input type="hidden" name="customer" value="{{ customer }}">
    <button>Manage your subscription</button>
  </form>
{% endblock %}

The transition to subscription management (customer portal) is done by sending the `customer ID` to the `create-portal-session` view, which is responsible for redirecting the user to the subscription profile in Stripe.

View of transition initiation to the user portal

Stripe provides a fast and convenient way to receive payments and allows us, without much work, to provide the user with a convenient and very powerful UI for managing their subscription, i.e., `customer portal`.

The customer portal is a completely independent and secure interface hosted by Stripe. To redirect the user to the portal, we need to generate a URL using `customer ID`, which is also what the view below is responsible for.

def create_portal_session(request):
    portal_session = stripe.billing_portal.Session.create(
        customer=request.POST['customer'],
        return_url=request.build_absolute_uri(reverse('subscriptions'))
    )
    return redirect(portal_session.url)

Asynchronicity, aka webhooks

The entire code we have written so far is only the initial subscription and only handles the first charge of the customer's card.

Instead, we would like to charge the user on a recurring basis and without their participation – after all, that's what subscription models are all about.

This is where webhooks, the event system that Stripe provides to developers, comes to the rescue.

Stripe generates a myriad of different events related to payment processing, subscription, document generation, and more. The distribution of events is done using the webhooks concept.

In a nutshell – Stripe, when an event occurs, triggers the URL indicated in the administration panel, to which all the event data is forwarded.

The template is straightforward and allows us to easily handle the asynchronous flow, which is a natural way to manage subscriptions and deferred payments.

Let's create a view that will receive events from Stripe, that is, our webhook handler:

@csrf_exempt
def webhooks(request):
    event = stripe.Webhook.construct_event(
        payload=request.body,
        sig_header=request.headers['stripe-signature'],
        secret=settings.STRIPE_HOOKS_SECRET
    )
    data = event['data']
    event_type = event['type']
    data_object = data['object']
    if event_type == 'invoice.paid':
        print(f'Renew customer: {data_object["customer"]}')
    elif event_type == 'customer.subscription.deleted':
        print(f'Cancel subscription: {data_object["customer"]}')
    return JsonResponse({'status': 'success'})

First, we need to fill in the value of the `STRIPE_HOOKS_SECRET` key in the configuration of our Django application, which we initially set to an empty character string.

We can get the value for this key from the Stripe panel, but to do so, we would have to open the access to the application to the world, which is not always convenient or secure.

As we mentioned at the beginning, the most challenging part of implementing asynchronous workflow is testing in a local environment. Stripe is positioning itself as a developer-friendly solution with a high level of DX.

In the arsenal of libraries and tools provided by Stripe, we will find everything that makes our daily life much easier and local work efficient and enjoyable. One such tool is Stripe CLI, which we should already have installed.

First, we need to log in using the Stripe CLI by executing the `stripe login` command. After logging in, we run the following command, which will redirect all hook calls to our local application without having to open our environment to the world:

stripe listen --forward-to <HOOKS_URL>

After executing the command, the console will display the key that we should enter into our configuration as `STRIPE_HOOKS_SECRET`.

From now on, all Stripe events will go directly to our view.

There are a lot of triggered events, but to show the general principle of integration in the sample code, we support only two types of events:

• `invoice.paid` – occurs at the time of subscription renewal and includes a `customer ID` so we can extend the validity of the user's account.
• `customer.subscription.deleted` – occurs when a user cancels a subscription; the data of such an event also include `customer ID`.

That's the long and short of it. With the presented solutions, we can easily build a full subscription service with virtually any logic.