Django Models

paystack-django provides 6 Django models for persisting Paystack data locally. When PAYSTACK['ENABLE_MODELS'] is True (the default), webhook handlers automatically create/update these records.

Models Overview

Model	Purpose
`PaystackTransaction`	Payment transactions (amount, status, reference, customer, authorization, fees, metadata)
`PaystackCustomer`	Customer records (email, name, phone, customer_code, risk_action)
`PaystackPlan`	Subscription plans (name, amount, interval, plan_code)
`PaystackSubscription`	Active subscriptions (subscription_code, plan_code, status, next_payment_date)
`PaystackTransfer`	Transfer records (transfer_code, reference, amount, recipient_code, status)
`PaystackWebhookEvent`	Raw webhook event log (event_type, event_id, data, processed flag)

Usage

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

# Successful transactions
paid = PaystackTransaction.objects.filter(status='success')

# Customer lookup
customer = PaystackCustomer.objects.get(email='customer@example.com')

# Active subscriptions
active_subs = PaystackSubscription.objects.filter(status='active')

# Unprocessed webhooks
pending = PaystackWebhookEvent.objects.filter(processed=False)

Base Model

All models inherit from PaystackBaseModel, which provides:

created_at — Auto-set on creation
updated_at — Auto-set on every save

PaystackTransaction

class djpaystack.models.PaystackTransaction(*args: Any, **kwargs: Any)[source]

Bases: PaystackBaseModel

Model for storing Paystack transactions

STATUS_CHOICES = [('pending', 'Pending'), ('success', 'Success'), ('failed', 'Failed'), ('abandoned', 'Abandoned')]

class Meta[source]

Bases: object

ordering = ['-created_at']

indexes = [django.db.models.Index]

Key fields: reference (unique), amount (kobo), currency, status, customer_email, customer_code, authorization_code, authorization_url, access_code, paid_at, channel, ip_address, fees, fees_split, metadata, raw_response.

PaystackCustomer

class djpaystack.models.PaystackCustomer(*args: Any, **kwargs: Any)[source]

Bases: PaystackBaseModel

Model for storing Paystack customers

class Meta[source]

Bases: object

ordering = ['-created_at']

Key fields: customer_code (unique), email (unique), first_name, last_name, phone, risk_action, metadata.

PaystackPlan

class djpaystack.models.PaystackPlan(*args: Any, **kwargs: Any)[source]

Bases: PaystackBaseModel

Model for storing Paystack plans

INTERVAL_CHOICES = [('daily', 'Daily'), ('weekly', 'Weekly'), ('monthly', 'Monthly'), ('quarterly', 'Quarterly'), ('biannually', 'Biannually'), ('annually', 'Annually')]

class Meta[source]

Bases: object

ordering = ['-created_at']

Key fields: plan_code (unique), name, amount, interval, description, currency, is_active, metadata.

PaystackSubscription

class djpaystack.models.PaystackSubscription(*args: Any, **kwargs: Any)[source]

Bases: PaystackBaseModel

Model for storing Paystack subscriptions

STATUS_CHOICES = [('active', 'Active'), ('non-renewing', 'Non-Renewing'), ('attention', 'Attention'), ('completed', 'Completed'), ('cancelled', 'Cancelled')]

class Meta[source]

Bases: object

ordering = ['-created_at']

Key fields: subscription_code (unique), customer_code, plan_code, amount, status, next_payment_date, email_token, authorization_code, metadata.

PaystackTransfer

class djpaystack.models.PaystackTransfer(*args: Any, **kwargs: Any)[source]

Bases: PaystackBaseModel

Model for storing Paystack transfers

STATUS_CHOICES = [('pending', 'Pending'), ('success', 'Success'), ('failed', 'Failed'), ('otp', 'OTP'), ('queued', 'Queued')]

class Meta[source]

Bases: object

ordering = ['-created_at']

Key fields: transfer_code (unique), reference (unique), amount, currency, status, recipient_code, reason, transferred_at, metadata.

PaystackWebhookEvent

class djpaystack.models.PaystackWebhookEvent(*args: Any, **kwargs: Any)[source]

Bases: PaystackBaseModel

Model for storing webhook events

class Meta[source]

Bases: object

ordering = ['-created_at']

indexes = [django.db.models.Index]

Key fields: event_type, event_id (unique), data (JSON), processed (boolean), processing_error, ip_address, user_agent.

Migrations

python manage.py migrate djpaystack