Repayment Data Structure

📊 Repayment Flow Entity Relationship Diagram (ERD)

The diagram below shows the complete payment flow using Crow's Foot notation:

Payment entities and their processing flow
Allocation mechanisms between payments and installments
Payment methods (Boleto, QR Code, PIX, etc.)
Transaction monitoring and status tracking

erDiagram
    Facility {
        int id PK
        string name
        boolean active
        string collateral_type
        decimal interest_rate
        datetime created_at
    }

    Loan {
        int id PK
        uuid uuid UK
        int facility_id FK
        int borrower_id FK
        string status
        decimal gross_amount
        decimal net_amount
        decimal interest_rate
        date expected_disbursement_date
        date first_installment_date
        datetime date_created
    }

    RepaymentSchedule {
        int id PK
        int loan_id FK
        date creation_date
        boolean is_active
        int version
        datetime created_at
    }

    RepaymentInstallment {
        int id PK
        int repayment_schedule_id FK
        int collateral_id FK
        decimal fixed_amount
        decimal fixed_principal
        decimal interest_at_due_date
        date due_date
        int installment_number
        json legacy_item
        datetime created_at
    }

    FacilityRepay {
        int id PK
        int facility_id FK
        datetime payment_received_at
        decimal gross_amount
        decimal net_amount
        int repayment_bank_account_id FK
        text error_message
        datetime date_created
    }

    FacilityRepayTransaction {
        int id PK
        int facility_repay_id FK
        uuid quote_identifier
        uuid payment_identifier
        int use_account_id
        datetime last_updated
        string approve_transaction_hash
        string repayment_transaction_hash
        string lender_claim_transaction_hash
        string stake_transaction_hash
        string status
        text error_message
    }

    PaymentAllocation {
        int id PK
        int facility_repay_id FK
        int repayment_installment_id FK
        decimal amount_allocated
        datetime provider_received_payment_at
        string payment_method
    }

    RepaymentInstallmentDiscount {
        int id PK
        int repayment_installment_id FK
        int applied_by_id FK
        decimal amount
        datetime applied_date
        text reason
        datetime date_created
    }

    Boleto {
        int id PK
        int repayment_installment_id FK
        string stark_id UK
        int amount
        string bar_code
        file file
        string city
        datetime created
        text descriptions
        text discounts
        string district
        datetime due
        float fee
        float fine
        float interest
        string line
        string name
        int our_number UK
        text transaction_ids
        int overdue_limit
        string receiver_name
        string receiver_tax_id
        string state_code
        string status
        string street_line_1
        string street_line_2
        text tags
        string tax_id
        string zip_code
        string workspace_id
        datetime paid_at
        datetime last_updated_at
    }

    PaymentQrCode {
        int id PK
        int created_by_id FK
        float amount
        string client_external_id
        text qr_code_string
        text qr_code_base64
        string qr_code_reference_id
        string qr_code_external_id
        datetime expiration_date
        boolean paid
        int facility_repay_created_id FK
        datetime date_created
    }

    RepaymentInstallmentToPaymentQRCode {
        int id PK
        int repayment_installment_id FK
        int payment_qr_code_id FK
        float amount
    }

    %% Core Repayment Flow
    Facility ||--o{ FacilityRepay : "receives_payments"
    Facility ||--o{ Loan : "contains"
    
    Loan ||--o{ RepaymentSchedule : "has_schedule"
    
    RepaymentSchedule ||--o{ RepaymentInstallment : "contains_installments"
    
    %% Payment Processing Flow
    FacilityRepay ||--o| FacilityRepayTransaction : "tracked_by"
    FacilityRepay ||--o{ PaymentAllocation : "allocated_via"
    
    PaymentAllocation }o--|| RepaymentInstallment : "allocated_to"
    
    %% Payment Methods
    RepaymentInstallment ||--o| Boleto : "can_be_paid_via"
    RepaymentInstallment ||--o{ RepaymentInstallmentToPaymentQRCode : "has_qr_codes"
    RepaymentInstallment ||--o{ RepaymentInstallmentDiscount : "has_discounts"
    
    %% QR Code Management
    PaymentQrCode ||--o{ RepaymentInstallmentToPaymentQRCode : "linked_to_installments"
    PaymentQrCode }o--o| FacilityRepay : "creates_facility_repay"

🏗️ Repayment Flow Entities

Core Payment Processing

FacilityRepay: Actual payments received by the facility from borrowers

FacilityRepayTransaction: Transaction monitoring and blockchain processing status
PaymentAllocation: Allocation of received payments to specific installments

Payment Schedule Management

RepaymentSchedule: Payment schedules for loans (versioned)
RepaymentInstallment: Individual installments within a schedule
RepaymentScheduleRequest: Requests for schedule modifications
RepaymentInstallmentDiscount: Discounts applied to installments

Payment Methods & Instruments

Boleto: Brazilian bank slips for payment processing
PaymentQrCode: QR codes for PIX and other instant payments
RepaymentInstallmentToPaymentQRCode: Many-to-many relationship for QR code assignments

🔄 Payment Flow Process

1. Payment Reception Flow

Borrower Payment → FacilityRepay → FacilityRepayTransaction → PaymentAllocation → RepaymentInstallment

2. Payment Method Generation

RepaymentInstallment → Boleto (1:1) OR QR Codes (1:N via junction table)

3. Payment Tracking

Boleto → BoletoLog → BoletoLogNotification
PaymentQrCode → Payment Detection → FacilityRepay Creation

4. Payment Allocation

FacilityRepay → PaymentAllocation → RepaymentInstallment(s)

🔗 Key Repayment Relationships

Facility → FacilityRepay → PaymentAllocation: Payment reception and allocation
RepaymentInstallment ↔ PaymentAllocation: Many-to-many allocation of payments
RepaymentInstallment → Boleto: One-to-one boleto generation
RepaymentInstallment ↔ PaymentQrCode: Many-to-many QR code generation
FacilityRepay ↔ FacilityRepayTransaction: Payment processing monitoring
Boleto → BoletoLog → BoletoLogNotification: Event tracking and notifications

📋 Payment States & Status

FacilityRepay Status

PENDING: Payment received but not processed
IN_PROGRESS: Payment being processed on blockchain
COMPLETED: Payment successfully processed
FAILED: Payment processing failed

RepaymentInstallment Status

NOT_PAID: No payments received
PARTIALLY_PAID: Partial payment received
PAID: Fully paid
LOAN_NOT_DISBURSED: Loan not yet disbursed

Boleto Status

created: Boleto created
registered: Registered with bank
paid: Payment received
credited: Amount credited
overdue: Past due date
canceled: Canceled boleto

🎯 Business Rules

Payment Allocation Rules

Payments are allocated to installments based on business logic
Multiple installments can share a single payment (via PaymentAllocation)
Partial payments are supported and tracked
Discounts can be applied to reduce installment amounts

Payment Method Rules

Each installment can have exactly one Boleto
Each installment can have multiple QR codes for different amounts
QR codes can be linked to multiple installments (shared payments)
Payment methods are generated on-demand

Transaction Processing Rules

All payments go through FacilityRepayTransaction for monitoring
Blockchain transactions are tracked with hash references
Failed transactions maintain error logs for debugging
Transaction status updates trigger downstream processes

📋 Conventions

PK: Primary Key
FK: Foreign Key
UK: Unique Key
||--o{: One-to-Many relationship
}o--||: Many-to-One relationship
||--o|: One-to-One relationship
}o--o|: Zero-or-One relationship