1. Installation

  1. Install django-payments

    $ pip install django-payments
    
  2. Add the callback processor to your URL router:

    # urls.py
    from django.conf.urls import include, url
    
    urlpatterns = [
        url('^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)
        try:
            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})
    

    Note

    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 }}">
        {{ form.as_p }}
        <p><input type="submit" value="Proceed" /></p>
    </form>
    
  6. Configure your settings.py:

    # settings.py
    INSTALLED_APPS = [
        # ...
        'payments']
    
    PAYMENT_HOST = 'localhost:8000'
    PAYMENT_USES_SSL = False
    PAYMENT_MODEL = 'mypaymentapp.Payment'
    PAYMENT_VARIANTS = {
        'default': ('payments.dummy.DummyProvider', {})}
    

    Variants are named pairs of payment providers and their configuration.

    Note

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

    Note

    PAYMENT_HOST can also be a callable object.