Controlled Automatic Payment Application

🔍 Problem Statement

As a billing administrator, I experience automatic payment applications to invoices without control, which results in payments being applied to unintended invoices and difficulty enforcing consistent billing behavior across accounts.

💡 User Stories

1. As a billing admin, I want to control how customer balances are automatically applied on a per-account basis, so that I can ensure payments are applied according to business rules rather than by default system logic.

2. As a finance manager, I want to choose whether balances are applied automatically or manually, so that I can manage cash application behavior based on the account’s billing needs.

3. As a compliance officer, I want to view an audit trail of all automatic and manual balance applications, so that I can confirm that the system applies funds according to configured rules and provides full traceability.

🎯 Definition of Done (DoD)

✔ Given a customer account with an available balance, when a new invoice is generated, then the balance should only be applied according to that account’s configured rules (e.g., exact match, oldest invoice first, newest invoice first, or manual application).

✔ Given an account with a configured rule, when invoices are generated, then Pelcro should apply or withhold balances in line with that configuration.

✔ Given any balance application event, then Pelcro should log an audit entry containing:

1. Action type (e.g., BALANCE_APPLIED),

2. Affected invoice and payment references,

3. Timestamp and actor (system or user).

✔ This change will impact Billing Engine and Admin UI, specifically:

1. Billing Engine Configuration

2. Introduce per-account settings to define how balances are applied:

3. Exact amount match

4. Oldest invoice first (default)

5. Newest invoice first

6. Manual application – balance remains available until the admin manually applies it to a specific invoice.

7. Configuration stored at the customer account level.

8. Admin UI Enhancements

9. Add a “Payment Application Rules” section to the Customer Account screen, allowing admins to select the desired rule.

10. Add an “Audit Log” tab within the Payment Details view showing all balance applications (automatic or manual).

✔ This solution will include the following limitations:

1. Rules are configured per customer account (no global defaults).

2. Only one rule profile type applies to all invoice types.

3. Audit trail entries are stored in Pelcro’s internal logs, not user-exportable.

4. No migration or retroactive adjustments for balances managed by Stripe.

5. Default behavior remains Stripe-standard automatic application; the new configuration is opt-in.