Lifecycle status & Workflows

Direct Debit Lifecycle Status

Each Direct Debit follows a strict state machine to ensure security and billing accuracy.

stateDiagram-v2
    [*] --> created: Create Direct Debit
    
    created --> active: Acknowledgment + CEP<br/>Validation + KYC (Lvl 2)
    created --> cancelled: Merchant Cancels
    
    active --> pending: Single Charge Fails<br/>(max attempts)
    active --> cancelled: Merchant Cancels<br/>(if no pending orders)
    active --> completed: All Payments<br/>Processed
    
    pending --> active: Merchant Retry
    pending --> cancelled: Merchant Cancels
    
    completed --> [*]
    cancelled --> [*]
    
    note right of created
        Initial state after creation.
        Requires:
        - Customer acknowledgment
        - CLABE validation (CEP)
        - KYC (Level 2 only)
    end note
    
    note right of active
        Ready for automated charges.
        Orders generated on schedule.
        Webhook: direct_debit.activated
    end note
    
    note right of pending
        Only for non-recurring
        scheduled debits that fail.
        Requires merchant action.
    end note
    
    note left of completed
        Final state.
        All payments processed
        or end_date reached.
    end note

Core Workflows

Direct Debit Creation

The creation workflow initiates the lifecycle of a Direct Debit by processing initial transaction data and determining the necessary activation steps.

Direct Debit Activation

This workflow occurs when a customer needs to provide their banking details for the first time to enable the service.

CLABE Validation

The validation workflow is used when the system already has the customer's banking information on file but requires explicit confirmation before resuming or starting charges.