Business Rules — Extraordinary Amortization

This page consolidates the invariants that govern the creation, settlement and cancellation of an extraordinary amortization. Refer to it whenever the endpoint pages cite an error code, a field or a condition that needs additional context.

Reference date (reference_date)

The reference_date is provided by the caller in the creation request and is the only temporal reference used by the service — the system never uses date.today(). All date-dependent logic (classification of overdue instalments, pro-rata Present Value discount, selection of instalments eligible for early_amortization and nominal_amount) starts from this field. The Present Value lookup on security-service receives this same reference_date.

Amortization types

The 7 supported types and how each distributes the amount across the instalments in installment_list:

Type	Distribution rule across the selected instalments	Allows partial payment
equal_amount	Proportional to the Present Value, overdue first and then future	No
first_installments	Sequential across the first N selected instalments (by due date), N = number_of_installments	No
present_amount	Explicit per instalment; discount orders interest → penalty → principal	No
matured_installments	Only instalments already fallen due, by due date	No
early_amortization	A single future instalment, up to its Present Value	Yes
nominal_amount	Future instalments at nominal value (principal + interest), by due date, without Present Value	Yes
full_amortization	Proportional to Present Value across every selected instalment, no cascade; each instalment is settled in full	No

installment_list (an array of integer installment_number) is required for every type — omitting it returns EVC100002. The service resolves each installment_number to the corresponding instalment of the security and fetches the Present Value per selected instalment; the amortization_type only defines how the amount is distributed across those instalments.

Early amortization (early_amortization)

early_amortization allows partial payment (as does nominal_amount). All of the following conditions apply:

• Exactly 1 instalment in installment_list — otherwise, EVC100015.
• The target instalment must not be overdue — otherwise, EVC100016.
• The amount must be ≤ the Present Value of the instalment — otherwise, EVC100017.
• Partial payment is allowed. The state paid_amount > 0 AND paid_amount < expected_amount is derived from the columns; there is no new status enum value. pending_conciliation represents both "not paid" and "partially paid"; the transition to paid only occurs when total_paid_amount >= total_expected_amount - tolerance_amount.

Nominal value amortization (nominal_amount)

nominal_amount settles future instalments at their nominal value — principal plus interest at maturity — without bringing them to the Present Value of the reference_date. All of the following conditions apply:

• Every instalment in installment_list must have a due_date on or after the reference_date — an overdue instalment returns EVC100030.
• The amount is distributed by due date, covering each instalment at its nominal value until it is exhausted; the last instalment reached may receive a partial amount.
• The amount must be ≤ the sum of the nominal values of the selected instalments — otherwise, EVC100031.
• Partial payment is allowed at settlement, with the same derived state described for early_amortization.

Full settlement (full_amortization)

full_amortization uses the declared amount to settle every instalment in installment_list, regardless of each one's Present Value:

• The amount is split across the instalments proportionally to their Present Value on the reference_date, with no cascade — no instalment is left without a share.
• Each event_conciliation is created with expected_amount equal to its share and discount_amount equal to the difference between the Present Value and the share.
• The amount cannot exceed the sum of the selected instalments' Present Values — otherwise, EVC100035.
• At liquidation, paying the share settles the instalment in full on security-service: the paid amount is recorded as paid and the difference as the instalment's discount. The same applies to present_amount.

Consistency between amount and the distribution

After distributing the amount, the service validates the result for every type, in this order:

1. amount greater than the sum of the distributed instalments' Present Values → EVC100035 (Present-Value-priced types; early_amortization and nominal_amount keep EVC100017 and EVC100031).
2. Any selected instalment would end with an expected_amount of zero → EVC100034. No event is created with zero-valued children; select only instalments the amount covers.
3. The sum of the distributed expected_amount differs from amount by more than R$ 0.01 → EVC100033. For present_amount, amount must equal the sum of the Present Values minus total_discount.

The expected_amount values are stored in cents, with the rounding residual on the last instalment, so the event's total_expected_amount always equals the sum of its children.

Settlement flow

Internal orchestration. Settlement of extraordinary events is executed by QI Tech (account-liquidation-api) upon detecting the payment — the integrator does not call any endpoint at this stage, nor receives a webhook dedicated to the status transitions. The rules below describe the internal behaviour so you understand what happens after creation.

Ordinary settlement emits the full total (rule 4). Ordinary settlement on the due_date continues to emit the instalment's full total_amount via SQS; there is no subtraction of paid_amount. The event reconciles the partially-paid state in its own early_amortization engine.

Cancellation and finalization

Internal orchestration. Cancellation and finalization are triggered by a daily routine — the integrator does not call any endpoint to cancel or finalize an extraordinary amortization, and there is no tenant-facing webhook dedicated to these transitions. The description below is informative.

See also

• Concept
• Integration Guide
• Create Extraordinary Amortization
• Query Extraordinary Amortization
• Operation Repurchase
• Examples
• Error catalog