Payment Tokens

This page explains how to create and configure payment tokens that your project accepts. Payment tokens determine which cryptocurrencies (native SOL or SPL tokens) your project accepts and what amount (price) a payment should be in crypto units.

Token types and model fields

django-solana-payments exposes an abstract model AbstractPaymentToken and a concrete implementation PaymentCryptoToken.

Key fields (on PaymentCryptoToken / your custom token model):

is_active (bool) — whether this token is currently accepted for payments.
token_type (enum) — either NATIVE (SOL) or SPL (SPL token). Choose SPL when using a token mint address.
mint_address (string) — required for SPL tokens, must be null for NATIVE tokens. The model enforces this via a database constraint.
payment_crypto_price (Decimal) — the amount in crypto units that corresponds to a single payment for this token.
name, symbol, meta_data — optional metadata fields on the concrete PaymentCryptoToken.

Important validation rules

For token_type == SPL, mint_address is required.
For token_type == NATIVE, mint_address must be null.

These rules are enforced by the model clean() method and by a database CheckConstraint on PaymentCryptoToken.

Database prerequisites

Run migrations after you install the package or add your custom models:

python manage.py makemigrations
python manage.py migrate

If you use custom token models, make sure your custom app is included in INSTALLED_APPS and SOLANA_PAYMENTS settings points to your model path, for example:
```
SOLANA_PAYMENTS = {
    "PAYMENT_CRYPTO_TOKEN_MODEL": "solana_payments.CustomPaymentToken",
    # ... other settings
}
```

Creating tokens (examples)

You can add tokens either through the Django admin or the Django shell.

Via Admin

Open the Django admin, find the PaymentCryptoToken (or your custom model) and create a new record. For SPL tokens provide the mint_address and set is_active to True.
Via shell

# Start a shell
python manage.py shell

from django_solana_payments.models import PaymentCryptoToken

# Native SOL token example
PaymentCryptoToken.objects.create(
    name='SOL',
    symbol='SOL',
    token_type='NATIVE',
    payment_crypto_price=0.001,
    is_active=True,
)

# SPL token example
PaymentCryptoToken.objects.create(
    name='MyToken',
    symbol='MTK',
    token_type='SPL',
    mint_address='TokenMintAddressHere',
    payment_crypto_price=10.0,
    is_active=True,
)

Generating payment prices

The library provides a helper method on SolanaPaymentsService that will transform active PaymentCryptoToken records into SolanaPayPaymentCryptoPrice objects which are used when creating a SolanaPayment:

SolanaPaymentsService.create_payment_crypto_prices_from_allowed_payment_crypto_tokens()

When you create a new payment using SolanaPaymentsService.create_payment() or the API endpoints, the service will automatically create and attach crypto price objects for the active tokens. You can also call the helper directly to pre-generate prices.

API and DRF

If you installed the drf extra, the library exposes a read-only endpoint for payment tokens at /payments/payments-tokens/ (see AllowedPaymentCryptoTokenViewSet). Use that endpoint to list active tokens and their mint addresses.

Checklist before accepting payments

[ ] Run migrations and confirm the PaymentCryptoToken table exists.
[ ] Create at least one active token with valid fields (for SPL tokens set mint_address).
[ ] If you use custom models, confirm SOLANA_PAYMENTS[“PAYMENT_CRYPTO_TOKEN_MODEL”] points to the correct model path.
[ ] Optionally, pre-generate crypto prices using create_payment_crypto_prices_from_allowed_payment_crypto_tokens() or let the service create them when you create payments.

Troubleshooting

If you see a ValidationError when saving a token, verify the token_type and mint_address values match the rules described above.
If the API shows no tokens, ensure is_active=True and the object is saved in the correct database and app.