Lifecycle status & Workflows

Direct Debit Lifecycle Status

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

Status	Description	Permitted Next States
created	Initial state; the Direct Debit exists but lacks a validated CLABE bank account. Waiting for customer acknowledgment and CLABE validation.	`active`, `cancelled`
active	The CLABE is validated and active (and KYC passed for Level 2). The system is ready to perform automated charges. Orders will be generated on schedule.	`pending`, `cancelled`, `completed`
pending	A single charge failed, and the direct debit is awaiting merchant manual retry. Only applies to non-recurring scheduled debits.	`active`, `cancelled`
cancelled	The authorization has been permanently revoked by the merchant. No further orders will be generated.	None (Final state)
completed	All scheduled payments have been processed (end date reached or one-time completed).	None (Final state)

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.