Building Beeing: A Modern Laravel Beekeeping Management System - Part 3: Stripe & Elorus Integration

In this third installment, we'll explore how Beeing handles subscription payments through Stripe and automatically generates Greek tax-compliant invoices using the Elorus API - a critical requirement for European businesses.

The Payment & Compliance Challenge

Building a subscription-based SaaS application for European markets presents unique challenges:

1. Payment Processing: Reliable, secure subscription management
2. Tax Compliance: EU VAT regulations and local requirements
3. Invoice Generation: Automatic, legally compliant documentation
4. User Experience: Seamless payment flow without compliance friction

For Greek businesses, proper invoice generation isn't optional - it's legally required. This led us to integrate with Elorus, a local invoicing service that ensures tax compliance.

Subscription Architecture with Laravel Cashier

We chose Laravel Cashier for its mature Stripe integration and Laravel ecosystem compatibility. The architecture follows a webhook-driven approach:

1. Subscription Events: Stripe sends webhooks for payment events
2. Payment Recording: We capture payment details for invoice generation
3. Invoice Creation: Async job creates Elorus invoice
4. Compliance Tracking: Full audit trail for tax purposes

Payment Data Structure

Our payment tracking extends beyond Cashier's default tables. We created a dedicated payments table that captures:

• Payment gateway details (Stripe IDs, amounts, currency)
• User associations for invoice generation
• Invoice status tracking
• Metadata for audit trails

This separation allows us to track payments independently of subscription states, which is crucial for accurate invoice generation.

Webhook Processing Strategy

Stripe webhooks are the backbone of our payment processing. We implemented a robust listener that:

• Validates webhook signatures for security
• Handles multiple event types gracefully
• Creates payment records immediately
• Queues invoice generation with appropriate delays

The delay in invoice generation (typically 2 minutes) ensures Stripe's data consistency across their systems before we attempt to access related objects.

Elorus Integration for Tax Compliance

Elorus provides the legal framework for Greek tax compliance. Our integration handles:

Invoice Service Architecture

We built a dedicated ElorusInvoiceService that encapsulates:

• API authentication and request formatting
• VAT calculations (24% for Greek services)
• Error handling and retry logic
• Response processing and storage

Document Management

Every generated invoice creates a Document record that tracks:

• Elorus document ID and status
• PDF URLs for customer access
• Tax compliance metadata
• Payment associations

This creates a complete audit trail from payment to invoice, essential for tax reporting.

Async Processing Benefits

Invoice generation happens asynchronously via Laravel queues, providing:

• Reliability: Failed jobs can be retried automatically
• Performance: Webhook responses aren't blocked by external API calls
• Scalability: High payment volumes don't overwhelm the system
• Error Handling: Failures can be monitored and addressed separately

Error Handling & Resilience

Payment processing requires exceptional reliability. Our error handling includes:

Webhook Validation

• Stripe signature verification prevents unauthorized requests
• Duplicate event detection avoids double-processing
• Structured logging for debugging and monitoring

API Failure Recovery

• Retry logic for temporary Elorus API failures
• Dead letter queues for persistent failures
• Admin notifications for manual intervention needs

Data Consistency

• Database transactions ensure payment/document consistency
• Idempotency keys prevent duplicate invoice creation
• Reconciliation commands identify and fix discrepancies

Admin Management Interface

The admin interface provides comprehensive oversight:

Payment Monitoring

• Real-time payment status tracking
• Failed payment identification and retry mechanisms
• User-specific payment history and troubleshooting

Invoice Management

• Bulk invoice generation for edge cases
• Document status monitoring and updates
• Direct integration with Elorus for manual operations

Compliance Reporting

• Tax period summaries for accounting
• Export capabilities for external accounting systems
• Audit trails for regulatory compliance

Configuration & Security

The integration requires careful configuration management:

Environment Variables

All sensitive data (API keys, organization IDs) are managed through environment variables with appropriate defaults for development environments.

Service Binding

Laravel's service container manages the ElorusInvoiceService with proper dependency injection, making testing and configuration management straightforward.

Security Considerations

• API keys are never logged or exposed in errors
• Webhook endpoints include CSRF protection
• Payment data includes appropriate access controls

Monitoring & Analytics

We implemented comprehensive monitoring for payment operations:

Health Checks

• Regular API connectivity tests
• Invoice generation success rate monitoring
• Payment processing latency tracking

Business Intelligence

• Revenue tracking and forecasting
• Payment method analysis
• Geographic distribution insights

Alert Systems

• Failed payment notifications
• Invoice generation failures
• Unusual activity patterns

Real-World Operational Insights

After deployment, several patterns emerged:

Payment Behavior

• Most users prefer card payments over alternative methods
• Failed payments often require customer communication
• Subscription updates need careful invoice handling

Compliance Learning

• Greek tax requirements are more complex than initially anticipated
• Different customer types (individual vs. business) need different invoice formats
• Audit trails prove invaluable during tax inspections

Performance Optimization

• Webhook processing needs to be extremely fast
• Invoice generation can be delayed without user impact
• Caching invoice data improves admin interface performance

Lessons Learned

1. Compliance First: Tax requirements should drive technical architecture, not be an afterthought
2. Async Everything: Payment processing should never block user operations
3. Audit Trails: Comprehensive logging saves significant time during troubleshooting
4. Error Recovery: Payment systems need exceptional error handling and recovery mechanisms
5. Testing Strategy: Payment flows require extensive integration testing with real Stripe test data

Fallback Mechanisms

We implemented several fallback systems:

Manual Processing

• Admin interface for manual invoice creation
• Payment reconciliation tools for edge cases
• Direct Elorus integration for emergency situations

Data Recovery

• Payment event replay capabilities
• Invoice regeneration from payment records
• Backup invoice storage for compliance

This robust payment and compliance system ensures Beeing can operate legally across European markets while providing excellent user experience. The separation of concerns between payment processing and invoice generation provides flexibility for future expansion to other markets.

In our next post, we'll explore the advanced activity management system that provides bulk operations for managing multiple hives efficiently.

This is part 3 of our series on building Beeing. The payment and invoice integration demonstrates how to handle complex business requirements while maintaining compliance with regional regulations.