Collections

The Float Service implements a sophisticated collection engine designed to optimize repayment rates while maintaining regulatory compliance.

Diagram source code: docs/modules/ROOT/images/diagrams/processes.py.

Scheduled Collections

Scheduled collections follow a multi-stage attempt strategy based on the float’s due date.

1. T-1 Day (6AM)

The day before the float is due, the system checks if the user has a valid debit card on file. * Invalid Card: The system immediately submits an ACH debit attempt. * Valid Card: No action is taken at this stage, waiting for the due date to attempt a pinless debit.

2. Due Date (6AM)

On the actual due date, the system attempts to collect the funds. * Pinless Debit: If a valid debit card exists, a pinless debit is submitted. This is the preferred method as it is instantaneous. * ACH Fallback: If the pinless debit fails with specific NSF (Non-Sufficient Funds) error codes (e.g., USIO 62 or 05), the system automatically falls back to an ACH attempt. * Retry State: If all attempts fail, the float is marked as RETRY.

3. Daily Retry (5AM)

Every morning at 5AM, the system attempts to collect floats in the RETRY state.

Limits: The system stops automated attempts after 3 unsuccessful ACH attempts.
Defaulting: Floats reaching 90 days past due are marked as DEFAULTED.
Balance Checking: Before attempting a retry, the system verifies if the user’s bank balance is sufficient (Float Amount + $10 buffer) to avoid causing overdrafts.

Webhook Collections

Webhook collections are driven by real-time income detection events.

Income Detection: When a deposit is detected in a user’s linked bank account, the webhook-worker is notified.
Eligibility Check: The system checks if the user has a float in RETRY status and ensures it hasn’t already attempted a collection more than twice that day.
Smart Collection: If balance criteria are met, it attempts a pinless debit (preferred) or ACH repayment.