Installments and default
Accepting an agreement generates the installment plan; from then on, management is about the installments — recording payments, tracking late ones and reacting to a break.
How installments are generated
At the moment of acceptance, the system automatically creates one installment per month, starting from the date of the first:
- Amount of each installment = final amount ÷ number of installments, rounded to 2 decimal places;
- The last installment absorbs the rounding, guaranteeing the sum matches the agreement's final amount exactly (e.g. R$ 1,000.00 in 3 installments becomes 333.33 + 333.33 + 333.34);
- Monthly due dates — same base date, month after month (agreement accepted in the portal: first installment due in 10 days).
Each installment has its own cycle:
| Status | Meaning |
|---|---|
pending | Open, awaiting payment |
paid | Paid (with payment amount and date recorded) |
overdue | Past due without payment |
cancelled | Cancelled (e.g. agreement cancelled) |
Recording installment payments
Record the payment with the amount paid and the date — from the agreement screen or via the API (PUT /api/v1/agreements/{id}/installments). Only installments of accepted or active agreements can be updated; a cancelled installment cannot be changed. The agreement screen consolidates the progress: how many installments paid, amount already received and remaining balance.
Agreement break
An agreement with past-due, unpaid installments is a broken agreement. This is a manual action: Dunning does not detect the break on its own — there is no automatic process that scans overdue installments and flips the status. Once you confirm the installments went unpaid, you record the break (via the API, by updating the agreement) and the status becomes defaulted (displayed as "Defaulted"). Two paths from there:
- Regularization — the debtor catches up on the installments and the agreement returns to
active. Nothing is lost. - Cancellation — you close the agreement (
cancelled); the still-pending installments are cancelled along with it, and the original charges return to the collection rule (see below).
Effect on the original charge
When the agreement was accepted, the original charge exited the rule with status negotiated. Cancelling the agreement reopens things automatically: each charge that was negotiated because of that agreement is reverted — back to overdue if already past due, or pending if the due date is still in the future — and re-enrolled into the current collection rule, resuming collection wherever it makes sense. With the charge back to overdue, the daily check treats it like any other overdue charge.
This reversion respects a few safeguards:
- The reversion acts per charge linked to this agreement, not per person: a charge only stays
negotiatedif it is also linked to another live agreement (accepted/active). The other charges in this agreement are reopened normally — cancelling one agreement never keeps another agreement's charges locked. - Charges already paid or cancelled are untouched; the reversion only acts on what the state machine allows.
- Each reversion is recorded in the audit trail (reason
agreement_cancelled).
Mark the break only after confirming the installment was not paid through another means (direct transfer, over-the-counter payment). Dunning an agreement that is actually current is exactly the kind of mistake the compliance engine exists to prevent — but it depends on the status reflecting reality.
Effects on the balance
The agreement does not erase the original debt at acceptance — the discount only becomes final upon fulfillment:
- Completed agreement (
completed): the debt is settled at the agreed final amount; the difference (the discount) is the cost of recovery. - Broken agreement: the discount was conditional on fulfillment. The original charge becomes collectible again at the updated amount — and the daily recalculation of interest and fine starts from the charge's original amount. If installments were paid before the break, adjust the charge amount to reflect what was already paid before resuming collection.
Tracking
The Agreements list shows original amount, discount, final amount, installments and status of each agreement. Filter by status (defaulted) to see the portfolio of broken agreements that needs action, and follow the agreement events via webhook to reconcile with finance.