Payments Domain - Serializers Documentation

class PaymentProcessorSerializer(serializers.ModelSerializer):
    payment_methods_count = serializers.SerializerMethodField()

    class Meta:
        model = PaymentProcessor
        fields = [
            'id', 'sanity_id', 'name', 'processor_type', 'is_active', 'is_test_mode',
            'configuration', 'processing_fee_percentage', 'processing_fee_fixed',
            'default_currency', 'payment_methods_count', 'created_at', 'updated_at'
        ]
        read_only_fields = ['id', 'created_at', 'updated_at', 'payment_methods_count']

def get_payment_methods_count(self, obj):
    return obj.payment_methods.count()

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "sanity_id": "processor-stripe-prod",
  "name": "Stripe Production",
  "processor_type": "stripe",
  "is_active": true,
  "is_test_mode": false,
  "processing_fee_percentage": "0.0290",
  "processing_fee_fixed": "0.30",
  "default_currency": "USD",
  "payment_methods_count": 3,
  "created_at": "2025-01-15T10:30:00Z",
  "updated_at": "2025-01-15T10:30:00Z"
}

def to_internal_value(self, data):
    """Handle nested Sanity webhook data with field name conversion."""
    from ..integrations.sync.field_mappings import bidirectional_field_mapper

    # Convert camelCase to snake_case for payments domain
    converted_data = {}
    for key, value in data.items():
        if key in ['_id', '_type', '_rev', '_createdAt', '_updatedAt']:
            continue

        django_field = bidirectional_field_mapper.get_django_field_name(key, 'payments')
        converted_data[django_field] = value

    return super().to_internal_value(converted_data)

class PaymentMethodSerializer(serializers.ModelSerializer):
    processor_name = serializers.CharField(source='processor.name', read_only=True, required=False)
    payments_count = serializers.SerializerMethodField()
    available_stores_count = serializers.SerializerMethodField()
    available_stores = serializers.SerializerMethodField()

    class Meta:
        model = PaymentMethod
        fields = [
            'id', 'sanity_id', 'name', 'method_type', 'processor', 'processor_name',
            'is_active', 'is_online_available', 'is_pos_available',
            'minimum_amount', 'maximum_amount', 'configuration', 'display_order',
            'icon_url', 'description', 'payments_count', 'available_stores_count',
            'available_stores', 'created_at', 'updated_at'
        ]
        read_only_fields = [
            'id', 'created_at', 'updated_at', 'processor_name',
            'payments_count', 'available_stores_count', 'available_stores'
        ]

processor_name = serializers.CharField(source='processor.name', read_only=True, required=False)

def get_payments_count(self, obj):
    return obj.payments.count()

def get_available_stores_count(self, obj):
    return obj.available_at_stores.count()

def get_available_stores(self, obj):
    """Return available stores with reference format matching Sanity."""
    stores = []
    for store_association in obj.available_at_stores.all():
        store = store_association.store
        stores.append({
            "_key": f"store_{store.sanity_id}",
            "_ref": store.sanity_id,
            "_type": "reference",
            "store_id": store.id,
            "store_name": store.name,
            "is_active": store.is_active
        })
    return stores

{
  "available_stores": [
    {
      "_key": "store_store-columbus-001",
      "_ref": "store-columbus-001",
      "_type": "reference",
      "store_id": "uuid-here",
      "store_name": "Columbus Main Street",
      "is_active": true
    }
  ]
}

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "sanity_id": "payment-method-credit-card",
  "name": "Visa/Mastercard",
  "method_type": "credit_card",
  "processor": "processor-uuid",
  "processor_name": "Stripe Production",
  "is_active": true,
  "is_online_available": true,
  "is_pos_available": true,
  "minimum_amount": "1.00",
  "maximum_amount": null,
  "configuration": {
    "accepted_brands": ["visa", "mastercard", "amex"],
    "requires_cvv": true
  },
  "display_order": 1,
  "icon_url": "https://cdn.example.com/icons/credit-card.png",
  "description": "All major credit cards",
  "payments_count": 1247,
  "available_stores_count": 5,
  "available_stores": [
    {
      "_key": "store_store-001",
      "_ref": "store-001",
      "_type": "reference",
      "store_id": "uuid",
      "store_name": "Main Street Store",
      "is_active": true
    }
  ],
  "created_at": "2025-01-15T10:30:00Z",
  "updated_at": "2025-01-15T10:30:00Z"
}

def to_internal_value(self, data):
    """Handle nested Sanity webhook data with field name conversion."""
    from ..integrations.sync.field_mappings import bidirectional_field_mapper

    # Convert camelCase to snake_case for payments domain
    converted_data = {}
    for key, value in data.items():
        if key in ['_id', '_type', '_rev', '_createdAt', '_updatedAt']:
            continue

        django_field = bidirectional_field_mapper.get_django_field_name(key, 'payments')
        converted_data[django_field] = value

    # Handle processor reference
    processor_ref = converted_data.get('processor')
    if isinstance(processor_ref, dict) and '_ref' in processor_ref:
        PaymentProcessor = apps.get_model('payments', 'PaymentProcessor')
        processor_instance = PaymentProcessor.objects.filter(sanity_id=processor_ref['_ref']).first()
        converted_data['processor'] = processor_instance.pk if processor_instance else None

    return super().to_internal_value(converted_data)

{
  "processor": {
    "_ref": "processor-stripe-prod",
    "_type": "reference"
  }
}

{
  "processor": UUID("processor-django-pk")  # Django foreign key
}

def create(self, validated_data):
    """Create payment method and handle store availability."""
    webhook_data = self.context.get('request_data', {})

    # Create the payment method instance
    payment_method = PaymentMethod.objects.create(**validated_data)

    # Process available stores
    self._process_available_stores(payment_method, webhook_data.get('availableAtStores', []))

    return payment_method

def update(self, instance, validated_data):
    """Update payment method and handle store availability."""
    webhook_data = self.context.get('request_data', {})

    # Update the payment method instance
    payment_method = super().update(instance, validated_data)

    # Process available stores
    self._process_available_stores(payment_method, webhook_data.get('availableAtStores', []))

    return payment_method

def _process_available_stores(self, payment_method, stores_data):
    """Process available stores for payment method."""
    if not isinstance(stores_data, list):
        return

    PaymentMethodStore = apps.get_model('payments', 'PaymentMethodStore')
    Store = apps.get_model('stores', 'Store')

    # Clear existing store associations
    payment_method.available_at_stores.all().delete()

    # Create new associations
    for store_ref in stores_data:
        if isinstance(store_ref, dict) and '_ref' in store_ref:
            store_instance = Store.objects.filter(sanity_id=store_ref['_ref']).first()
            if store_instance:
                PaymentMethodStore.objects.create(
                    payment_method=payment_method,
                    store=store_instance
                )

{
  "availableAtStores": [
    {
      "_key": "key1",
      "_ref": "store-001",
      "_type": "reference"
    },
    {
      "_key": "key2",
      "_ref": "store-002",
      "_type": "reference"
    }
  ]
}

class TransactionPaymentSerializer(serializers.ModelSerializer):
    transaction_id = serializers.CharField(source='transaction.transactionId', read_only=True, required=False)
    payment_method_name = serializers.CharField(source='payment_method.name', read_only=True)
    payment_method_type = serializers.CharField(source='payment_method.method_type', read_only=True)
    refunds = RefundSerializer(many=True, read_only=True)
    refunds_count = serializers.SerializerMethodField()
    total_refunded = serializers.SerializerMethodField()

    class Meta:
        model = TransactionPayment
        fields = [
            'id', 'sanity_id', 'transaction', 'transaction_id', 'payment_method',
            'payment_method_name', 'payment_method_type', 'amount', 'tender_amount',
            'change_due', 'status', 'processing_fee', 'net_amount',
            'processor_transaction_id', 'processor_response', 'risk_score',
            'cash_drawer_event', 'processed_at', 'metadata', 'refunds',
            'refunds_count', 'total_refunded', 'created_at', 'updated_at'
        ]
        read_only_fields = [
            'id', 'created_at', 'updated_at', 'transaction_id', 'payment_method_name',
            'payment_method_type', 'refunds', 'refunds_count', 'total_refunded',
            'net_amount', 'change_due'
        ]

transaction_id = serializers.CharField(source='transaction.transactionId', read_only=True, required=False)

payment_method_name = serializers.CharField(source='payment_method.name', read_only=True)

payment_method_type = serializers.CharField(source='payment_method.method_type', read_only=True)

refunds = RefundSerializer(many=True, read_only=True)

def get_refunds_count(self, obj):
    return obj.refunds.count()

def get_total_refunded(self, obj):
    return sum(refund.amount for refund in obj.refunds.filter(status='succeeded'))

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "sanity_id": "payment-abc123",
  "transaction": "transaction-uuid",
  "transaction_id": "TXN-20251117-ABC123",
  "payment_method": "payment-method-uuid",
  "payment_method_name": "Visa/Mastercard",
  "payment_method_type": "credit_card",
  "amount": "125.50",
  "tender_amount": null,
  "change_due": null,
  "status": "succeeded",
  "processing_fee": "3.64",
  "net_amount": "121.86",
  "processor_transaction_id": "ch_3NqXYZ...",
  "processor_response": {
    "id": "ch_3NqXYZ...",
    "status": "succeeded"
  },
  "risk_score": "12.50",
  "cash_drawer_event": null,
  "processed_at": "2025-11-17T14:30:00Z",
  "metadata": {
    "device_id": "POS-001"
  },
  "refunds": [
    {
      "id": "refund-uuid",
      "refund_id": "REF-20251118-DEF456",
      "amount": "25.00",
      "status": "succeeded"
    }
  ],
  "refunds_count": 1,
  "total_refunded": "25.00",
  "created_at": "2025-11-17T14:30:00Z",
  "updated_at": "2025-11-18T10:15:00Z"
}

def to_internal_value(self, data):
    """Handle nested Sanity webhook data with field name conversion."""
    from ..integrations.sync.field_mappings import bidirectional_field_mapper

    # Convert camelCase to snake_case for payments domain
    converted_data = {}
    for key, value in data.items():
        if key in ['_id', '_type', '_rev', '_createdAt', '_updatedAt']:
            continue

        django_field = bidirectional_field_mapper.get_django_field_name(key, 'payments')
        converted_data[django_field] = value

    # Handle transaction reference
    transaction_ref = converted_data.get('transaction')
    if isinstance(transaction_ref, dict) and '_ref' in transaction_ref:
        SalesTransaction = apps.get_model('transactions', 'SalesTransaction')
        transaction_instance = SalesTransaction.objects.filter(sanity_id=transaction_ref['_ref']).first()
        converted_data['transaction'] = transaction_instance.pk if transaction_instance else None

    # Handle payment method reference
    payment_method_ref = converted_data.get('payment_method')
    if isinstance(payment_method_ref, dict) and '_ref' in payment_method_ref:
        PaymentMethod = apps.get_model('payments', 'PaymentMethod')
        payment_method_instance = PaymentMethod.objects.filter(sanity_id=payment_method_ref['_ref']).first()
        converted_data['payment_method'] = payment_method_instance.pk if payment_method_instance else None

    # Handle cash drawer event reference
    cash_drawer_ref = converted_data.get('cash_drawer_event')
    if isinstance(cash_drawer_ref, dict) and '_ref' in cash_drawer_ref:
        CashDrawerEvent = apps.get_model('transactions', 'CashDrawerEvent')
        cash_drawer_instance = CashDrawerEvent.objects.filter(sanity_id=cash_drawer_ref['_ref']).first()
        converted_data['cash_drawer_event'] = cash_drawer_instance.pk if cash_drawer_instance else None

    # Handle processor response as object
    processor_response_ref = converted_data.get('processor_response')
    if isinstance(processor_response_ref, dict) and '_ref' in processor_response_ref:
        # If it's a reference to another document, store the reference ID
        converted_data['processor_response'] = {'reference_id': processor_response_ref['_ref']}
    elif isinstance(processor_response_ref, dict):
        # If it's inline processor response data, store it directly
        converted_data['processor_response'] = processor_response_ref

    return super().to_internal_value(converted_data)

def create(self, validated_data):
    """Create payment and handle nested refunds."""
    webhook_data = self.context.get('request_data', {})

    # Create the payment instance
    payment = Payment.objects.create(**validated_data)

    # Process refunds
    self._process_refunds(payment, webhook_data.get('refunds', []))

    return payment

def update(self, instance, validated_data):
    """Update payment and handle nested refunds."""
    webhook_data = self.context.get('request_data', {})

    # Update the payment instance
    payment = super().update(instance, validated_data)

    # Process refunds
    self._process_refunds(payment, webhook_data.get('refunds', []))

    return payment

def _process_refunds(self, payment, refunds_data):
    """Process refunds for payment."""
    if not isinstance(refunds_data, list):
        return

    Refund = apps.get_model('payments', 'Refund')

    # Process each refund reference
    for refund_ref in refunds_data:
        if isinstance(refund_ref, dict) and '_ref' in refund_ref:
            # Check if refund already exists with this sanity_id
            existing_refund = Refund.objects.filter(sanity_id=refund_ref['_ref']).first()
            if not existing_refund:
                # Create placeholder refund - actual refund data will come via separate webhook
                Refund.objects.create(
                    payment=payment,
                    amount=0,  # Will be updated when refund webhook comes
                    status='pending',
                    sanity_id=refund_ref['_ref']
                )

{
  "refunds": [
    {
      "_ref": "refund-abc123",
      "_type": "reference"
    }
  ]
}

Refund(
    payment=payment_instance,
    amount=Decimal('0.00'),  # Placeholder
    status='pending',
    sanity_id='refund-abc123'
)

class RefundSerializer(serializers.ModelSerializer):
    payment_amount = serializers.DecimalField(
        source='payment.amount',
        max_digits=10,
        decimal_places=2,
        read_only=True
    )
    transaction_id = serializers.CharField(source='payment.transaction.transactionId', read_only=True)

    class Meta:
        model = Refund
        fields = [
            'id', 'refund_id', 'sanity_id', 'payment', 'payment_amount', 'transaction_id',
            'amount', 'reason', 'status', 'processor_refund_id', 'processed_at',
            'sales_return', 'metadata', 'created_at', 'updated_at'
        ]
        read_only_fields = [
            'id', 'refund_id', 'processed_at', 'created_at', 'updated_at', 'payment_amount', 'transaction_id'
        ]

payment_amount = serializers.DecimalField(
    source='payment.amount',
    max_digits=10,
    decimal_places=2,
    read_only=True
)

transaction_id = serializers.CharField(source='payment.transaction.transactionId', read_only=True)

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "refund_id": "REF-20251118-ABC123",
  "sanity_id": "refund-abc123",
  "payment": "payment-uuid",
  "payment_amount": "125.50",
  "transaction_id": "transaction-uuid",
  "amount": "25.00",
  "reason": "Customer returned one item - defective",
  "status": "succeeded",
  "processor_refund_id": "re_3NqXYZ...",
  "processed_at": "2025-11-18T10:15:00Z",
  "sales_return": "return-uuid",
  "metadata": {
    "initiated_by": "MANAGER-12345"
  },
  "created_at": "2025-11-18T10:10:00Z",
  "updated_at": "2025-11-18T10:15:00Z"
}

class PaymentMethodSimpleSerializer(serializers.ModelSerializer):
    class Meta:
        model = PaymentMethod
        fields = ['id', 'name', 'method_type', 'is_active']

{
  "id": "uuid",
  "name": "Visa/Mastercard",
  "method_type": "credit_card",
  "is_active": true
}

class PaymentSimpleSerializer(serializers.ModelSerializer):
    payment_method_name = serializers.CharField(source='payment_method.name', read_only=True)

    class Meta:
        model = TransactionPayment
        fields = [
            'id', 'amount', 'status', 'payment_method', 'payment_method_name',
            'processing_fee', 'net_amount', 'created_at'
        ]
        read_only_fields = ['payment_method_name']

{
  "id": "uuid",
  "amount": "125.50",
  "status": "succeeded",
  "payment_method": "payment-method-uuid",
  "payment_method_name": "Visa/Mastercard",
  "processing_fee": "3.64",
  "net_amount": "121.86",
  "created_at": "2025-11-17T14:30:00Z"
}

class PaymentProcessorCreateSerializer(serializers.ModelSerializer):
    class Meta:
        model = PaymentProcessor
        fields = [
            'name', 'processor_type', 'is_active', 'is_test_mode',
            'configuration', 'processing_fee_percentage', 'processing_fee_fixed',
            'default_currency'
        ]

def validate_default_currency(self, value):
    """Validate currency code format."""
    if value and len(value) != 3:
        raise serializers.ValidationError('Currency code must be exactly 3 characters')
    return value.upper() if value else value

class PaymentMethodCreateSerializer(serializers.ModelSerializer):
    class Meta:
        model = PaymentMethod
        fields = [
            'name', 'method_type', 'processor', 'is_active',
            'is_online_available', 'is_pos_available', 'minimum_amount',
            'maximum_amount', 'configuration', 'display_order',
            'icon_url', 'description'
        ]

def validate(self, data):
    """Validate payment method data."""
    if data.get('maximum_amount') and data.get('minimum_amount'):
        if data['minimum_amount'] > data['maximum_amount']:
            raise serializers.ValidationError(
                'Minimum amount cannot be greater than maximum amount'
            )
    return data

class PaymentCreateSerializer(serializers.ModelSerializer):
    class Meta:
        model = TransactionPayment
        fields = [
            'transaction', 'payment_method', 'amount', 'status',
            'processing_fee', 'processor_transaction_id', 'processor_response',
            'risk_score', 'cash_drawer_event', 'processed_at', 'metadata'
        ]

def validate_amount(self, value):
    """Validate payment amount."""
    if value <= 0:
        raise serializers.ValidationError('Payment amount must be greater than 0')
    return value

def validate_risk_score(self, value):
    """Validate risk score range."""
    if value is not None and (value < 0 or value > 100):
        raise serializers.ValidationError('Risk score must be between 0 and 100')
    return value

class RefundCreateSerializer(serializers.ModelSerializer):
    class Meta:
        model = Refund
        fields = [
            'payment', 'amount', 'reason', 'status',
            'processor_refund_id', 'processed_at', 'metadata'
        ]

def validate(self, data):
    """Validate refund data."""
    if data['amount'] <= 0:
        raise serializers.ValidationError('Refund amount must be greater than 0')

    if data.get('payment'):
        if data['amount'] > data['payment'].amount:
            raise serializers.ValidationError(
                'Refund amount cannot exceed original payment amount'
            )

    return data

from ..integrations.sync.field_mappings import bidirectional_field_mapper

def to_internal_value(self, data):
    converted_data = {}
    for key, value in data.items():
        if key in ['_id', '_type', '_rev', '_createdAt', '_updatedAt']:
            continue  # Skip Sanity metadata

        django_field = bidirectional_field_mapper.get_django_field_name(key, 'payments')
        converted_data[django_field] = value

    return super().to_internal_value(converted_data)

{
  "processor": {
    "_ref": "processor-stripe-prod",
    "_type": "reference"
  }
}

processor_ref = converted_data.get('processor')
if isinstance(processor_ref, dict) and '_ref' in processor_ref:
    PaymentProcessor = apps.get_model('payments', 'PaymentProcessor')
    processor_instance = PaymentProcessor.objects.filter(sanity_id=processor_ref['_ref']).first()
    converted_data['processor'] = processor_instance.pk if processor_instance else None

{
  "availableAtStores": [
    {
      "_key": "key1",
      "_ref": "store-001",
      "_type": "reference"
    },
    {
      "_key": "key2",
      "_ref": "store-002",
      "_type": "reference"
    }
  ]
}

def _process_available_stores(self, payment_method, stores_data):
    # Clear existing associations
    payment_method.available_at_stores.all().delete()

    # Create new associations
    for store_ref in stores_data:
        if isinstance(store_ref, dict) and '_ref' in store_ref:
            store_instance = Store.objects.filter(sanity_id=store_ref['_ref']).first()
            if store_instance:
                PaymentMethodStore.objects.create(
                    payment_method=payment_method,
                    store=store_instance
                )