django-solana-payments 0.2.2

A plug-and-play Django library for accepting online payments via the Solana blockchain

Django Solana Payments

A Django library for integrating Solana payments into your project. This library provides a flexible and customizable way to accept Solana payments with support for customizable models, an easy-to-use API, and management commands for processing online payments using the Solana blockchain.

Key Features

• Transaction verification and automatic payment confirmation: Monitors the Solana blockchain, verifies incoming transactions, and automatically confirms payments when the expected amount is received.
• Multi-token support (SOL and SPL tokens): Configure a list of active payment tokens (for example, SOL and USDC) and the library will use them for pricing and verification flows.
• Flexibility and customization: Use your own custom models for payments and tokens to fit your project's needs. Add custom logic using signals or callabacks.
• Ease of integration: Provides ready-to-use endpoints that can be used in existing DRF applications, or ready-to-use methods for Django applications that are not part of DRF.
• Security and encryption: Provides an out-of-the-box encryption mechanism that helps keep one-time payment wallets secure.
• Management commands: Includes management commands for handling expired payments and sending funds from one-time wallets.

Documentation

See the full documentation at https://django-solana-payments.readthedocs.io/

Installation

1. 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]"
   

   This provides ready-to-use API endpoints for creating and managing payments.

2. Configure settings.py

   INSTALLED_APPS = [
       ...,
       'django_solana_payments',
   ]
   
   SOLANA_PAYMENTS = {
       "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 will be derived from the keypair)
       # FEE_PAYER_ADDRESS is derived from FEE_PAYER_KEYPAIR; you don't normally need to set it separately.
       "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()
       "SOLANA_PAYMENT_MODEL": "payments.CustomSolanaPayment", # Custom model for solana payment
       "PAYMENT_CRYPTO_TOKEN_MODEL": "payments.CustomPaymentToken", # Custom model for solana payment token
       "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 (needed for oen time wallets creation)
       "PAYMENT_VALIDITY_SECONDS": 30 * 60, # Payment validity window in seconds (default: 30 minutes)
   }
   

3. Migrate and Route

python manage.py migrate

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

4. Open the admin panel and create payment token records, specifying the correct mint addresses for SPL tokens.

Integration in 3 simple steps

Start accepting Solana payments with a fast, production-ready flow designed for real checkout UX.

Integration flow

Typical API flow:

1. Call POST /solana-payments/initiate/ to create a payment and receive payment_address.
2. Show that address/QR code to the payer, then the payer sends funds to the payment_address.
3. Poll GET /solana-payments/verify-transfer/{payment_address}?token_type=... until status becomes confirmed or finalized.

Common UI examples:

• Connect crypto wallet -> show payment summary in the wallet extension -> user signs and sends transaction -> app checks payment status.
• Open wallet app (Phantom/Solflare/mobile wallet) -> scan the QR code -> send expected amount -> return to your app -> app payment checks status.

Optionally call GET /solana-payments/payments/{payment_address}/ for details.

Demo

Running the Example Project

The included example project provides a demonstration of how to use the library and what it can do. To run it:

1. Navigate to the example project directory

   cd examples/demo_project
   

2. Install dependencies

   pip install -r requirements.txt
   

3. Run migrations

   python mange.py makemigrations
   python manage.py migrate
   

4. Start the development server

   ./dev_server.sh
   

Running Tests

To run the tests for the library:

1. Install test dependencies

   pip install pytest pytest-django
   

2. Run the tests

   pytest
   

License

This package is licensed under the MIT License. See the LICENSE file for more details.

Contributing

Contributions are welcome. Please read CONTRIBUTING.md for setup instructions, testing, feature proposals, and pull request guidelines.

If you find this project useful, consider giving it a star to support its development!

Developer Guide

Local setup

1. Clone the repository and create a virtual environment:

   git clone https://github.com/Artemooon/django-solana-payments.git
   cd django-solana-payments
   python -m venv .venv
   source .venv/bin/activate
   

2. Install development dependencies:

   pip install -e ".[dev,docs,drf]"
   

3. Run tests:

   pytest
   

Install pre-commit

Install and enable git hooks:

pip install pre-commit # (if not installed)
pre-commit install

Release process

1. Bump version in pyproject.toml.

2. Commit and tag:

   git add -A
   git commit -m "Release x.y.z"
   git tag vx.y.z
   git push origin main --tags
   

The GitHub Release workflow publish automatically on pushed tags.