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.

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.
  • 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​