Payments Domain - Services Documentation

# CORRECT: Credentials from settings
api_key = settings.STRIPE_API_KEY

# FORBIDDEN: Credentials from database
# api_key = processor.configuration.get('api_key')  # NEVER DO THIS

from nextango.apps.payments.gateways.registry import get_gateway_for_processor

gateway = get_gateway_for_processor(processor)   # processor.processor_type = "stripe" | "custom" | "square" | "paypal"
result  = gateway.get_connection_token()

if not processor.is_active:
    return {
        'success': False,
        'message': 'Processor is not active'
    }

processor_handlers = {
    'stripe': PaymentProcessorService._test_stripe_connection,
    'square': PaymentProcessorService._test_square_connection,
    'paypal': PaymentProcessorService._test_paypal_connection,
    'custom': PaymentProcessorService._test_custom_connection,
}

handler = processor_handlers.get(processor.processor_type)
if handler:
    return handler(processor)

from nextango.apps.payments.services import PaymentProcessorService

processor = PaymentProcessor.objects.get(sanity_id='processor-stripe-prod')
result = PaymentProcessorService.test_processor_connection(processor)

if result['success']:
    print(f"{result['message']}")
else:
    print(f"{result['message']}")

{
    'success': True,
    'message': 'Stripe connection successful',
    'test_mode': False
}

{
    'success': False,
    'message': 'Stripe API key not configured in environment'
}

# Credentials from settings (environment variables)
api_key = settings.STRIPE_API_KEY

if not api_key:
    return {
        'success': False,
        'message': 'Stripe API key not configured in environment'
    }

return {
    'success': True,
    'message': 'Stripe connection test (mock - credentials loaded from settings)',
    'test_mode': processor.is_test_mode
}

import stripe

stripe.api_key = api_key

try:
    # Test API call - list payment methods or retrieve account
    account = stripe.Account.retrieve()
    return {
        'success': True,
        'message': f'Connected to Stripe account: {account.business_profile.name}',
        'test_mode': processor.is_test_mode,
        'account_id': account.id
    }
except stripe.error.AuthenticationError:
    return {
        'success': False,
        'message': 'Invalid Stripe API key'
    }
except stripe.error.StripeError as e:
    return {
        'success': False,
        'message': f'Stripe error: {str(e)}'
    }

access_token = settings.SQUARE_ACCESS_TOKEN

client_id = settings.PAYPAL_CLIENT_ID
client_secret = settings.PAYPAL_CLIENT_SECRET

api_key = settings.CUSTOM_PROCESSOR_API_KEY

# processor.configuration can still be used for non-sensitive config like webhook URLs

if not payment_method.processor:
    return Decimal('0.00')  # No processor = no fee

processor = payment_method.processor
fee = Decimal('0.00')

# Add percentage fee
if processor.processing_fee_percentage:
    fee += amount * (processor.processing_fee_percentage / Decimal('100'))

# Add fixed fee
if processor.processing_fee_fixed:
    fee += processor.processing_fee_fixed

return fee.quantize(Decimal('0.01'))  # Always 2 decimal places

processor.processing_fee_percentage = Decimal('2.90')
processor.processing_fee_fixed = Decimal('0.30')

# Payment of $100.00
fee = calculate_processing_fee(Decimal('100.00'), payment_method)
# fee = (100.00 * 0.029) + 0.30 = 2.90 + 0.30 = $3.20

with transaction.atomic():
    # All operations succeed or all fail

SaleTransaction = apps.get_model('transactions', 'SaleTransaction')
sale_transaction = SaleTransaction.objects.get(transactionId=transaction_id)

if sale_transaction.status in ['completed', 'voided', 'refunded']:
    return {
        'success': False,
        'error': f'Cannot apply payment to {sale_transaction.status} transaction',
        'transaction': {
            'transactionId': sale_transaction.transactionId,
            'status': sale_transaction.status
        }
    }

payment_method = PaymentMethod.objects.get(id=payment_method_id)

if tendered_amount < payment_method.minimum_amount:
    return {
        'success': False,
        'error': f'Amount below minimum of \${payment_method.minimum_amount}'
    }

remaining_balance = sale_transaction.payment_balance

# Payment amount is capped at remaining balance, but never negative
# If balance is negative (overpaid), payment_amount is 0
payment_amount = max(Decimal('0.00'), min(tendered_amount, remaining_balance))

change_due = None
if payment_method.method_type == 'cash' and tendered_amount > payment_amount:
    change_due = tendered_amount - payment_amount

clean_metadata = {}
if metadata:
    for key, value in metadata.items():
        if key == 'change_due':
            # Skip change_due from metadata - we calculate it ourselves
            continue
        clean_metadata[key] = value

# Only add change_due to metadata if there is actual change (positive value)
# Must be string for Sanity schema compatibility
if change_due and change_due > 0:
    clean_metadata['change_due'] = str(change_due.quantize(Decimal('0.01')))

payment = TransactionPayment.objects.create(
    transaction=sale_transaction,
    payment_method=payment_method,
    amount=payment_amount,
    tender_amount=tendered_amount if payment_method.method_type == 'cash' else None,
    change_due=change_due,
    processing_fee=processing_fee,
    status='succeeded',  # POS terminal already confirmed
    processed_at=timezone.now(),
    metadata=clean_metadata
)

if payment_method.method_type == 'cash':
    cash_drawer_event = PaymentService._create_cash_drawer_event(
        sale_transaction, payment_amount, metadata or {}
    )
    payment.cash_drawer_event = cash_drawer_event
    payment.save(update_fields=['cash_drawer_event'])

# Refresh from DB to get updated payment_balance
sale_transaction.refresh_from_db()

if sale_transaction.is_fully_paid:
    sale_transaction.status = 'completed'
    sale_transaction.completedAt = timezone.now()
    sale_transaction.save(update_fields=['status', 'completedAt'])
    logger.info(f"Transaction {transaction_id} marked as completed - fully paid")
else:
    logger.info(
        f"Transaction {transaction_id} remains pending - "
        f"balance \${sale_transaction.payment_balance}"
    )

return {
    'success': True,
    'payment': {
        'id': payment.id,
        'amount': str(payment.amount),
        'status': payment.status,
        'method': payment_method.name,
        'method_type': payment_method.method_type
    },
    'transaction': {
        'transactionId': sale_transaction.transactionId,
        'status': sale_transaction.status,
        'totalAmount': str(sale_transaction.totalAmount),
        'payment_balance': str(sale_transaction.payment_balance),
        'is_fully_paid': sale_transaction.is_fully_paid,
        'requires_additional_payment': not sale_transaction.is_fully_paid
    }
}

except SaleTransaction.DoesNotExist:
    return {
        'success': False,
        'error': f'Transaction {transaction_id} not found'
    }

except PaymentMethod.DoesNotExist:
    return {
        'success': False,
        'error': 'Payment method not found'
    }

except Exception as e:
    logger.error(f"Error applying payment to transaction {transaction_id}: {e}")
    import traceback
    logger.error(traceback.format_exc())
    return {
        'success': False,
        'error': str(e)
    }

from nextango.apps.payments.services import PaymentService
from decimal import Decimal

result = PaymentService.apply_payment_to_transaction(
    transaction_id="TXN-20251117-ABC123",
    payment_method_id="cash-payment-method-uuid",
    tendered_amount=Decimal("120.00"),
    metadata={
        "register_id": "POS-01",
        "employee_id": "emp-uuid"
    }
)

if result['success']:
    print(f"Payment applied: \${result['payment']['amount']}")
    print(f"Transaction status: {result['transaction']['status']}")
    if result['transaction']['requires_additional_payment']:
        print(f"Balance remaining: \${result['transaction']['payment_balance']}")

# Transaction total: $100.00

# First payment - Cash $60
result1 = PaymentService.apply_payment_to_transaction(
    transaction_id="TXN-20251117-ABC123",
    payment_method_id="cash-uuid",
    tendered_amount=Decimal("60.00")
)
# result1['transaction']['payment_balance'] = "40.00"
# result1['transaction']['status'] = "pending"

# Second payment - Credit card $40
result2 = PaymentService.apply_payment_to_transaction(
    transaction_id="TXN-20251117-ABC123",
    payment_method_id="credit-card-uuid",
    tendered_amount=Decimal("40.00")
)
# result2['transaction']['payment_balance'] = "0.00"
# result2['transaction']['status'] = "completed"

from django.conf import settings
if getattr(settings, 'DEBUG', False) and not payment_method.processor:
    payment.status = 'succeeded'
    payment.processor_response = {
        'message': 'Dev mode auto-success',
        'transaction_id': f'dev_mock_{payment.id}',
        'processor': 'dev_mode'
    }
    payment.processor_transaction_id = f'dev_mock_{payment.id}'
    payment.save()
    return True, payment, 'Payment processed successfully (dev mode)'

if payment_method.processor and payment_method.processor.processor_type == 'stripe':
    payment.status = 'pending'  # Wait for webhook confirmation
    logger.info(f"Stripe PaymentIntent created - waiting for webhook confirmation: {processor_response.get('transaction_id')}")
else:
    payment.status = 'succeeded'

success, payment, message = PaymentService.process_payment(
    transaction_id=transaction_uuid,
    payment_method_id=payment_method_uuid,
    amount=Decimal("100.00"),
    metadata={'device_id': 'POS-01'}
)

if success:
    print(f"{message}")
    print(f"Payment ID: {payment.id}, Status: {payment.status}")
else:
    print(f"{message}")

# Resolve POS payment type to PaymentMethod
payment_method = PaymentMethodService.resolve_pos_payment_type(payment_type, store_id)

if not payment_method:
    # Try to create default methods in dev mode
    default_methods = PaymentMethodService.get_or_create_default_payment_methods(store_id)
    payment_method = default_methods.get(payment_type.lower())

    if not payment_method:
        return False, None, f"Payment method '{payment_type}' not available"

# Legacy POS sends "cash" string
success, payment, message = PaymentService.process_payment_with_pos_type(
    transaction_id=transaction_uuid,
    payment_type="cash",  # String instead of UUID
    amount=Decimal("50.00"),
    store_id=store_uuid
)

processor_handlers = {
    'stripe': PaymentService._process_stripe_payment,
    'square': PaymentService._process_square_payment,
    'paypal': PaymentService._process_paypal_payment,
    'custom': PaymentService._process_custom_payment,
}

handler = processor_handlers.get(processor.processor_type)
if handler:
    return handler(payment, processor)

return False, {'message': f'No handler for processor type: {processor.processor_type}'}

import uuid
from django.utils import timezone

event_id = f"CASH-{timezone.now().strftime('%Y%m%d')}-{uuid.uuid4().hex[:8].upper()}"
# Example: "CASH-20251117-A3F8B2C1"

CashDrawerEvent = apps.get_model('transactions', 'CashDrawerEvent')

return CashDrawerEvent.objects.create(
    eventId=event_id,
    eventType='sale',
    store=sales_transaction.store,
    employee=sales_transaction.employee,
    registerId=metadata.get('register_id', 'POS-01'),
    amount=amount,
    transaction=sales_transaction,
    cashBreakdown=metadata.get('cash_breakdown', {}),
    drawerTotalBefore=metadata.get('drawer_total_before', Decimal('0.00')),
    drawerTotalAfter=metadata.get('drawer_total_after', Decimal('0.00')),
    notes=metadata.get('notes', ''),
    shiftId=metadata.get('shift_id', ''),
)

# Credentials from settings, NOT database
api_key = settings.STRIPE_API_KEY

if not api_key:
    return False, {
        'message': 'Stripe API key not configured in environment',
        'processor': 'stripe'
    }

import stripe

stripe.api_key = api_key

# Create PaymentIntent
intent = stripe.PaymentIntent.create(
    amount=int(payment.amount * 100),  # Stripe uses cents
    currency=processor.default_currency.lower() if processor.default_currency else 'usd',
    metadata={
        'payment_id': str(payment.id),
        'transaction_id': str(payment.transaction.id) if payment.transaction else None,
        'customer_id': str(payment.transaction.customer.id) if payment.transaction and payment.transaction.customer else None,
    },
    automatic_payment_methods={'enabled': True},
)

logger.info(f"Created Stripe PaymentIntent: {intent.id} for payment {payment.id}")

return True, {
    'transaction_id': intent.id,  # This gets saved to processor_transaction_id
    'message': 'PaymentIntent created successfully',
    'processor': 'stripe',
    'client_secret': intent.client_secret,  # For frontend confirmation
    'status': intent.status,
}

except stripe._error.StripeError as e:
    logger.error(f"Stripe error creating PaymentIntent: {e}")
    return False, {
        'message': f'Stripe error: {str(e)}',
        'processor': 'stripe',
        'error_type': type(e).__name__,
    }

except Exception as e:
    logger.error(f"Unexpected error creating Stripe PaymentIntent: {e}")
    return False, {
        'message': f'Unexpected error: {str(e)}',
        'processor': 'stripe'
    }

access_token = settings.SQUARE_ACCESS_TOKEN
location_id = settings.SQUARE_LOCATION_ID

from square.client import Client

client = Client(
    access_token=access_token,
    environment='production' if not processor.is_test_mode else 'sandbox'
)

result = client.payments.create_payment(
    body={
        "source_id": "...",  # Card token from Square SDK
        "idempotency_key": str(payment.id),
        "amount_money": {
            "amount": int(payment.amount * 100),  # Square uses cents
            "currency": processor.default_currency or "USD"
        },
        "location_id": location_id
    }
)

return True, {
    'transaction_id': result.body['payment']['id'],
    'message': 'Square payment processed',
    'processor': 'square'
}

client_id = settings.PAYPAL_CLIENT_ID
client_secret = settings.PAYPAL_CLIENT_SECRET

api_key = settings.CUSTOM_PROCESSOR_API_KEY
api_secret = settings.CUSTOM_PROCESSOR_API_SECRET

# processor.configuration can still be used for non-sensitive config like webhook URLs

success, refund, message = RefundService.process_refund(...)

with transaction.atomic():
    # All operations succeed or all fail

if amount <= 0:
    return False, None, 'Refund amount must be greater than 0'

if amount > payment.amount:
    return False, None, 'Refund amount cannot exceed payment amount'

# Check existing refunds
total_refunded = payment.refunds.filter(status='succeeded').aggregate(
    total=models.Sum('amount')
)['total'] or Decimal('0.00')

if (total_refunded + amount) > payment.amount:
    return False, None, 'Total refunds cannot exceed payment amount'

refund = Refund.objects.create(
    payment=payment,
    amount=amount,
    reason=reason,
    status='pending',
    metadata=metadata or {},
    sales_return=sales_return  # Link to return if provided
)

logger.info(f"Created refund {refund.refund_id} for payment {payment.id}, amount \${amount}")

# Process with payment processor
success, processor_response = RefundService._process_with_processor(
    refund, payment.payment_method.processor
)

if success:
    refund.status = 'succeeded'
    refund.processor_refund_id = processor_response.get('refund_id')
else:
    refund.status = 'failed'

refund.save()

from nextango.apps.payments.services import RefundService
from decimal import Decimal

success, refund, message = RefundService.process_refund(
    payment_id=payment_uuid,
    amount=Decimal("100.00"),  # Full payment amount
    reason="Customer requested full refund"
)

if success:
    print(f"Refund {refund.refund_id}: {message}")
else:
    print(f"{message}")

# Original payment: $100.00
# Refund only $25.00

success, refund, message = RefundService.process_refund(
    payment_id=payment_uuid,
    amount=Decimal("25.00"),  # Partial amount
    reason="Partial return - 1 item returned"
)

# Payment still has $75.00 that can be refunded in future

# When processing return, link refund to return transaction
Return = apps.get_model('transactions', 'Return')
return_instance = Return.objects.get(returnId='RET-20251117-ABC123')

success, refund, message = RefundService.process_refund(
    payment_id=payment_uuid,
    amount=Decimal("50.00"),
    reason="Return processed",
    sales_return=return_instance  # Link refund to return
)

from django.conf import settings
if getattr(settings, 'DEBUG', False) and not processor:
    return True, {
        'refund_id': f'dev_mock_refund_{refund.id}',
        'message': 'Refund processed successfully (dev mode)',
        'processor': 'dev_mode'
    }

processor_handlers = {
    'stripe': RefundService._process_stripe_refund,
    'square': RefundService._process_square_refund,
    'paypal': RefundService._process_paypal_refund,
    'custom': RefundService._process_custom_refund,
}

handler = processor_handlers.get(processor.processor_type)
if handler:
    return handler(refund, processor)

import stripe
from django.conf import settings

stripe.api_key = settings.STRIPE_API_KEY

# Get original payment's processor_transaction_id (PaymentIntent ID)
payment_intent_id = refund.payment.processor_transaction_id

try:
    # Create Stripe Refund
    stripe_refund = stripe.Refund.create(
        payment_intent=payment_intent_id,
        amount=int(refund.amount * 100),  # Stripe uses cents
        metadata={
            'refund_id': str(refund.id),
            'reason': refund.reason
        }
    )

    return True, {
        'refund_id': stripe_refund.id,
        'message': 'Stripe refund processed',
        'processor': 'stripe',
        'status': stripe_refund.status
    }

except stripe.error.StripeError as e:
    return False, {
        'message': f'Stripe error: {str(e)}',
        'processor': 'stripe'
    }

pos_type_mapping = {
    'cash': 'cash',
    'card': 'card',
    'check': 'check',
    'credit': 'card',  # Alias for card
    'debit': 'card',   # Alias for card
}

method_type = pos_type_mapping.get(payment_type.lower())

if not method_type:
    logger.warning(f"Unknown POS payment type: {payment_type}")
    return None

query = PaymentMethod.objects.filter(
    method_type=method_type,
    is_active=True
)

if store_id:
    store_specific = query.filter(available_at_stores__store_id=store_id).first()
    if store_specific:
        return store_specific

return query.first()

# POS sends "cash" string
payment_method = PaymentMethodService.resolve_pos_payment_type(
    payment_type="cash",
    store_id=store_uuid
)

if payment_method:
    print(f"Resolved to: {payment_method.name}")
else:
    print("Payment method not available")

default_methods = [
    {
        'pos_type': 'cash',
        'method_type': 'cash',
        'name': 'Cash',
        'display_name': 'Cash Payment'
    },
    {
        'pos_type': 'card',
        'method_type': 'card',
        'name': 'Card',
        'display_name': 'Card Payment'
    },
    {
        'pos_type': 'check',
        'method_type': 'check',
        'name': 'Check',
        'display_name': 'Check Payment'
    }
]

for method_config in default_methods:
    # Try to find existing method
    payment_method = PaymentMethodService.resolve_pos_payment_type(
        method_config['pos_type'], store_id
    )

    # Create if doesn't exist and we're in dev mode
    if not payment_method and getattr(settings, 'DEBUG', False):
        payment_method = PaymentMethod.objects.create(
            name=method_config['name'],
            display_name=method_config['display_name'],
            method_type=method_config['method_type'],
            is_active=True,
            minimum_amount=Decimal('0.01'),
            # No processor for dev mode - will auto-succeed
            processor=None
        )
        logger.info(f"Created default payment method: {payment_method.name}")

    if payment_method:
        methods[method_config['pos_type']] = payment_method

if not payment_method and getattr(settings, 'DEBUG', False):

from nextango.apps.payments.services import PaymentMethodService

# Dev mode - auto-create if missing
methods = PaymentMethodService.get_or_create_default_payment_methods()

cash_method = methods.get('cash')
card_method = methods.get('card')
check_method = methods.get('check')

try:
    # Try lookup by database id first, then by sanity_id
    try:
        store = Store.objects.get(id=store_id)
    except (Store.DoesNotExist, ValueError):
        # If not found by id or invalid UUID, try sanity_id
        store = Store.objects.get(sanity_id=store_id)
except Store.DoesNotExist:
    logger.warning(f"Store not found with id or sanity_id: {store_id}")
    return []

# Get methods specifically available at this store OR methods available everywhere
payment_methods = PaymentMethod.objects.filter(
    models.Q(available_at_stores__store=store) |
    models.Q(available_at_stores__isnull=True),  # Empty = available everywhere
    is_active=True
).distinct()

available_methods = PaymentMethodService.get_available_methods_for_store(
    store_id="store-downtown-001"  # Sanity ID
)

for method in available_methods:
    print(f"- {method.name} ({method.method_type})")

try:
    payment_method = PaymentMethod.objects.get(id=payment_method_id)
except PaymentMethod.DoesNotExist:
    return False, 'Payment method not found'

if not payment_method.is_active:
    return False, 'Payment method is not active'

if amount < payment_method.minimum_amount:
    return False, f'Amount below minimum of \${payment_method.minimum_amount}'

if payment_method.maximum_amount and amount > payment_method.maximum_amount:
    return False, f'Amount exceeds maximum of \${payment_method.maximum_amount}'

if store_id:
    available_methods = PaymentMethodService.get_available_methods_for_store(store_id)
    if payment_method not in available_methods:
        return False, 'Payment method not available at this store'

return True, 'Payment method is valid'

is_valid, message = PaymentMethodService.validate_method_for_transaction(
    payment_method_id=payment_method_uuid,
    amount=Decimal("50.00"),
    store_id=store_uuid
)

if is_valid:
    # Proceed with payment
    pass
else:
    # Show error to user
    print(f"{message}")

# NEVER store credentials in database
processor.configuration = {
    'api_key': 'sk_live_...',  # SECURITY VIOLATION
    'webhook_secret': 'whsec_...'  # SECURITY VIOLATION
}

# Store in environment variables
# .env file (not committed to git)
STRIPE_API_KEY=sk_live_...
STRIPE_WEBHOOK_SECRET=whsec_...

# Django settings
from django.conf import settings
api_key = settings.STRIPE_API_KEY  # SECURE

# Database stores non-sensitive config
processor.configuration = {
    'webhook_url': 'https://api.example.com/webhooks/stripe',
    'timeout_seconds': 30,
    'display_name': 'Stripe Production'
}

payment = TransactionPayment.objects.create(
    # ...
    idempotency_key=metadata.get('idempotency_key') if metadata else None
)

stripe.PaymentIntent.create(
    amount=10000,
    currency='usd',
    idempotency_key=str(payment.id)  # Same key = same payment
)

if getattr(settings, 'DEBUG', False) and not payment_method.processor:
    payment.status = 'succeeded'
    payment.processor_response = {
        'message': 'Dev mode auto-success',
        'transaction_id': f'dev_mock_{payment.id}',
        'processor': 'dev_mode'
    }
    payment.save()
    return True, payment, 'Payment processed successfully (dev mode)'

intent = stripe.PaymentIntent.create(
    amount=int(payment.amount * 100),
    currency='usd',
    # ...
)

# Payment status = 'pending'
payment.status = 'pending'
payment.processor_transaction_id = intent.id
payment.save()

# Stripe sends webhook: payment_intent.succeeded
# Webhook handler updates payment:
payment = TransactionPayment.objects.get(processor_transaction_id=intent.id)
payment.status = 'succeeded'
payment.save()

if payment_method.method_type == 'cash':
    cash_drawer_event = PaymentService._create_cash_drawer_event(
        sale_transaction, payment_amount, metadata or {}
    )
    payment.cash_drawer_event = cash_drawer_event
    payment.save()

# Payment 1: Cash $60
PaymentService.apply_payment_to_transaction(
    transaction_id="TXN-...",
    payment_method_id=cash_uuid,
    tendered_amount=Decimal("60.00")
)
# Transaction balance: $40.00, status: 'pending'

# Payment 2: Credit card $40
PaymentService.apply_payment_to_transaction(
    transaction_id="TXN-...",
    payment_method_id=card_uuid,
    tendered_amount=Decimal("40.00")
)
# Transaction balance: $0.00, status: 'completed'

with transaction.atomic():
    # Multiple database operations
    # Either ALL succeed or ALL rollback

if getattr(settings, 'DEBUG', False) and not payment_method.processor:
    # Auto-succeed without real processor
    payment.status = 'succeeded'

if not api_key:
    return False, {
        'message': 'Stripe API key not configured in environment',
        'processor': 'stripe'
    }

logger.info(f"Created Stripe PaymentIntent: {intent.id} for payment {payment.id}")

logger.error(f"Error processing payment: {e}")
import traceback
logger.error(traceback.format_exc())