1. Installation

  1. Install django-payments

    $ pip install django-payments

Note that some providers have additional dependencies. For example, if using stripe, you should run:

$ pip install "django-payments[stripe]"
  1. Add payments to your INSTALLED_APPS.

  2. Add the callback processor to your URL router:

    # urls.py
    from django.conf.urls import include, path
    urlpatterns = [
        path('payments/', include('payments.urls')),
  3. Define a Payment model by subclassing payments.models.BasePayment:

    # mypaymentapp/models.py
    from decimal import Decimal
    from payments import PurchasedItem
    from payments.models import BasePayment
    class Payment(BasePayment):
        def get_failure_url(self):
            return 'http://example.com/failure/'
        def get_success_url(self):
            return 'http://example.com/success/'
        def get_purchased_items(self):
            # you'll probably want to retrieve these from an associated order
            yield PurchasedItem(name='The Hound of the Baskervilles', sku='BSKV',
                                quantity=9, price=Decimal(10), currency='USD')

    The get_purchased_items() method should return an iterable yielding instances of payments.PurchasedItem.

  4. Write a view that will handle the payment. You can obtain a form instance by passing POST data to payment.get_form():

    # mypaymentapp/views.py
    from django.shortcuts import get_object_or_404, redirect
    from django.template.response import TemplateResponse
    from payments import get_payment_model, RedirectNeeded
    def payment_details(request, payment_id):
        payment = get_object_or_404(get_payment_model(), id=payment_id)
            form = payment.get_form(data=request.POST or None)
        except RedirectNeeded as redirect_to:
            return redirect(str(redirect_to))
        return TemplateResponse(request, 'payment.html',
                                {'form': form, 'payment': payment})


    Please note that Payment.get_form() may raise a RedirectNeeded exception.

  5. Prepare a template that displays the form using its action and method:

    <!-- templates/payment.html -->
    <form action="{{ form.action }}" method="{{ form.method }}">
        {% csrf_token %}
        {{ form.as_p }}
        <p><input type="submit" value="Proceed" /></p>
  6. Configure your settings.py:

    # settings.py
        # ...
    PAYMENT_HOST = 'localhost:8000'
    PAYMENT_MODEL = 'mypaymentapp.Payment'
        'default': ('payments.dummy.DummyProvider', {})}

    Variants are named pairs of payment providers and their configuration.


    Variant names are used in URLs so it’s best to stick to ASCII.


    PAYMENT_HOST can also be a callable object.