Installation

Install the package

$ pip install django-payments

Most providers have additional dependencies. For example, if using stripe, you should run:

$ pip install "django-payments[stripe]"

Multiple providers can be specified comma-separated, e.g.:

$ pip install "django-payments[mercadopago,stripe]"

Hint

Use quotes as above to prevent your shell from parsing the square brackets.

Changed in version 0.15: Each provider now has extra/optional dependencies. Previously, dependencies for all providers were installed by default.

Configure Django

payments needs to be registered as a Django app by adding it to settings.py:

INSTALLED_APPS = [
  ...
  "payments",
  ...
]

There is no strong requirement for it to be listed first nor last.

Add the callback processor to your URL router (urls.py).

# urls.py
from django.conf.urls import include, path

urlpatterns = [
    path('payments/', include('payments.urls')),
]

This includes two sets of URLs:

  • Views (endpoints) where notifications will be received from payment providers. These must be exposed properly for the provider to notify us of any payment. Note that these notifications may be delivered _after_ the user has navigated away from the website.

  • Views where users are directed after completing a payment. Usually, once the user has completed a flow at the payment provider’s website, their browser will be redirected to one of these views and POST some additional data. These views parse this data, communicate with the provider (if a necessary) and then redirect the user to a view of your choosing.

None of these views render any “pages” that your users might every see.

Additional Django settings

The following settings are mandatory, as well as PAYMENT_MODEL (more on this later in Registering the Payment class).

# This can be a string or callable, and should return a base host that
# will be used when receiving callbacks and notifications from payment
# providers.
#
# Keep in mind that if you use `localhost`, external servers won't be
# able to reach you for webhook notifications.
PAYMENT_HOST = 'localhost:8000'

# Whether to use TLS (HTTPS). If false, will use plain-text HTTP.
# Defaults to ``not settings.DEBUG``.
PAYMENT_USES_SSL = False

The following setting is optional, and reserved for advanced usages:

# Callable to retrieve payment provider instance
#
# This is an advanced setting. It is required if defining provider
# credentials in the settings file is unsuitable. Implementations may choose
# to read provider credentials from the database or any other source that's
# suitable.
#
# Alternatively, you can provide a callable that takes two arguments:
# variant (string) and an optional payment (BasePayment).
# The callback has to return an instance of the desired payment provider.
#
# For inspiration, see the payments.core.payment_factory function, which
# retrieves the variant from the above dictionary.
PAYMENT_VARIANT_FACTORY = "mypaymentapp.provider_factory"