Skip to main content

Examples — Extraordinary Amortization

This page presents two creation scenarios. The integrator's interaction is fire-and-forget: it only makes the creation call and QI Tech orchestrates settlement, finalization and cancellation internally. There is no tenant-facing webhook dedicated to the status transitions of the extraordinary event_conciliation; confirmation of the operation's effect is observed through the reports and webhooks that already exist for the underlying operation (e.g. commercial_paper.operation_status_change).

Scenario 1: partial early payoff of an instalment (early_amortization)​

Covers a single future instalment, with partial payment allowed.

POST /event_conciliation/extraordinary_event

{
  "security_key": "971380d4-469e-48f6-a64b-3afb8a88109e",
  "investment_key": "<investment_key>",
  "amortization_type": "early_amortization",
  "amount": 1500.00,
  "reference_date": "2026-04-24",
  "due_date": "2026-04-24",
  "installment_list": [3]
}

Response: 201 Created

{
  "extraordinary_event_conciliation_key": "11111111-1111-4111-8111-111111111111",
  "security_key": "971380d4-469e-48f6-a64b-3afb8a88109e",
  "amortization_type": "early_amortization",
  "total_expected_amount": 1500.00,
  "total_discount_amount": 0,
  "status": "pending_conciliation",
  "reference_date": "2026-04-24",
  "due_date": "2026-04-24",
  "event_conciliation_list": [
    {
      "event_conciliation_key": "22222222-2222-4222-8222-222222222222",
      "installment_key": "33333333-3333-4333-8333-333333333333",
      "expected_amount": 1500.00,
      "discount_amount": 0,
      "due_date": "2026-04-24",
      "status": "pending_conciliation",
      "event_conciliation_type": "extraordinary"
    }
  ]
}

From this 201 onward the integration is complete on the integrator's side. When the payment of R$ 1,500.00 reaches the corresponding settlement account, QI Tech (account-liquidation-api) settles the instalment conciliation event internally and updates the paid_amount; when the sum covers total_expected_amount - tolerance_amount, the parent transitions to paid. If the payment does not come in, the event is cancelled or finalized by the security-service daily settlement routine.

Scenario 2: full payoff with discount (present_amount with 2 installments)​

Creates an amortization with a consolidated discount covering two instalments.

POST /event_conciliation/extraordinary_event

{
  "security_key": "971380d4-469e-48f6-a64b-3afb8a88109e",
  "investment_key": "<investment_key>",
  "amortization_type": "present_amount",
  "amount": 5000.00,
  "reference_date": "2026-04-24",
  "due_date": "2026-04-24",
  "installment_list": [1, 2],
  "total_discount": 100.00
}

Response 201 Created — two instalment conciliation events are generated with the amounts distributed according to the present_amount engine (interest → penalty → principal). See Create Extraordinary Amortization for the complete response shape.

From the 201 onward the integrator's interaction is the same as in Scenario 1: QI Tech settles each instalment conciliation event when the corresponding payments come in, and finalizes or cancels the event internally if the amounts do not arrive within the settlement window.

Scenario 3: settling future instalments at nominal value (nominal_amount)​

The issuer wants to settle instalments 3 and 4 before maturity by paying the nominal value of each (principal + interest at maturity), with no Present Value discount. The reference_date precedes both due dates.

{
  "security_key": "971380d4-469e-48f6-a64b-3afb8a88109e",
  "investment_key": "<investment_key>",
  "amortization_type": "nominal_amount",
  "amount": 18670.00,
  "reference_date": "2026-02-08",
  "due_date": "2026-06-06",
  "installment_list": [3, 4]
}

Response 201 Created — one instalment conciliation event per instalment, with expected_amount equal to the nominal value of each (9360.00 and 9310.00 in this example). If the amount were lower than the sum, instalment 3 would be covered first and instalment 4 would receive the remainder. Overdue instalments return EVC100030; an amount above the sum of the nominal values returns EVC100031. Settlement accepts partial payment, as in early_amortization.

Scenario 4: full settlement for a negotiated amount (full_amortization)​

Issuer and investor agree to settle instalments 1 and 2 for R$ 10,000.00, although their Present Values on the reference_date are R$ 9,460.00 and R$ 9,410.00. The amount is split proportionally to Present Value and each instalment is settled in full at liquidation.

{
  "security_key": "971380d4-469e-48f6-a64b-3afb8a88109e",
  "investment_key": "<investment_key>",
  "amortization_type": "full_amortization",
  "amount": 10000.00,
  "reference_date": "2026-02-08",
  "due_date": "2026-02-08",
  "installment_list": [1, 2]
}

Response 201 Created — two instalment conciliation events with expected_amount 5013.25 and 4986.75 (the sum equals the amount) and discount_amount 4446.75 and 4423.25. An amount above the sum of the Present Values returns EVC100035; an amount too small to give every instalment a positive share returns EVC100034.

Troubleshooting​

The most common error codes when calling creation. For the complete list, refer to the Error catalog.

  • EVC100015 (400, EarlyAmortizationRequiresSingleInstallment) — early_amortization accepts exactly one instalment in installment_list. Reduce it to 1.
  • EVC000007 (404, InstallmentNumberNotFound) — some installment_number sent in installment_list does not exist in the target security. Check the numbers returned by GET /security/security/{security_key} before calling.
  • QIT000001 (400) — schema rejected. Typical cause: sending the legacy installment_key_list field (removed) or non-integer items in installment_list.
  • EVC100016 (400, EarlyAmortizationInstallmentOverdue) — the target instalment of early_amortization is overdue and is not eligible. Select a future instalment.
  • EVC100017 (400, EarlyAmortizationAmountExceedsPresentValue) — in early_amortization, the amount exceeded the Present Value of the instalment. Confirm the PV before calling.
  • EVC100030 (400, InstallmentNotEligibleForNominalAmortization) — in nominal_amount, some instalment in installment_list is already overdue on the reference_date. Select only future instalments.
  • EVC100031 (400, NominalAmountExceedsInstallmentsNominalValue) — in nominal_amount, the amount exceeded the sum of the nominal values (principal + interest) of the selected instalments. Lower the amount.
  • EVC100033 (400, DistributionDoesNotMatchAmount) — the sum of the distributed expected_amount differs from the declared amount by more than R$ 0.01. For present_amount, send an amount equal to the sum of the Present Values minus total_discount.
  • EVC100034 (400, DistributionWithZeroInstallment) — a selected instalment would end with an expected_amount of zero (for example, total_discount equal to the Present Value, or an amount exhausted before the last instalment). Select only instalments the amount covers.
  • EVC100035 (400, AmountExceedsInstallmentsPresentValue) — the amount exceeds the sum of the selected instalments' Present Values. Lower the amount.
  • EVC100013 (424, SecurityApiUnavailable) — Security API temporarily unavailable when fetching the Present Value; this is transient. Wait and repeat the call.
  • SEC000031 (400, PostFixedSecurityNotSupported) — post-fixed assets (CDI, IPCA, IGPM) are not supported in V1. Use pre_price or pre_sac assets.

See also​