API Reference

This page provides detailed API documentation for all dj-payfast components.

Models

PayFastPayment

class payfast.models.PayFastPayment

Model representing a PayFast payment transaction.

Fields

user

Type:: ForeignKey to User (nullable)

The user who made the payment. Can be null for guest checkouts.

m_payment_id

Type:: CharField (max_length=100, unique)

Unique merchant payment ID. Must be unique across all payments.

pf_payment_id

Type:: CharField (max_length=100, nullable)

PayFast’s internal payment ID. Populated after payment is processed.

amount

Type:: DecimalField (max_digits=10, decimal_places=2)

Payment amount in South African Rand (ZAR).

amount_gross

Type:: DecimalField (max_digits=10, decimal_places=2, nullable)

Gross amount including fees. Populated by webhook.

amount_fee

Type:: DecimalField (max_digits=10, decimal_places=2, nullable)

PayFast transaction fee. Populated by webhook.

amount_net

Type:: DecimalField (max_digits=10, decimal_places=2, nullable)

Net amount after fees. Populated by webhook.

item_name

Type:: CharField (max_length=255)

Name of the item being purchased.

item_description

Type:: TextField (blank)

Detailed description of the item.

name_first

Type:: CharField (max_length=100, blank)

Customer’s first name.

name_last

Type:: CharField (max_length=100, blank)

Customer’s last name.

email_address

Type:: EmailField

Customer’s email address.

cell_number

Type:: CharField (max_length=20, blank)

Customer’s cell phone number.

status

Type:: CharField (max_length=20)
Choices:: pending, complete, failed, cancelled
Default:: pending

Current status of the payment.

payment_status

Type:: CharField (max_length=50, blank)

PayFast’s payment status (e.g., ‘COMPLETE’). Populated by webhook.

created_at

Type:: DateTimeField (auto_now_add)

When the payment record was created.

updated_at

Type:: DateTimeField (auto_now)

When the payment record was last updated.

completed_at

Type:: DateTimeField (nullable)

When the payment was marked as complete.

custom_str1 through custom_str5

Type:: CharField (max_length=255, blank)

Custom string fields for storing additional data.

custom_int1 through custom_int5

Type:: IntegerField (nullable)

Custom integer fields for storing additional data.

Methods

mark_complete()

Mark the payment as complete and set completion timestamp.

payment.mark_complete()

mark_failed()

Mark the payment as failed.

payment.mark_failed()

__str__()

Return string representation of the payment.

Returns:: "Payment {m_payment_id} - {status}"

Example Usage

from payfast.models import PayFastPayment
import uuid

# Create a payment
payment = PayFastPayment.objects.create(
    user=request.user,
    m_payment_id=str(uuid.uuid4()),
    amount=199.99,
    item_name='Premium Subscription',
    email_address='user@example.com',
)

# Query payments
completed = PayFastPayment.objects.filter(status='complete')

# Update status
payment.mark_complete()

PayFastNotification

class payfast.models.PayFastNotification

Model for logging PayFast ITN (Instant Transaction Notification) webhooks.

Fields

payment

Type:: ForeignKey to PayFastPayment (nullable)

The associated payment record, if found.

raw_data

Type:: JSONField

Complete raw POST data from PayFast.

is_valid

Type:: BooleanField (default=False)

Whether the notification passed all validation checks.

validation_errors

Type:: TextField (blank)

Error messages if validation failed.

ip_address

Type:: GenericIPAddressField (nullable)

IP address of the webhook request.

created_at

Type:: DateTimeField (auto_now_add)

When the notification was received.

Methods

__str__()

Return string representation of the notification.

Returns:: "Notification {id} - {'Valid' if is_valid else 'Invalid'}"

Example Usage

from payfast.models import PayFastNotification

# Get all notifications for a payment
notifications = PayFastNotification.objects.filter(
    payment=payment
)

# Check for validation failures
failed = PayFastNotification.objects.filter(
    is_valid=False
)

for notification in failed:
    print(notification.validation_errors)
    print(notification.raw_data)

Forms

PayFastPaymentForm

class payfast.forms.PayFastPaymentForm

Django form for generating PayFast payment requests.

Fields

All fields are hidden inputs that will be submitted to PayFast:

merchant_id: PayFast merchant ID (auto-populated from settings).

merchant_key: PayFast merchant key (auto-populated from settings).

amount: Payment amount (required).

item_name: Item name (required).

item_description: Item description (optional).

m_payment_id: Unique payment ID (required).

name_first: Customer first name (optional).

name_last: Customer last name (optional).

email_address: Customer email (required).

cell_number: Customer phone number (optional).

return_url: URL to redirect after successful payment (optional).

cancel_url: URL to redirect if payment is cancelled (optional).

notify_url: Webhook URL for ITN notifications (required).

custom_str1 through custom_str5: Custom string fields (optional).

custom_int1 through custom_int5: Custom integer fields (optional).

signature: MD5 signature for security (auto-generated).

Methods

__init__(*args, **kwargs): Initialize form and generate signature from initial data.

get_action_url()

Get the PayFast form submission URL (sandbox or production).

Returns:: PayFast processing URL

Example Usage

from payfast.forms import PayFastPaymentForm

# Create form
form = PayFastPaymentForm(initial={
    'amount': 99.99,
    'item_name': 'Premium Plan',
    'm_payment_id': 'unique-payment-id',
    'email_address': 'user@example.com',
    'notify_url': 'https://example.com/payfast/notify/',
})

# In template
# <form action="{{ form.get_action_url }}" method="post">
#     {{ form.as_p }}
#     <button type="submit">Pay</button>
# </form>

Views

PayFastNotifyView

class payfast.views.PayFastNotifyView

Class-based view for handling PayFast ITN webhook notifications.

Decorators

@csrf_exempt - CSRF protection disabled (PayFast can’t send CSRF token)
@require_POST - Only POST requests allowed

Methods

post(request, *args, **kwargs)

Handle incoming webhook notification.

Process:

Extract POST data
Validate IP address
Verify signature
Validate with PayFast server
Find payment record
Update payment status
Log notification

Parameters:: request – Django HttpRequest object
Returns:: HttpResponse with status 200 if valid, 400 if invalid

validate_with_payfast(post_data)

Validate notification data with PayFast servers.

Parameters:: post_data – Dictionary of POST data
Returns:: Boolean indicating validation success

Example Custom View

from payfast.views import PayFastNotifyView

class CustomNotifyView(PayFastNotifyView):

    def post(self, request, *args, **kwargs):
        response = super().post(request, *args, **kwargs)

        if response.status_code == 200:
            # Add custom logic
            self.send_notifications(request.POST)

        return response

    def send_notifications(self, data):
        # Your custom implementation
        pass

Utility Functions

generate_signature

payfast.utils.generate_signature(data_dict, passphrase=None)

Generate MD5 signature for PayFast request.

Parameters:

data_dict – Dictionary of payment data
passphrase – PayFast passphrase (optional, uses settings if not provided)

Returns:

MD5 signature as hex string

Example

from payfast.utils import generate_signature

data = {
    'merchant_id': '10000100',
    'merchant_key': '46f0cd694581a',
    'amount': '100.00',
    'item_name': 'Test Product',
}

signature = generate_signature(data, passphrase='MyPassphrase')

verify_signature

payfast.utils.verify_signature(data_dict, passphrase=None)

Verify PayFast signature from webhook data.

Parameters:

data_dict – Dictionary containing payment data and signature
passphrase – PayFast passphrase (optional)

Returns:

Boolean indicating if signature is valid

Example

from payfast.utils import verify_signature

webhook_data = request.POST.dict()

if verify_signature(webhook_data):
    # Signature is valid
    process_payment(webhook_data)
else:
    # Invalid signature
    log_security_alert()

validate_ip

payfast.utils.validate_ip(ip_address)

Validate that request comes from PayFast servers.

Parameters:: ip_address – IP address to validate
Returns:: Boolean indicating if IP is valid

Example

from payfast.utils import validate_ip

ip = request.META.get('REMOTE_ADDR')

if validate_ip(ip):
    # Request from PayFast
    process_webhook()
else:
    # Invalid IP
    return HttpResponseForbidden()

Configuration

Settings

All settings are configured in your Django settings.py:

PAYFAST_MERCHANT_ID

Type:: str
Required:: Yes

Your PayFast merchant ID.

PAYFAST_MERCHANT_ID = '10000100'

PAYFAST_MERCHANT_KEY

Type:: str
Required:: Yes

Your PayFast merchant key.

PAYFAST_MERCHANT_KEY = '46f0cd694581a'

PAYFAST_PASSPHRASE

Type:: str
Required:: No (but recommended)
Default:: ''

Your PayFast passphrase for enhanced security.

PAYFAST_PASSPHRASE = 'MySecurePassphrase123'

PAYFAST_TEST_MODE

Type:: bool
Required:: No
Default:: True

Enable sandbox/test mode. Set to False for production.

PAYFAST_TEST_MODE = False  # Production mode

URLs

payfast.urls

URL configuration for dj-payfast.

Patterns:

notify/ - Webhook endpoint (name: payfast:notify)

Usage:

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

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

This creates the endpoint: /payfast/notify/

Admin

PayFastPaymentAdmin

class payfast.admin.PayFastPaymentAdmin

Django admin configuration for PayFastPayment model.

Features:

List display with key fields
Filters by status, dates
Search by payment IDs and email
Read-only timestamp fields
Organized fieldsets
Collapsible custom fields section

List Display:

m_payment_id
user
amount
status
email_address
created_at
completed_at

Filters:

status
created_at
completed_at

Search Fields:

m_payment_id
pf_payment_id
email_address
item_name

PayFastNotificationAdmin

class payfast.admin.PayFastNotificationAdmin

Django admin configuration for PayFastNotification model.

Features:

List display with validation status
Filter by validity and date
Search by payment ID and IP
Read-only raw data field

List Display:

id
payment
is_valid
ip_address
created_at

Exceptions

While dj-payfast uses standard Django exceptions, you may want to create custom exceptions:

# payfast/exceptions.py
class PayFastError(Exception):
    """Base exception for PayFast errors"""
    pass

class SignatureVerificationError(PayFastError):
    """Signature verification failed"""
    pass

class PayFastValidationError(PayFastError):
    """PayFast validation failed"""
    pass

Constants

Payment Status Choices

payfast.models.PayFastPayment.STATUS_CHOICES

Available payment status values:

'pending' - Payment initiated but not complete
'complete' - Payment successfully completed
'failed' - Payment failed
'cancelled' - Payment cancelled by user

PayFast URLs

payfast.conf.PAYFAST_URL: PayFast payment processing URL (sandbox or production).

payfast.conf.PAYFAST_VALIDATE_URL: PayFast validation endpoint (sandbox or production).

Version Information

payfast.__version__

Current version of dj-payfast.

import payfast
print(payfast.__version__)  # '0.1.0'

Type Hints

For better IDE support and type checking, you can use type hints:

from typing import Optional, Dict, Any
from decimal import Decimal
from django.http import HttpRequest, HttpResponse
from payfast.models import PayFastPayment

def create_payment(
    user_id: int,
    amount: Decimal,
    item_name: str,
    email: str
) -> PayFastPayment:
    payment = PayFastPayment.objects.create(
        user_id=user_id,
        m_payment_id=str(uuid.uuid4()),
        amount=amount,
        item_name=item_name,
        email_address=email,
    )
    return payment

def process_webhook(
    request: HttpRequest,
    data: Dict[str, Any]
) -> HttpResponse:
    # Process webhook
    pass

API Reference

Models

PayFastPayment

PayFastNotification

Forms

PayFastPaymentForm

Views

PayFastNotifyView

Utility Functions

generate_signature

verify_signature

validate_ip

Configuration

Settings

URLs

Admin

PayFastPaymentAdmin

PayFastNotificationAdmin

Exceptions

Constants

Payment Status Choices

PayFast URLs

Version Information

Type Hints

See Also