Django Payment Gateways Package

A pluggable Django package for integrating multiple payment gateways including Paystack, Flutterwave, Interswitch, and Stripe, with an extensible architecture for adding more gateways.

✨ Features

• 🔌 Plug-and-play integration
• 🔐 Paystack, Flutterwave, Interswitch, Stripe, PayPal support
• 📦 Dispatcher pattern for gateway switching
• 🧱 Abstract BaseOrder model for customization
• ✅ Built-in Payment Verification View (redirect-based gateways)
• 🟦 Webhook-based verification for Stripe, PayPal, Paystack, Flutterwave, and Interswitch
• 🧠 Smart unique order reference generation
• 🧪 Built-in signal handling for order reference
• 🔔 payment_confirmed signal fired on every webhook-confirmed payment, for your own post-payment side effects
• 💡 Fully customizable frontend and views

Example Project

A sample Django project demonstrating how to use this package is available here:

👉 django_pg_test_project

📦 Installation

pip install django-pg

⚙️ Project Setup

1. Add the app to INSTALLED_APPS

# settings.py
INSTALLED_APPS = [
    ...
    'django_pg',  # Your payment package
]

2. Configure your Order model (Extend the BaseOrder abstract model) In your own app, create your order model by extending gateways.models.BaseOrder:

# yourapp/models.py
from django.db import models
from django_pg.models import BaseOrder
from django.contrib.auth.models import User

class Order(BaseOrder):
    user = models.ForeignKey(User, on_delete=models.CASCADE)
    total_price = models.DecimalField(max_digits=10, decimal_places=2)
    # Add your fields here

3. Define the model that handles the Order in settings.py

# settings.py

# Models used for order
PAYMENT_ORDER_MODEL = 'yourapp.Order'

🎯 Choose Your Payment Gateway

If you're using multiple payment methods (e.g. Paystack, Flutterwave, Interswitch, and stripe), make sure your template checks for the selected payment_method. If you're only using one payment method, you can pass the preferred payment method in a hidden field when the order is created.

Each guide covers:

• 🔑 API key configuration
• ⚙️ Gateway-specific settings
• 🧪 Testing with sandbox credentials
• 🚀 Going live checklist
• 🔧 Troubleshooting common issues
• 🟦 Webhook setup (recommended for every gateway above - a redirect-only integration never confirms a payment if the customer closes the tab before the redirect fires; the webhook confirms it independently of the browser)

4. Built-in Payment Verification View django-pg provides a built-in payment_verification view that handles verifying transactions for all the payment gateways out of the box.

🔌 URL Configuration

You can use the built-in view directly in your urls.py:

from django.urls import path
from django_pg.views import payment_verification  # Import from the package

urlpatterns = [
    path("verify/<int:order_id>/<str:payment_method>/", payment_verification, name="payment_verification"),
]

Note: Users attempting to make a payment via Paystack and Flutterwave must have a valid email address. The Paystack and Flutterwave gateway requires this for transaction initiation. Make sure you enforce email submission when a user registers

🔁 Signals (Auto Order Reference)

You don’t need to register anything. The gateways app automatically registers a pre_save signal that generates a unique order_reference.

# gateways/signals.py
@receiver(pre_save, sender=Order)
def set_order_reference(sender, instance, **kwargs):
    if not instance.order_reference:
        instance.order_reference = generate_unique_order_reference()

⚠️ Since a webhook is what looks the order up (by matching order_reference against whatever reference the gateway reports), your checkout must pass order.order_reference as the transaction reference you hand to the gateway (Paystack's ref, Flutterwave's/Interswitch's tx_ref) - not a randomly generated one. Each gateway's setup guide shows this in its template example.

🔔 Signal (Payment Confirmed via Webhook)

Every webhook handler (Stripe, PayPal, Paystack, Flutterwave, Interswitch) sends this signal after successfully confirming a payment, so your project can run its own post-payment side effects - an audit log, a custom fulfilment timeline, a confirmation email - without django_pg needing to know anything about them:

from django.dispatch import receiver
from django_pg.signals import payment_confirmed

@receiver(payment_confirmed)
def on_payment_confirmed(sender, order, provider, reference, raw_response, via, **kwargs):
    # via is currently always "webhook" - the client-triggered
    # payment_verification view does NOT send this signal, only the
    # webhook handlers do.
    ...

This only fires from the webhook path, not from the client-triggered payment_verification/PaymentVerificationJSONView flow - if you need to react to both, keep your own logic in whatever view calls django_pg.payment.verify_payment in addition to this receiver.

🧠 Gateway Dispatcher (Behind the scenes)

The following function routes the verification based on the selected payment method:

# gateways/payment.py
def verify_payment(order_id, reference, user, payment_method):
    if payment_method == 'paystack':
        return verify_paystack_payment(order_id, reference, user)
    # elif payment_method == 'flutterwave': ...

You don't need to modify this — it's extendable internally.

🛡 License

This project is licensed under the MIT License – see the LICENSE file for details.

🤝 Contributing

Pull requests are welcome! If you find a bug or have a feature request, feel free to open an issue.

See full Changelog.