Skip to main content

Extraordinary Amortization

Overview​

Extraordinary amortization is the process of reducing the outstanding balance of an issuance outside the ordinary schedule — when the issuer prepays, settles instalments ahead of their due date, or refinances part of the debt. QI Tech receives this request via API, validates the amounts and registers the event for later settlement, without interfering with the ordinary amortizations generated on each due_date.

Typical scenarios involve early payoff by the issuer, early payment of one or more instalments, and partial refinancing operations. In all of these cases the integrator starts the flow on demand, informing which instalment (or set of instalments) is being amortized and for what amount.

You use this API whenever you need to change the outstanding balance outside the ordinary payment schedule. The result is always a traceable event, with its own status and financial record. Creation is fire-and-forget: QI Tech orchestrates settlement, finalization and cancellation internally, without the integrator having to call additional endpoints.

Ordinary vs extraordinary amortization​

Ordinary amortization is generated automatically by QI Tech: on each due_date, the instalment settlement process is created internally with no action from the integrator. Extraordinary amortization, on the other hand, is always started on demand, through an explicit API call. The two coexist — registering an extraordinary amortization does not cancel or replace the ordinary ones still to fall due; it only adds a new settlement event on the asset.

Amortization types​

The five supported types live in the amortization_type field:

  • equal_amount (proportional amounts) — proportionally distributes the informed amount across the overdue instalments first, and then across the future ones.
  • first_installments (first instalments) — applies the amount sequentially to the first N instalments until it is exhausted.
  • present_amount (present value) — the integrator chooses the instalments and may inform total_discount; the distribution order is interest → penalty → principal.
  • matured_installments (matured instalments) — applies the amount exclusively to instalments that have already fallen due.
  • early_amortization (early amortization) — brings forward the payment of a future instalment.

Only early_amortization allows partial payment — the other four require full coverage of the declared amount within the tolerance.

Key concepts​

  • event_conciliation — corresponds to the conciliation event of a specific instalment. Responsible for the act of conciliating payments and/or extraordinary amortizations of instalments of a security.
  • reference_date — reference date provided by the caller on every creation (it must match the payoff date). QI Tech never uses date.today(): all date-related logic (maturity classification, Present Value projection, discrimination between overdue and upcoming instalments) starts from this field.
  • Present Value — calculated internally and consumed during event creation. The integrator does not need to calculate Present Value on their side.
  • Tolerance (tolerance_amount) — maximum accepted difference between the settlement amount and the expected instalment amount. Defaults to R$ 0.01. Differences above the tolerance cause the settlement to be rejected.
  • Derived partial state — when paid_amount > 0 and paid_amount < expected_amount, the instalment is considered partially paid. There is no new status: the state is DERIVED from the paid_amount and expected_amount columns. The pending_conciliation status covers both "not yet paid" and "partially paid"; paid only appears when the accumulated amount covers the expected one within the tolerance.

Next steps​

Move on to the Integration Guide to see the step-by-step flow. For the scenario in which a new operation repurchases open extraordinary amortizations, see Amortization with Repurchase.