Skip to content

Recurring Payments System

This document explains how the recurring payments system works in the UBU Finance backend.

Overview

The UBU Finance backend includes a robust recurring payments system that automatically processes scheduled payments based on predefined rules. This system uses Celery, a distributed task queue, to handle background processing of recurring payments.

Architecture

The recurring payments system consists of the following components:

  1. Recurring Payment Model: Stores information about recurring payments, including frequency, amount, and next payment date.
  2. Celery Worker: Processes background tasks, including recurring payment processing.
  3. Celery Beat: Schedules periodic tasks to check for and process due recurring payments.
  4. Redis: Acts as a message broker and result backend for Celery tasks.
  5. Flower: Provides monitoring and management of Celery tasks.

How It Works

Scheduling Recurring Payments

When a user creates a recurring payment through the API, the system:

  1. Validates the payment details
  2. Creates a record in the RecurringPaymentModel table
  3. Sets the next_payment_date based on the specified frequency and start date
  4. Marks the recurring payment as active

Automatic Processing

The system automatically processes recurring payments through the following steps:

  1. Scheduled Task: A Celery Beat scheduler runs a task every hour to check for due recurring payments.
  2. Payment Detection: The task queries the database for active recurring payments where:
  3. next_payment_date is in the past or today
  4. end_date is in the future or not set
  5. is_active is true
  6. Payment Processing: For each due recurring payment:
  7. Creates a new payment record based on the recurring payment template
  8. Processes the payment (updates account balances, creates transaction records)
  9. Updates the next_payment_date based on the frequency
  10. Updates the last_payment_date to the current date
  11. Completion: If the next calculated payment date is beyond the end date, the recurring payment is deactivated.

Frequency Options

The system supports the following payment frequencies:

  • Daily: Payment occurs every day
  • Weekly: Payment occurs every 7 days
  • Biweekly: Payment occurs every 14 days
  • Monthly: Payment occurs on the same day each month
  • Quarterly: Payment occurs every 3 months
  • Annually: Payment occurs every year on the same date

Monitoring and Management

Flower Dashboard

The system includes a Flower dashboard for monitoring and managing Celery tasks:

  • URL: http://localhost:8090 (when running locally)
  • Features:
  • View task status and history
  • Monitor worker status
  • Inspect task details
  • Revoke or terminate tasks

Logging

All recurring payment processing activities are logged for auditing and troubleshooting:

  • Successful payments
  • Failed payments with error details
  • Schedule updates
  • Deactivation events

Configuration

The recurring payment system can be configured through environment variables:

  • REDIS_URL: URL for Redis connection (default: redis://redis:6379/0)
  • CELERY_TASK_SCHEDULE: How often to check for recurring payments (default: 3600 seconds / 1 hour)

Docker Integration

The recurring payment system is fully integrated with Docker Compose:

  • celery-worker: Processes background tasks
  • celery-beat: Schedules periodic tasks
  • flower: Provides monitoring interface
  • redis: Acts as message broker

Error Handling

The system includes robust error handling:

  1. Transaction Isolation: Each payment is processed in its own transaction
  2. Retry Mechanism: Failed tasks are automatically retried with exponential backoff
  3. Logging: All errors are logged for investigation
  4. Notification: System administrators can be notified of repeated failures

API Integration

The recurring payments system integrates with the existing API endpoints:

  • Create recurring payments via POST /api/payments/recurring
  • Update recurring payments via PUT /api/payments/recurring/{recurring_id}
  • Cancel recurring payments via DELETE /api/payments/recurring/{recurring_id}
  • View recurring payment history via GET /api/payments/recurring/{recurring_id}/history

Security Considerations

The recurring payment system adheres to the same security standards as the rest of the application:

  • All background tasks run with appropriate authentication context
  • Sensitive payment data is protected
  • Access to the Flower dashboard is restricted
  • All payment processing activities are logged for audit purposes