Installation

Install the package
```
pip install django-solana-payments
```
For DRF support, which provides API endpoints for creating and managing payments, install the drf extra:
```
pip install "django-solana-payments[drf]"
```
For django-payments integration support, install the django-payments extra:
```
pip install "django-solana-payments[django-payments]"
```

Add the app to `INSTALLED_APPS`

INSTALLED_APPS = [
    ...,
    'django_solana_payments',
]

Create custom payment models

Create your own models that inherit from the library’s abstract base models, then reference them from SOLANA_PAYMENTS.

from django.db import models

from django_solana_payments.models import (
    AbstractPaymentToken,
    AbstractSolanaPayment,
)


class CustomSolanaPayment(AbstractSolanaPayment):
    customer_id = models.CharField(max_length=255, blank=True, null=True)


class CustomPaymentToken(AbstractPaymentToken):
    name = models.CharField(max_length=100)
    symbol = models.CharField(max_length=10)

See Custom Models for the full guide.

Configure `SOLANA_PAYMENTS`

After creating your models, point SOLANA_PAYMENTS at those model paths and configure the rest of the library settings.

SOLANA_PAYMENTS = {
    "SOLANA_PAYMENT_MODEL": "solana_payments.CustomSolanaPayment", # Custom model for solana payment
    "PAYMENT_CRYPTO_TOKEN_MODEL": "solana_payments.CustomPaymentToken", # Custom model for solana payment token

    "RPC_URL": "https://api.mainnet-beta.solana.com",
    "RECEIVER_ADDRESS": "YOUR_WALLET_ADDRESS", # Wallet that receives funds
    "FEE_PAYER_KEYPAIR": "WALLET_KEYPAIR", # Wallet keypair that pays network fees (address is derived from keypair)
    # FEE_PAYER_ADDRESS is derived from the keypair and doesn't need to be set separately
    "RPC_TIMEOUT": 10, # Optional AsyncClient timeout in seconds
    "RPC_EXTRA_HEADERS": None, # Optional dict of extra RPC headers
    "RPC_PROXY": None, # Optional proxy URL
    "RPC_RATE_LIMIT": 0, # Optional AsyncClient rate limit; 0 disables limiter
    "ONE_TIME_WALLETS_ENCRYPTION_ENABLED": True, # Enables encryption for one-time payments wallets
    "ONE_TIME_WALLETS_ENCRYPTION_KEY": "ONE_TIME_WALLETS_ENCRYPTION_KEY", # Generate with the Fernet.generate_key()
    "RPC_COMMITMENT": "Confirmed", # RPC Commitment
    "PAYMENT_ACCEPTANCE_COMMITMENT": "Confirmed", # Commitment for payment acceptance
    "MAX_ATAS_PER_TX": 8, # Max associated token accounts to create/close per transaction
    "PAYMENT_VALIDITY_SECONDS": 30 * 60, # Payment validity window in seconds (default: 30 minutes)
}

If you need a better RPC control, use BaseSolanaClient(client_factory=…). That allows specifying custom options for AsyncClient.

Migrate and Route

python manage.py migrate

# Add this to your urls.py
urlpatterns = [
    path('solana-payments/', include('django_solana_payments.urls')),
]

Create payment tokens (required)

Open the admin panel and create at least one active payment token before initiating payments. A common setup is:
- Native SOL token (token_type=NATIVE, mint_address empty)
- USDC SPL token (token_type=SPL, with the correct USDC mint for your network)
See Payment Tokens for model fields, validation rules, and examples.
Continue with API usage

See DRF API Usage for endpoint details and request examples.

Root level imports

For common flows you can import the root helpers directly:

from django_solana_payments import (
    create_payment,
    verify_transaction_and_process_payment,
)

payment = create_payment(
    {
        "label": "Premium Plan",
        "message": "Monthly subscription",
        "meta_data": {"order_id": "sub-1001"},
    }
)

status = verify_transaction_and_process_payment(
    payment_address=payment.payment_address,
    payment_crypto_token=my_token,
)

For explicit service classes, see API Reference.

For async-capable usage and AsyncClient details, see Async Support.