Payments Domain - Models Documentation

class PaymentProcessor(SanityIntegratedModel, AuditableMixin):
    name = models.CharField(max_length=255)
    processor_type = models.CharField(max_length=50, choices=[...])
    is_active = models.BooleanField(default=True)
    is_test_mode = models.BooleanField(default=False)
    configuration = models.JSONField(default=dict, blank=True)
    processing_fee_percentage = models.DecimalField(max_digits=6, decimal_places=4, null=True, blank=True)
    processing_fee_fixed = models.DecimalField(max_digits=10, decimal_places=2, null=True, blank=True)
    default_currency = models.CharField(max_length=3, default='USD')

help_text=(
    'Payment Processor Configuration - NON-SENSITIVE settings only '
    '(e.g., webhook URLs, timeout values, display preferences). '
    'DO NOT store API keys, tokens, or secrets here. '
    'Credentials are loaded from environment variables (.env) in development '
    'and Docker secrets in production. See settings/base.py for credential configuration.'
)

{
  "webhook_url": "https://api.example.com/webhooks/stripe",
  "timeout_seconds": 30,
  "retry_attempts": 3,
  "display_name": "Credit Card Processing"
}

{
  "api_key": "sk_live_...",  // FORBIDDEN
  "secret": "whsec_...",      // FORBIDDEN
  "access_token": "..."       // FORBIDDEN
}

# Stripe charges 2.9% + $0.30
processing_fee_percentage = Decimal('0.0290')
processing_fee_fixed = Decimal('0.30')

# For a $100 payment:
fee = (Decimal('100.00') * processing_fee_percentage) + processing_fee_fixed
# fee = $2.90 + $0.30 = $3.20

def clean(self):
    if self.default_currency and len(self.default_currency) != 3:
        raise ValidationError('Default currency must be a 3-letter code')

class Meta:
    db_table = 'payment_processor'
    ordering = ['name']
    indexes = [
        models.Index(fields=['processor_type'], name='payment_processor_type_idx'),
        models.Index(fields=['is_active'], name='payment_processor_active_idx'),
    ]

def __str__(self):
    status = 'Active' if self.is_active else 'Inactive'
    mode = ' (Test)' if self.is_test_mode else ''
    return f'{self.name} - {self.processor_type} - {status}{mode}'

def save(self, *args, **kwargs):
    self.full_clean()
    super().save(*args, **kwargs)

def clean(self):
    super().clean()
    if self.default_currency and len(self.default_currency) != 3:
        raise ValidationError('Default currency must be a 3-letter code')

from nextango.apps.payments.models import PaymentProcessor

processor = PaymentProcessor.objects.create(
    name='Stripe Production',
    processor_type='stripe',
    is_active=True,
    is_test_mode=False,
    processing_fee_percentage=Decimal('0.0290'),
    processing_fee_fixed=Decimal('0.30'),
    default_currency='USD',
    configuration={
        'webhook_url': 'https://api.example.com/webhooks/stripe',
        'timeout_seconds': 30
    }
)

# Get all active processors
active_processors = PaymentProcessor.objects.filter(is_active=True)

# Get production processors only
production = PaymentProcessor.objects.filter(
    is_active=True,
    is_test_mode=False
)

# Get Stripe processor
stripe = PaymentProcessor.objects.get(processor_type='stripe', is_active=True)

class PaymentMethod(SanityIntegratedModel, AuditableMixin):
    name = models.CharField(max_length=255)
    method_type = models.CharField(max_length=50, choices=[...])
    processor = models.ForeignKey(PaymentProcessor, on_delete=models.SET_NULL, null=True, blank=True)
    is_active = models.BooleanField(default=True)
    is_online_available = models.BooleanField(default=True)
    is_pos_available = models.BooleanField(default=True)
    minimum_amount = models.DecimalField(max_digits=10, decimal_places=2, default=0.01)
    maximum_amount = models.DecimalField(max_digits=10, decimal_places=2, null=True, blank=True)
    configuration = models.JSONField(default=dict, blank=True)
    display_order = models.IntegerField(default=0)
    icon_url = models.URLField(null=True, blank=True)
    description = models.TextField(blank=True)

# Cash doesn't need a processor
cash_method = PaymentMethod.objects.create(
    name='Cash',
    method_type='cash',
    processor=None  # No processor needed
)

# Credit cards require a processor
credit_card_method = PaymentMethod.objects.create(
    name='Visa/Mastercard',
    method_type='credit_card',
    processor=stripe_processor  # Links to PaymentProcessor
)

def clean(self):
    if self.maximum_amount and self.minimum_amount > self.maximum_amount:
        raise ValidationError('Minimum amount cannot be greater than maximum amount')

{
  "accepted_brands": ["visa", "mastercard", "amex"],
  "requires_cvv": true,
  "allows_installments": false,
  "max_installments": 12
}

cash = PaymentMethod.objects.create(name='Cash', display_order=0)           # Shown first
credit = PaymentMethod.objects.create(name='Credit Card', display_order=1)  # Shown second
store_credit = PaymentMethod.objects.create(name='Store Credit', display_order=2)  # Shown third

class Meta:
    db_table = 'payment_method'
    ordering = ['display_order', 'name']
    indexes = [
        models.Index(fields=['method_type'], name='payment_method_type_idx'),
        models.Index(fields=['is_active'], name='payment_method_active_idx'),
        models.Index(fields=['display_order'], name='payment_method_order_idx'),
    ]

def __str__(self):
    status = 'Active' if self.is_active else 'Inactive'
    return f'{self.name} ({self.method_type}) - {status}'

def clean(self):
    super().clean()
    if self.maximum_amount and self.minimum_amount > self.maximum_amount:
        raise ValidationError('Minimum amount cannot be greater than maximum amount')

from nextango.apps.payments.models import PaymentMethod, PaymentProcessor

# Cash payment (no processor needed)
cash = PaymentMethod.objects.create(
    name='Cash',
    method_type='cash',
    processor=None,
    is_online_available=False,  # Cash only at POS
    minimum_amount=Decimal('0.01'),
    maximum_amount=Decimal('10000.00'),
    display_order=0
)

# Credit card payment (requires processor)
stripe_processor = PaymentProcessor.objects.get(processor_type='stripe')
credit_card = PaymentMethod.objects.create(
    name='Visa/Mastercard',
    method_type='credit_card',
    processor=stripe_processor,
    is_online_available=True,
    is_pos_available=True,
    minimum_amount=Decimal('1.00'),
    configuration={
        'accepted_brands': ['visa', 'mastercard', 'amex'],
        'requires_cvv': True
    },
    display_order=1,
    icon_url='https://cdn.example.com/icons/credit-card.png'
)

# Get all active POS payment methods
pos_methods = PaymentMethod.objects.filter(
    is_active=True,
    is_pos_available=True
).order_by('display_order')

# Get online-available payment methods
online_methods = PaymentMethod.objects.filter(
    is_active=True,
    is_online_available=True
)

# Get payment methods for specific processor
stripe_methods = PaymentMethod.objects.filter(
    processor__processor_type='stripe',
    is_active=True
)

class PaymentMethodStore(models.Model):
    payment_method = models.ForeignKey(
        PaymentMethod,
        on_delete=models.CASCADE,
        related_name='available_at_stores'
    )
    store = models.ForeignKey(
        'stores.Store',
        on_delete=models.CASCADE,
        related_name='available_payment_methods'
    )

class Meta:
    db_table = 'payment_method_store'
    unique_together = [['payment_method', 'store']]

from nextango.apps.payments.models import PaymentMethod, PaymentMethodStore
from nextango.apps.stores.models import Store

# Get store and payment methods
store_a = Store.objects.get(store_code='STORE-A')
store_b = Store.objects.get(store_code='STORE-B')

cash = PaymentMethod.objects.get(method_type='cash')
credit_card = PaymentMethod.objects.get(method_type='credit_card')
apple_pay = PaymentMethod.objects.get(name='Apple Pay')

# Store A: Cash and credit card only
PaymentMethodStore.objects.create(payment_method=cash, store=store_a)
PaymentMethodStore.objects.create(payment_method=credit_card, store=store_a)

# Store B: All payment methods including Apple Pay
PaymentMethodStore.objects.create(payment_method=cash, store=store_b)
PaymentMethodStore.objects.create(payment_method=credit_card, store=store_b)
PaymentMethodStore.objects.create(payment_method=apple_pay, store=store_b)

# Get all payment methods available at a specific store
store = Store.objects.get(store_code='STORE-A')
available_methods = PaymentMethod.objects.filter(
    available_at_stores__store=store,
    is_active=True
).order_by('display_order')

# Get all stores where a payment method is available
payment_method = PaymentMethod.objects.get(name='Apple Pay')
stores_with_apple_pay = Store.objects.filter(
    available_payment_methods__payment_method=payment_method,
    is_active=True
)

# Check if payment method is available at specific store
is_available = PaymentMethodStore.objects.filter(
    payment_method=apple_pay,
    store=store
).exists()

class TransactionPayment(SanityIntegratedModel, AuditableMixin):
    transaction = models.ForeignKey('transactions.SaleTransaction', on_delete=models.CASCADE)
    payment_method = models.ForeignKey(PaymentMethod, on_delete=models.PROTECT)
    purchased_items = models.ManyToManyField('transactions.SaleLineItem', blank=True)
    payment_method_type = models.CharField(max_length=50, choices=[...], null=True, blank=True)
    amount = models.DecimalField(max_digits=10, decimal_places=2)
    tender_amount = models.DecimalField(max_digits=10, decimal_places=2, null=True, blank=True)
    change_due = models.DecimalField(max_digits=10, decimal_places=2, null=True, blank=True)
    status = models.CharField(max_length=20, choices=[...], default='pending')
    processing_fee = models.DecimalField(max_digits=10, decimal_places=2, default=0.00)
    net_amount = models.DecimalField(max_digits=10, decimal_places=2, default=0.00)

# A transaction can have multiple payments (split payment)
transaction = SaleTransaction.objects.get(transactionId='TXN-20251117-ABC123')
payments = transaction.payment_records.all()

# Total paid
total_paid = sum(p.amount for p in payments if p.status == 'succeeded')

# Customer pays for items 1-2 with cash, items 3-4 with credit card
transaction = SaleTransaction.objects.get(pk=transaction_id)
items_1_2 = transaction.line_items.filter(id__in=[item1_id, item2_id])
items_3_4 = transaction.line_items.filter(id__in=[item3_id, item4_id])

cash_payment = TransactionPayment.objects.create(
    transaction=transaction,
    payment_method=cash_method,
    amount=Decimal('50.00')
)
cash_payment.purchased_items.set(items_1_2)

card_payment = TransactionPayment.objects.create(
    transaction=transaction,
    payment_method=credit_card_method,
    amount=Decimal('75.00')
)
card_payment.purchased_items.set(items_3_4)

def save(self, *args, **kwargs):
    # Auto-populate from payment_method on save
    if self.payment_method and not self.payment_method_type:
        self.payment_method_type = self.payment_method.method_type
    super().save(*args, **kwargs)

# Fast query without JOIN
cash_payments = TransactionPayment.objects.filter(payment_method_type='cash')

# vs slower query with JOIN
cash_payments = TransactionPayment.objects.filter(payment_method__method_type='cash')

# Customer pays $50 cash for $42.75 purchase
payment = TransactionPayment.objects.create(
    transaction=transaction,
    payment_method=cash_method,
    amount=Decimal('42.75'),
    tender_amount=Decimal('50.00'),
    change_due=Decimal('7.25')  # $50.00 - $42.75
)

pending → succeeded  (successful payment)
pending → failed     (declined/error)

def save(self, *args, **kwargs):
    if self.amount and self.processing_fee:
        self.net_amount = self.amount - self.processing_fee
    else:
        self.net_amount = self.amount or 0
    super().save(*args, **kwargs)

# $100 payment with $3.20 processing fee
payment = TransactionPayment(
    amount=Decimal('100.00'),
    processing_fee=Decimal('3.20')
)
payment.save()
# payment.net_amount = $96.80 (automatically calculated)

{
  "id": "ch_3NqXYZ...",
  "object": "charge",
  "amount": 10000,
  "currency": "usd",
  "status": "succeeded",
  "payment_method_details": {
    "type": "card",
    "card": {
      "brand": "visa",
      "last4": "4242"
    }
  }
}

def clean(self):
    if self.risk_score is not None and (self.risk_score < 0 or self.risk_score > 100):
        raise ValidationError('Risk score must be between 0 and 100')

# Create cash drawer "sale" event when cash payment succeeds
cash_payment = TransactionPayment.objects.create(
    transaction=transaction,
    payment_method=cash_method,
    amount=Decimal('42.75'),
    status='succeeded'
)

# Create corresponding cash drawer event
from nextango.apps.transactions.models import CashDrawerEvent
drawer_event = CashDrawerEvent.objects.create(
    store=transaction.store,
    employee=transaction.employee,
    event_type='sale',
    amount=cash_payment.amount,
    transaction=transaction
)

# Link payment to drawer event
cash_payment.cash_drawer_event = drawer_event
cash_payment.save()

{
  "device_id": "POS-REGISTER-001",
  "cashier_id": "EMP-12345",
  "receipt_number": "RCP-20251117-001",
  "customer_signature": "data:image/png;base64,..."
}

import uuid

idempotency_key = str(uuid.uuid4())

# First attempt
payment1 = TransactionPayment.objects.create(
    transaction=transaction,
    payment_method=credit_card,
    amount=Decimal('100.00'),
    idempotency_key=idempotency_key
)
# Success

# Network error causes retry with same key
payment2 = TransactionPayment.objects.create(
    transaction=transaction,
    payment_method=credit_card,
    amount=Decimal('100.00'),
    idempotency_key=idempotency_key  # Same key
)
# Raises IntegrityError - duplicate prevented

payment = TransactionPayment.objects.create(
    transaction=transaction,
    payment_method=credit_card,
    amount=Decimal('250.00'),
    three_d_secure_status='authenticated',  # Passed 3DS
    cvv_verification_status='match',        # CVV matches
    avs_verification_status='match',        # Address matches
    risk_score=Decimal('15.00')             # Low risk
)
# High confidence - auto-approve

def save(self, *args, **kwargs):
    # Set data retention date (7 years for PCI compliance) only on creation
    if self.pk is None and not self.data_retention_date:
        from django.utils import timezone
        self.data_retention_date = timezone.now() + timezone.timedelta(days=2555)  # 7 years
    super().save(*args, **kwargs)

def anonymize_payment_data(payment):
    """Anonymize sensitive payment data after retention period."""
    payment.last_four_digits = 'XXXX'
    payment.card_brand = ''
    payment.processor_response = {}
    payment.metadata = {}
    payment.anonymized_at = timezone.now()
    payment.save()

payment = TransactionPayment.objects.get(pk=payment_id)
display_text = f"{payment.card_brand} ending in {payment.last_four_digits}"
# Output: "Visa ending in 4242"

class Meta:
    db_table = 'payment'
    ordering = ['-created_at']
    indexes = [
        models.Index(fields=['status'], name='payment_status_idx'),
        models.Index(fields=['processor_transaction_id'], name='payment_processor_id_idx'),
        models.Index(fields=['transaction'], name='payment_transaction_idx'),
        models.Index(fields=['payment_method'], name='payment_method_idx'),
        models.Index(fields=['processed_at'], name='payment_processed_idx'),
    ]

def __str__(self):
    return f'TransactionPayment \${self.amount} via {self.payment_method.name} - {self.status}'

def clean(self):
    super().clean()
    if self.amount <= 0:
        raise ValidationError('Payment amount must be greater than 0')

    if self.risk_score is not None and (self.risk_score < 0 or self.risk_score > 100):
        raise ValidationError('Risk score must be between 0 and 100')

def save(self, *args, **kwargs):
    # 1. Denormalize payment_method_type
    if self.payment_method and not self.payment_method_type:
        self.payment_method_type = self.payment_method.method_type

    # 2. Calculate net amount
    if self.amount and self.processing_fee:
        self.net_amount = self.amount - self.processing_fee
    else:
        self.net_amount = self.amount or 0

    # 3. Set data retention date (7 years for PCI compliance) only on creation
    if self.pk is None and not self.data_retention_date:
        from django.utils import timezone
        self.data_retention_date = timezone.now() + timezone.timedelta(days=2555)

    super().save(*args, **kwargs)

from nextango.apps.payments.models import TransactionPayment, PaymentMethod

cash_method = PaymentMethod.objects.get(method_type='cash')
transaction = SaleTransaction.objects.get(transactionId='TXN-20251117-ABC123')

payment = TransactionPayment.objects.create(
    transaction=transaction,
    payment_method=cash_method,
    amount=Decimal('42.75'),
    tender_amount=Decimal('50.00'),
    change_due=Decimal('7.25'),
    status='succeeded',
    processed_at=timezone.now()
)

credit_card_method = PaymentMethod.objects.get(method_type='credit_card')

payment = TransactionPayment.objects.create(
    transaction=transaction,
    payment_method=credit_card_method,
    amount=Decimal('125.50'),
    status='pending',
    idempotency_key=str(uuid.uuid4()),
    three_d_secure_status='authenticated',
    cvv_verification_status='match',
    avs_verification_status='match',
    risk_score=Decimal('12.50'),
    last_four_digits='4242',
    card_brand='Visa',
    funding_source='credit'
)

# After processor confirms
payment.status = 'succeeded'
payment.processor_transaction_id = 'ch_3NqXYZ...'
payment.processor_response = {
    'id': 'ch_3NqXYZ...',
    'status': 'succeeded'
}
payment.processing_fee = Decimal('3.64')  # 2.9% + $0.30
payment.processed_at = timezone.now()
payment.save()  # net_amount auto-calculated to $121.86

# Total: $200 - pay $100 cash, $100 credit
transaction = SaleTransaction.objects.get(pk=transaction_id)

# Cash payment
cash_payment = TransactionPayment.objects.create(
    transaction=transaction,
    payment_method=cash_method,
    amount=Decimal('100.00'),
    status='succeeded'
)

# Credit card payment
card_payment = TransactionPayment.objects.create(
    transaction=transaction,
    payment_method=credit_card_method,
    amount=Decimal('100.00'),
    status='succeeded'
)

# Verify total payments match transaction total
total_payments = transaction.payment_records.filter(status='succeeded').aggregate(
    total=Sum('amount')
)['total']
assert total_payments == transaction.totalAmount

class Refund(SanityIntegratedModel, AuditableMixin):
    refund_id = models.CharField(max_length=50, unique=True, null=True, blank=True, editable=False)
    payment = models.ForeignKey(TransactionPayment, on_delete=models.CASCADE)
    amount = models.DecimalField(max_digits=10, decimal_places=2)
    reason = models.CharField(max_length=255, blank=True)
    status = models.CharField(max_length=20, choices=[...], default='pending')
    processor_refund_id = models.CharField(max_length=255, null=True, blank=True)
    processed_at = models.DateTimeField(null=True, blank=True)
    sales_return = models.ForeignKey('transactions.Return', on_delete=models.SET_NULL, null=True, blank=True)
    metadata = models.JSONField(default=dict, blank=True)

def save(self, *args, **kwargs):
    if not self.refund_id:
        import uuid
        from django.utils import timezone
        date_str = timezone.now().strftime('%Y%m%d')
        unique_id = uuid.uuid4().hex[:8].upper()
        self.refund_id = f'REF-{date_str}-{unique_id}'
    super().save(*args, **kwargs)

# Get all refunds for a payment
payment = TransactionPayment.objects.get(pk=payment_id)
refunds = payment.refunds.all()

# Calculate total refunded
total_refunded = refunds.filter(status='succeeded').aggregate(
    total=Sum('amount')
)['total'] or Decimal('0.00')

# Calculate remaining refundable amount
refundable = payment.amount - total_refunded

def clean(self):
    if self.amount <= 0:
        raise ValidationError('Refund amount must be greater than 0')

    if self.payment and self.amount > self.payment.amount:
        raise ValidationError('Refund amount cannot exceed original payment amount')

pending → succeeded  (refund processed)
pending → failed     (processor error)

# STEP 1: Process refund FIRST (sales_return=None initially)
refund = Refund.objects.create(
    payment=original_payment,
    amount=total_return_value,
    reason=f'Return for transaction {transaction_id}',
    sales_return=None,  # No return exists yet
    status='pending'
)

# STEP 2: Create return record AFTER refunds processed
sales_return = Return.objects.create_return(
    original_transaction=original_transaction,
    employee=employee,
    reason=reason
)

# STEP 3: Link refunds to return
refund.sales_return = sales_return
refund.save(update_fields=['sales_return'])

{
  "initiated_by": "MANAGER-12345",
  "approval_code": "APR-20251117-001",
  "refund_method": "original_payment_method",
  "customer_notification_sent": true
}

class Meta:
    db_table = 'refund'
    ordering = ['-created_at']
    indexes = [
        models.Index(fields=['status'], name='refund_status_idx'),
        models.Index(fields=['payment'], name='refund_payment_idx'),
        models.Index(fields=['processed_at'], name='refund_processed_idx'),
    ]

def __str__(self):
    return f'{self.refund_id} - \${self.amount} - {self.status}' if self.refund_id else f'Refund \${self.amount}'

def save(self, *args, **kwargs):
    if not self.refund_id:
        import uuid
        from django.utils import timezone
        date_str = timezone.now().strftime('%Y%m%d')
        unique_id = uuid.uuid4().hex[:8].upper()
        self.refund_id = f'REF-{date_str}-{unique_id}'
    super().save(*args, **kwargs)

def clean(self):
    super().clean()
    if self.amount <= 0:
        raise ValidationError('Refund amount must be greater than 0')

    if self.payment and self.amount > self.payment.amount:
        raise ValidationError('Refund amount cannot exceed original payment amount')

from nextango.apps.payments.models import Refund

payment = TransactionPayment.objects.get(pk=payment_id)

refund = Refund.objects.create(
    payment=payment,
    amount=payment.amount,  # Full refund
    reason='Order cancelled by customer',
    status='pending'
)

# After processor confirms
refund.status = 'succeeded'
refund.processor_refund_id = 're_3NqXYZ...'
refund.processed_at = timezone.now()
refund.save()

# Original payment: $100
# Refund: $25 for one returned item

refund = Refund.objects.create(
    payment=payment,
    amount=Decimal('25.00'),  # Partial refund
    reason='One item returned - defective',
    status='pending'
)

# Customer returns items, refund issued
sales_return = Return.objects.get(returnId='RET-20251117-ABC123')
original_transaction = sales_return.originalSaleId

# Find original payment(s)
original_payments = TransactionPayment.objects.filter(
    transaction=original_transaction,
    status='succeeded'
).order_by('-created_at')

# Issue refund to most recent payment
refund = Refund.objects.create(
    payment=original_payments.first(),
    amount=sales_return.refund_amount,
    reason=f"Return: {sales_return.reason}",
    sales_return=sales_return,
    status='pending'
)

def get_refundable_amount(payment):
    """Calculate remaining refundable amount for a payment."""
    total_refunded = payment.refunds.filter(
        status='succeeded'
    ).aggregate(total=Sum('amount'))['total'] or Decimal('0.00')

    return payment.amount - total_refunded

# Usage
payment = TransactionPayment.objects.get(pk=payment_id)
refundable = get_refundable_amount(payment)

if refund_amount > refundable:
    raise ValidationError(f'Cannot refund \${refund_amount}. Only \${refundable} available.')

class WebhookEvent(models.Model):
    event_id = models.CharField(max_length=255, unique=True, db_index=True)
    event_type = models.CharField(max_length=100)
    processor = models.CharField(max_length=50, choices=[...])
    status = models.CharField(max_length=20, choices=[...], default='pending')
    raw_payload = models.JSONField()
    error_message = models.TextField(blank=True)
    payment = models.ForeignKey(TransactionPayment, on_delete=models.SET_NULL, null=True, blank=True)
    processed_at = models.DateTimeField(null=True, blank=True)
    created_at = models.DateTimeField(auto_now_add=True)

# Webhook received
event_id = webhook_payload.get('id')

# Check if already processed
if WebhookEvent.objects.filter(event_id=event_id).exists():
    logger.info(f"Webhook {event_id} already processed - skipping")
    return HttpResponse(status=200)  # Return success to prevent retries

# First time - create event
webhook_event = WebhookEvent.objects.create(
    event_id=event_id,
    event_type=webhook_payload.get('type'),
    processor='stripe',
    raw_payload=webhook_payload,
    status='pending'
)

pending → processed  (webhook handled successfully)
pending → failed     (processing error)

{
  "id": "evt_1NqXYZ...",
  "object": "event",
  "type": "payment_intent.succeeded",
  "data": {
    "object": {
      "id": "pi_3NqXYZ...",
      "amount": 10000,
      "currency": "usd",
      "status": "succeeded"
    }
  },
  "created": 1699564800
}

try:
    # Process webhook
    process_payment_webhook(webhook_event)
    webhook_event.status = 'processed'
    webhook_event.processed_at = timezone.now()
except Exception as e:
    webhook_event.status = 'failed'
    webhook_event.error_message = str(e)
    logger.error(f"Webhook processing failed: {e}")
finally:
    webhook_event.save()

# After processing webhook, link to payment
payment = TransactionPayment.objects.get(processor_transaction_id=charge_id)
webhook_event.payment = payment
webhook_event.save()

# Later: View all webhook events for a payment
payment_webhooks = payment.webhook_events.all().order_by('-created_at')

class Meta:
    db_table = 'webhook_event'
    ordering = ['-created_at']
    indexes = [
        models.Index(fields=['event_id'], name='webhook_event_id_idx'),
        models.Index(fields=['processor', 'status'], name='webhook_processor_status_idx'),
        models.Index(fields=['created_at'], name='webhook_created_idx'),
    ]

def __str__(self):
    return f'{self.processor} - {self.event_type} ({self.event_id}) - {self.status}'

from nextango.apps.payments.models import WebhookEvent, TransactionPayment
import stripe

@csrf_exempt
def stripe_webhook_view(request):
    payload = request.body
    sig_header = request.META.get('HTTP_STRIPE_SIGNATURE')

    try:
        event = stripe.Webhook.construct_event(
            payload, sig_header, settings.STRIPE_WEBHOOK_SECRET
        )
    except ValueError:
        return HttpResponse(status=400)
    except stripe.error.SignatureVerificationError:
        return HttpResponse(status=400)

    # Check idempotency
    event_id = event['id']
    if WebhookEvent.objects.filter(event_id=event_id).exists():
        return HttpResponse(status=200)  # Already processed

    # Create webhook event record
    webhook_event = WebhookEvent.objects.create(
        event_id=event_id,
        event_type=event['type'],
        processor='stripe',
        raw_payload=event,
        status='pending'
    )

    # Process event
    try:
        if event['type'] == 'payment_intent.succeeded':
            payment_intent = event['data']['object']
            payment = TransactionPayment.objects.get(
                processor_transaction_id=payment_intent['id']
            )
            payment.status = 'succeeded'
            payment.processed_at = timezone.now()
            payment.save()

            # Link webhook to payment
            webhook_event.payment = payment

        webhook_event.status = 'processed'
        webhook_event.processed_at = timezone.now()
        webhook_event.save()

        return HttpResponse(status=200)

    except Exception as e:
        webhook_event.status = 'failed'
        webhook_event.error_message = str(e)
        webhook_event.save()
        return HttpResponse(status=500)

def retry_failed_webhooks():
    """Retry failed webhook processing."""
    failed_webhooks = WebhookEvent.objects.filter(
        status='failed',
        created_at__gte=timezone.now() - timedelta(hours=24)
    )

    for webhook in failed_webhooks:
        try:
            # Re-process webhook
            process_webhook_event(webhook)
            webhook.status = 'processed'
            webhook.processed_at = timezone.now()
            webhook.error_message = ''
            webhook.save()
        except Exception as e:
            webhook.error_message = f"Retry failed: {str(e)}"
            webhook.save()

# Get all Stripe webhooks from last 7 days
recent_stripe_webhooks = WebhookEvent.objects.filter(
    processor='stripe',
    created_at__gte=timezone.now() - timedelta(days=7)
).order_by('-created_at')

# Get failed webhooks needing attention
failed_webhooks = WebhookEvent.objects.filter(
    status='failed'
).select_related('payment')

# Get all webhooks for a specific payment
payment = TransactionPayment.objects.get(pk=payment_id)
payment_webhook_history = payment.webhook_events.all().order_by('-created_at')

PaymentProcessor (1) ───────< (∞) PaymentMethod
                                      │
                                      │ (1)
                                      │
                                      ↓
                                 (∞) PaymentMethodStore (∞) ───> (1) Store
                                      │
                                      │ (1)
                                      │
                                      ↓
                                 (∞) TransactionPayment ───> (1) SaleTransaction
                                      │                        │
                                      │                        │
                                      ↓                        ↓
                                 (∞) Refund              (∞) SaleLineItem
                                      │                        ↑
                                      │                        │
                                      ↓                        │ (M:M)
                              (1) Return ──────────────────────┘

TransactionPayment (1) <───────< (∞) WebhookEvent

TransactionPayment (∞) >───────< (∞) SaleLineItem (via purchased_items M:M)

TransactionPayment (1) ───────> (1) CashDrawerEvent

stripe_processor = PaymentProcessor.objects.get(processor_type='stripe')

# All payment methods using Stripe
stripe_methods = stripe_processor.payment_methods.all()
# Example: Credit Card, Debit Card, Digital Wallet (all via Stripe)