CONFIGURATION.RST

Configuration

This guide covers all configuration options for dj-payfast.

Basic Settings

Required Settings

These settings must be configured in your settings.py:

# PayFast Merchant Credentials
PAYFAST_MERCHANT_ID = 'your_merchant_id'
PAYFAST_MERCHANT_KEY = 'your_merchant_key'

# Test or Production Mode
PAYFAST_TEST_MODE = True  # Set to False for production

Optional Settings

# Security passphrase (highly recommended)
PAYFAST_PASSPHRASE = 'your_secure_passphrase'

Environment Variables

Recommended: Store credentials as environment variables:

import os

PAYFAST_MERCHANT_ID = os.environ.get('PAYFAST_MERCHANT_ID')
PAYFAST_MERCHANT_KEY = os.environ.get('PAYFAST_MERCHANT_KEY')
PAYFAST_PASSPHRASE = os.environ.get('PAYFAST_PASSPHRASE')
PAYFAST_TEST_MODE = os.environ.get('PAYFAST_TEST_MODE', 'True') == 'True'

Highly Recommended: Using dotzen:

pip install dotzen

from dotzen import config

PAYFAST_MERCHANT_ID = config('PAYFAST_MERCHANT_ID')
PAYFAST_MERCHANT_KEY = config('PAYFAST_MERCHANT_KEY')
PAYFAST_PASSPHRASE = config('PAYFAST_PASSPHRASE', default='')
PAYFAST_TEST_MODE = config('PAYFAST_TEST_MODE', default=True, cast=bool)

Create a .env file:

PAYFAST_MERCHANT_ID=10000100
PAYFAST_MERCHANT_KEY=46f0cd694581a
PAYFAST_PASSPHRASE=your_secure_passphrase
PAYFAST_TEST_MODE=True

Using python-decouple:

pip install python-decouple

from decouple import config

PAYFAST_MERCHANT_ID = config('PAYFAST_MERCHANT_ID')
PAYFAST_MERCHANT_KEY = config('PAYFAST_MERCHANT_KEY')
PAYFAST_PASSPHRASE = config('PAYFAST_PASSPHRASE', default='')
PAYFAST_TEST_MODE = config('PAYFAST_TEST_MODE', default=True, cast=bool)

Create a .env file:

PAYFAST_MERCHANT_ID=10000100
PAYFAST_MERCHANT_KEY=46f0cd694581a
PAYFAST_PASSPHRASE=your_secure_passphrase
PAYFAST_TEST_MODE=True

Test vs Production Mode

Test Mode (Sandbox)

PAYFAST_TEST_MODE = True

  • Uses sandbox.payfast.co.za

  • Test credentials required

  • No real money processed

  • Perfect for development

Production Mode

PAYFAST_TEST_MODE = False

  • Uses www.payfast.co.za

  • Production credentials required

  • Real money processed

  • Requires verified merchant account

URL Configuration

PayFast URLs are automatically configured based on PAYFAST_TEST_MODE:

Test Mode URLs:

  • Payment: https://sandbox.payfast.co.za/eng/process

  • Validation: https://sandbox.payfast.co.za/eng/query/validate

Production URLs:

  • Payment: https://www.payfast.co.za/eng/process

  • Validation: https://www.payfast.co.za/eng/query/validate

Custom Configuration

Advanced users can override default URLs:

# Custom PayFast URLs (not recommended)
PAYFAST_URL = 'https://custom.payfast.url/process'
PAYFAST_VALIDATE_URL = 'https://custom.payfast.url/validate'

Database Configuration

dj-payfast creates two models:

  • PayFastPayment - Stores payment records

  • PayFastNotification - Logs webhook notifications

Default settings work for most cases. For high-volume sites:

# Add database indexes
DATABASES = {
    'default': {
        # ... your database config
    }
}

# Consider separate database for payments
DATABASE_ROUTERS = ['myapp.routers.PaymentRouter']

Webhook Configuration

The webhook URL is automatically configured at:

https://yourdomain.com/payfast/notify/

Ensure this URL is:

  1. Publicly accessible

  2. Uses HTTPS (required for production)

  3. Not behind authentication

  4. Can receive POST requests

For local development, use ngrok:

ngrok http 8000

Then use the ngrok URL in your notify_url:

notify_url = 'https://abc123.ngrok.io/payfast/notify/'

Security Settings

Passphrase

Highly recommended for production:

PAYFAST_PASSPHRASE = 'your_very_secure_random_passphrase_here'

Generate a secure passphrase:

import secrets
passphrase = secrets.token_urlsafe(32)
print(passphrase)

IP Validation

PayFast webhook requests come from specific IPs. The library validates these automatically.

Valid PayFast hosts:

  • www.payfast.co.za

  • sandbox.payfast.co.za

  • w1w.payfast.co.za

  • w2w.payfast.co.za

HTTPS Configuration

Required for production:

# Ensure HTTPS in production
SECURE_SSL_REDIRECT = True
SECURE_PROXY_SSL_HEADER = ('HTTP_X_FORWARDED_PROTO', 'https')
SESSION_COOKIE_SECURE = True
CSRF_COOKIE_SECURE = True

Logging Configuration

Configure logging to track payments:

LOGGING = {
    'version': 1,
    'disable_existing_loggers': False,
    'handlers': {
        'file': {
            'level': 'INFO',
            'class': 'logging.FileHandler',
            'filename': 'payfast.log',
        },
    },
    'loggers': {
        'payfast': {
            'handlers': ['file'],
            'level': 'INFO',
            'propagate': True,
        },
    },
}

Multi-Environment Setup

Example configuration for multiple environments:

# settings/base.py
INSTALLED_APPS = [
    # ...
    'payfast',
]

# settings/development.py
from .base import *

PAYFAST_TEST_MODE = True
PAYFAST_MERCHANT_ID = '10000100'  # Sandbox ID
PAYFAST_MERCHANT_KEY = '46f0cd694581a'  # Sandbox key

# settings/production.py
from .base import *

PAYFAST_TEST_MODE = False
PAYFAST_MERCHANT_ID = os.environ['PAYFAST_MERCHANT_ID']
PAYFAST_MERCHANT_KEY = os.environ['PAYFAST_MERCHANT_KEY']
PAYFAST_PASSPHRASE = os.environ['PAYFAST_PASSPHRASE']

Configuration Checklist

Before going to production:

☐ Set PAYFAST_TEST_MODE = False
☐ Use production credentials
☐ Set secure PAYFAST_PASSPHRASE
☐ Enable HTTPS
☐ Configure proper logging
☐ Test webhook URL is accessible
☐ Set up error monitoring
☐ Review security settings
☐ Test with small transaction
☐ Monitor first few transactions

Next Steps