Feature Summary

A categorized reference of capabilities exposed by the Float Service. For flow details and data models, follow the cross-references on each section.

Float Management

Feature Description

Feature	Description
Create float	Creates a new float for a user after validating subscription status, fraud checks, underwriting eligibility, and any active requirements bypass. Submits a disbursement to the Payments Service and publishes a `user_float_created` event to EventBridge.
Get floats	Returns all floats for a user. Optionally includes computed payback date information.
Get active floats	Returns only floats in an active status (`RETRY`, `DEFAULTED`, `SCHEDULING`, `ACHSENT`, `UNCOLLECTABLE`).
Get float by ID	Returns a single float record by float ID.
Update float	Updates a float’s `ach_debit_status` and `ach_debit_date`. Writes a `SUPPORT` process entry to the collection history log.
Get collection history	Returns all collection attempt records for a given float from the `collection-history` DynamoDB table.

Create float

Creates a new float for a user after validating subscription status, fraud checks, underwriting eligibility, and any active requirements bypass. Submits a disbursement to the Payments Service and publishes a user_float_created event to EventBridge.

Get floats

Returns all floats for a user. Optionally includes computed payback date information.

Get active floats

Returns only floats in an active status (RETRY, DEFAULTED, SCHEDULING, ACHSENT, UNCOLLECTABLE).

Get float by ID

Returns a single float record by float ID.

Update float

Updates a float’s ach_debit_status and ach_debit_date. Writes a SUPPORT process entry to the collection history log.

Get collection history

Returns all collection attempt records for a given float from the collection-history DynamoDB table.

See PostgreSQL Schema for the float data model and API Specification for the full endpoint reference.

Collections

Feature Description

Feature	Description
T-1 Day collection	The day before a float’s due date, submits an ACH debit for users without a valid primary debit card. Users with a valid card are held for the Due Date pinless attempt.
Due Date collection	On the float’s due date, attempts pinless debit first (if a valid card exists). Falls back to ACH on NSF errors. Marks the float `RETRY` if all attempts fail.
Daily Retry	Every morning, retries floats in `RETRY` (and similar) status. Enforces a maximum ACH attempt count and a 90-day age threshold before marking `DEFAULTED`. Checks Plaid balance before attempting; marks `UNCOLLECTABLE` if no valid payment method exists.
Income detection webhook	On income events from the Insight Service, attempts collection on floats in `RETRY` status. Subject to a per-day attempt cap and a cached balance threshold of $50.
Balance update webhook	On balance update events from the Transactions Service, attempts opportunistic collection on floats in `RETRY` status. Applies a more conservative balance check (fee + amount + $20 buffer, configurable via GrowthBook).
ACH settlement handling	Processes ACH payment callbacks from the `prod-payments` Kinesis stream. Updates float status on settlement and notifies the user via Segment, Iterable, and AppsFlyer.
ACH prenotes	Submits zero-dollar USIO prenotes 4 business days before a float’s due date to validate account numbers with the ACH processor. Driven by the weekday `prod-floats-prenote-scheduler` and gated per user by the `floats.prenotes` GrowthBook feature flag.

T-1 Day collection

The day before a float’s due date, submits an ACH debit for users without a valid primary debit card. Users with a valid card are held for the Due Date pinless attempt.

Due Date collection

On the float’s due date, attempts pinless debit first (if a valid card exists). Falls back to ACH on NSF errors. Marks the float RETRY if all attempts fail.

Daily Retry

Every morning, retries floats in RETRY (and similar) status. Enforces a maximum ACH attempt count and a 90-day age threshold before marking DEFAULTED. Checks Plaid balance before attempting; marks UNCOLLECTABLE if no valid payment method exists.

Income detection webhook

On income events from the Insight Service, attempts collection on floats in RETRY status. Subject to a per-day attempt cap and a cached balance threshold of $50.

Balance update webhook

On balance update events from the Transactions Service, attempts opportunistic collection on floats in RETRY status. Applies a more conservative balance check (fee + amount + $20 buffer, configurable via GrowthBook).

ACH settlement handling

Processes ACH payment callbacks from the prod-payments Kinesis stream. Updates float status on settlement and notifies the user via Segment, Iterable, and AppsFlyer.

ACH prenotes

Submits zero-dollar USIO prenotes 4 business days before a float’s due date to validate account numbers with the ACH processor. Driven by the weekday prod-floats-prenote-scheduler and gated per user by the floats.prenotes GrowthBook feature flag.

See Collections Engine for detailed flow diagrams and decision logic.

Bypass & Payback

Feature	Description
Get requirements bypass	Returns the active bypass record for a user, if one exists.
Add requirements bypass	Creates or updates a bypass record with an expiration date and reason. Bypasses the standard eligibility requirements check on the next float creation for that user.
Remove requirements bypass	Deletes the bypass record for a user.
Manual payback	Submits a manual collection payment for an active float via the Payments Service.
Payback for account reactivation	Pays off all overdue floats for a user during account reactivation. Returns the amount collected, any remaining balance, and the masked card number used.

Feature

Description

Get requirements bypass

Returns the active bypass record for a user, if one exists.

Add requirements bypass

Creates or updates a bypass record with an expiration date and reason. Bypasses the standard eligibility requirements check on the next float creation for that user.

Remove requirements bypass

Deletes the bypass record for a user.

Manual payback

Submits a manual collection payment for an active float via the Payments Service.

Payback for account reactivation

Pays off all overdue floats for a user during account reactivation. Returns the amount collected, any remaining balance, and the masked card number used.

See Bypass & Payback for flow details.

Administration

Feature Description

Feature	Description
Ban user	Marks all active floats in `RETRY` or `SCHEDULING` status as `DEFAULTED` when a user is banned from the platform.
QA float creation	Test-environment-only endpoint for creating float records with associated collection history and payment records. Used by QA automation.

Ban user

Marks all active floats in RETRY or SCHEDULING status as DEFAULTED when a user is banned from the platform.

QA float creation

Test-environment-only endpoint for creating float records with associated collection history and payment records. Used by QA automation.