paystack-django 1.1.0

A comprehensive Django integration for Paystack Payment Gateway

paystack-django

A comprehensive Django integration for the Paystack Payment Gateway. This package provides a complete, production-ready solution for integrating Paystack payments into your Django applications.

Features

• Complete Paystack API Coverage — 26 API modules covering every Paystack endpoint
• Django Models — Pre-built models for transactions, customers, plans, subscriptions, transfers, and webhook events
• Webhook System — Signature-verified webhook handling with IP whitelisting and event deduplication
• Django Signals — Signals for payment success/failure, subscriptions, transfers, refunds, and disputes
• System Checks — Django startup checks validate your Paystack configuration
• Context Manager — PaystackClient supports with statements for clean session management
• Retry & Backoff — Automatic retries with exponential back-off on transient failures
• Type Hints — Fully typed with py.typed marker for IDE and mypy support
• Production Ready — Secure defaults, lazy logging, Decimal-safe currency conversion

Supported Services

Category	API Modules
Payments	Transactions, Charge, Payment Requests, Pages
Customers	Customers, Direct Debit, Dedicated Accounts
Recurring	Plans, Subscriptions
Payouts	Transfers, Transfer Recipients, Transfer Control
Commerce	Products, Splits, Subaccounts
Operations	Refunds, Disputes, Settlements, Bulk Charges
Other	Verification, Terminal, Virtual Terminal, Apple Pay, Integration, Miscellaneous

Installation

pip install paystack-django

Quick Start

1. Add to Django Settings

# settings.py
INSTALLED_APPS = [
    # ...
    'djpaystack',
]

PAYSTACK = {
    'SECRET_KEY': 'sk_live_your_secret_key_here',
    'PUBLIC_KEY': 'pk_live_your_public_key_here',
    'WEBHOOK_SECRET': 'whsec_your_webhook_secret',
}

2. Run Migrations

python manage.py migrate djpaystack

3. Initialize a Transaction

from djpaystack import PaystackClient

client = PaystackClient()

response = client.transactions.initialize(
    email='[e-mail]',
    amount=50000,  # Amount in kobo (500 NGN)
    reference='order-001',
)

authorization_url = response['data']['authorization_url']
# Redirect user to authorization_url

The client can also be used as a context manager:

with PaystackClient() as client:
    response = client.transactions.verify(reference='order-001')

4. Verify Transaction

response = client.transactions.verify(reference='order-001')

if response['data']['status'] == 'success':
    print("Payment successful!")

5. Set Up Webhooks

# urls.py
from django.urls import path
from djpaystack.webhooks.views import handle_webhook

urlpatterns = [
    path('webhooks/paystack/', handle_webhook, name='paystack_webhook'),
]

Configure the webhook URL in your Paystack Dashboard.

Usage Examples

Customers

client = PaystackClient()

# Create customer
response = client.customers.create(
    email='[e-mail]',
    first_name='John',
    last_name='Doe',
    phone='2348012345678',
)

# Fetch customer
response = client.customers.fetch(email_or_code='CUS_xxxxx')

Subscriptions

# Create a plan
response = client.plans.create(
    name='Monthly Pro',
    amount=500000,  # 5,000 NGN
    interval='monthly',
)
plan_code = response['data']['plan_code']

# Subscribe a customer
response = client.subscriptions.create(
    customer='CUS_xxxxx',
    plan=plan_code,
    authorization='AUTH_xxxxx',
)

Transfers

# Create transfer recipient
response = client.transfer_recipients.create(
    type='nuban',
    name='John Doe',
    account_number='0000000000',
    bank_code='058',
)
recipient_code = response['data']['recipient_code']

# Initiate transfer
response = client.transfers.initiate(
    source='balance',
    amount=50000,
    recipient=recipient_code,
    reason='Payout',
)

Charge (Card, Bank Transfer, USSD, QR, EFT)

# Charge with bank transfer
response = client.charge.create(
    email='[e-mail]',
    amount=50000,
    bank_transfer={'account_expires_at': '2025-12-31T23:59:59'},
)

# Charge with QR code (scan-to-pay)
response = client.charge.create(
    email='[e-mail]',
    amount=50000,
    qr={'provider': 'visa'},
)

Refunds

# Create refund
response = client.refunds.create(transaction='123456')

# Retry a stuck refund
response = client.refunds.retry(id='123456')

Dedicated Virtual Accounts

# Single-step assignment
response = client.dedicated_accounts.assign(
    email='[e-mail]',
    first_name='John',
    last_name='Doe',
    phone='[phone]',
    preferred_bank='wema-bank',
)

Dynamic Transaction Splits

response = client.transactions.initialize(
    email='[e-mail]',
    amount=100000,
    split={
        'type': 'percentage',
        'bearer_type': 'account',
        'subaccounts': [
            {'subaccount': 'ACCT_xxx', 'share': 30},
            {'subaccount': 'ACCT_yyy', 'share': 20},
        ],
    },
)

Webhook Signals

Listen for payment events using Django signals:

from django.dispatch import receiver
from djpaystack.signals import paystack_payment_successful, paystack_payment_failed

@receiver(paystack_payment_successful)
def on_payment_success(sender, transaction_data, **kwargs):
    reference = transaction_data['reference']
    # Fulfil the order

@receiver(paystack_payment_failed)
def on_payment_failed(sender, transaction_data, **kwargs):
    reference = transaction_data['reference']
    # Notify the customer

Available signals: paystack_payment_successful, paystack_payment_failed, paystack_subscription_created, paystack_subscription_cancelled, paystack_transfer_successful, paystack_transfer_failed, paystack_refund_processed, paystack_dispute_created, paystack_dispute_resolved.

Configuration Reference

PAYSTACK = {
    # Required
    'SECRET_KEY': 'sk_...',
    'PUBLIC_KEY': 'pk_...',

    # Webhook
    'WEBHOOK_SECRET': 'whsec_...',
    'ALLOWED_WEBHOOK_IPS': [],  # Empty = Paystack default IPs

    # API behaviour
    'BASE_URL': 'https://api.paystack.co',
    'TIMEOUT': 30,
    'MAX_RETRIES': 3,
    'VERIFY_SSL': True,
    'CURRENCY': 'NGN',
    'ENVIRONMENT': 'production',  # 'production' or 'test'

    # Features
    'AUTO_VERIFY_TRANSACTIONS': True,
    'ENABLE_SIGNALS': True,
    'ENABLE_MODELS': True,
    'CACHE_TIMEOUT': 300,
    'LOG_REQUESTS': False,
    'LOG_RESPONSES': False,
    'CALLBACK_URL': None,
}

Django Models

from djpaystack.models import (
    PaystackTransaction,
    PaystackCustomer,
    PaystackPlan,
    PaystackSubscription,
    PaystackTransfer,
    PaystackWebhookEvent,
)

Error Handling

from djpaystack.exceptions import (
    PaystackError,
    PaystackAPIError,
    PaystackValidationError,
    PaystackAuthenticationError,
    PaystackNetworkError,
)

try:
    response = client.transactions.verify(reference='ref-123')
except PaystackAuthenticationError:
    print("Invalid API key")
except PaystackNetworkError:
    print("Network error — will be retried automatically")
except PaystackAPIError as e:
    print(f"API error: {e}")

Django Compatibility

paystack-django	Django 3.2	4.0	4.1	4.2	5.0	5.2	6.0
1.1.x	✅	✅	✅	✅	✅	✅	✅

Python 3.8 – 3.14 supported.

Testing

pip install -e ".[dev]"
pytest --cov=djpaystack

Documentation

Full documentation is available at django-paystack.readthedocs.io.

Contributing

See CONTRIBUTING.md for guidelines.

License

MIT — see LICENSE.

Links

• Full Documentation
• PyPI
• GitHub
• Bug Tracker
• Changelog

---

Made with ❤️ by Humming Byte