Lifecycle status & Workflows
Understanding the Direct Debit lifecycle is essential for managing automated payments effectively. This page details the various states a debit can inhabit and the automated workflows—from creation to final completion—that drive the payment engine.
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. | active, cancelled |
| active | The CLABE is validated and active. The system is ready to perform automated charges. | paused, cancelled, completed |
| paused | The Direct Debit is temporarily suspended. No charges will be attempted until reactivated. | active, cancelled |
| cancelled | The authorization has been permanently revoked by the merchant or customer. | None (Final state) |
| completed | The Direct Decit has reached its end_date or the payment limit has been met. | None (Final state) |
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.
Step 1: Client sends POST
The merchant initiates the process by sending a POST request with the initial transaction data to the system.
Initial transaction data
Business and security validations
Initial Status: 'created'
Status verification
Direct Debit Activation
This workflow occurs when a customer needs to provide their banking details for the first time to enable the service.
Step 1: Access Activation Link
The user opens the secure link provided in the activation email, which includes a temporary validation token.
GET /direct-debit/activate/id?_v=token
18-digit CLABE, Bank, RFC (optional), and Alias (optional)
Sends customer_clabe data and the direct_debit_id
Verifies CLABE, creates/updates records, and sets status to 'active'
Finds and automatically activates other direct debits with the same CLABE
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.
Step 1: Access Validation Link
The user clicks the validation link sent via email, which directs them to a secure verification page.
GET /direct-debit/id?_v=token
The user verifies that the stored bank information is correct
Sets is_active = true and updates direct_debit status to 'active'
Updated 2 days ago