Create Extraordinary Amortization

This endpoint creates an extraordinary amortization over one or more installment of an issuance. The event-conciliation-service groups the instalments into a single extraordinary amortization event, distributes the declared amount according to the informed amortization_type and obtains the Present Value via security-service — the integrator does not calculate Present Value on their side. The reference_date is provided by the caller in the extraordinary amortization request and is the only temporal reference used by the service when classifying overdue instalments and applying the pro-rata discount.

---

Request

ENDPOINT

/event_conciliation/extraordinary_event

METHOD

POST

Request Body

installment_list (an array of installment_number, integers ≥ 1) is required for every type: it defines the target instalments and the amortization_type defines how the amount is distributed across them. The numbers sent in installment_list are resolved by the service against the installment_number of the corresponding security.

Example — early_amortization (a single future instalment):

{
  "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": [1]
}

Example — equal_amount (proportional across the selected instalments):

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

Example — nominal_amount (future instalments at nominal value):

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

Request Body Params

Field	Type	Required	Description
security_key	string (UUID)	Yes	Unique key of the asset (security) to which the amortization will be applied.
investment_key	string (UUID)	Yes	Key of the target investment. Used by security-service as the proportional basis in the Present Value calculation.
amortization_type	string	Yes	Distribution strategy. Values: equal_amount, first_installments, present_amount, matured_installments, early_amortization, nominal_amount, full_amortization.
amount	number	Yes	Total amount to be amortized (in BRL). Distributed across the selected instalments according to the amortization_type.
reference_date	string (date)	Yes	Reference date in YYYY-MM-DD format. Provided by the caller — the service uses it as "today" to classify overdue instalments and apply the pro-rata Present Value discount.
due_date	string (date)	Yes	Target settlement date (typically the same as reference_date).
installment_list	array of integers (≥ 1)	Yes	List of installment_number (not UUIDs) of the target instalments, with minItems: 1. Required for every type — omitting it returns EVC100002. The service resolves each number against the installment_number of the security; non-existent numbers return EVC000007. The legacy installment_key_list has been removed — clients still sending the field receive QIT000001 (400).
total_discount	number	No	Used only with present_amount — distributes the discount in the order interest → penalty → principal.
number_of_installments	integer	Conditional	Required with first_installments: how many of the selected instalments, by due date, receive the amount.

---

Response

STATUS

201

Response Body

{
  "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"
    }
  ]
}

Response Body Params

Field	Type	Description
extraordinary_event_conciliation_key	string (UUID)	Key of the general extraordinary amortization event created.
security_key	string (UUID)	Key of the asset — echoes the value sent.
amortization_type	string	Chosen amortization type — echoes the value sent.
total_expected_amount	number	Sum distributed across the event_conciliation (instalment conciliation events) by the engine of the chosen type.
total_discount_amount	number	Total discount applied. Different from zero only for present_amount.
status	string	Initial status of the extraordinary event. Always pending_conciliation on creation.
reference_date	string (date)	Reference date sent in the request (it must match the payoff date).
due_date	string (date)	Target settlement date sent in the request.
event_conciliation_list	array	List of event_conciliation (instalment conciliation event) generated. event_conciliation_list object.

event_conciliation_list object

Field	Type	Description
event_conciliation_key	string (UUID)	Key of the instalment conciliation event (event_conciliation).
installment_key	string (UUID)	Key of the instalment affected by this conciliation event.
expected_amount	number	Amount assigned to this instalment conciliation event by the distribution engine.
discount_amount	number	Share of the total_discount allocated to this instalment conciliation event (present_amount) or difference between the instalment's Present Value and the received share (full_amortization).
due_date	string (date)	Due date of the associated instalment.
status	string	Initial status of the instalment conciliation event. Always pending_conciliation on creation.
event_conciliation_type	string	Type of the event_conciliation. Always extraordinary for instalment conciliation events created by this flow.

---

Errors

Code	HTTP	Meaning
EVC100001	400	Invalid amortization_type. Use one of the seven supported values.
EVC100002	400	installment_list is required (and non-empty) for every amortization type.
EVC100003	400	number_of_installments is required for first_installments.
EVC100004	400	Some informed instalment does not belong to the target security.
EVC000007	404	Some integer in installment_list does not match any installment_number of the security (InstallmentNumberNotFound).
QIT000001	400	Schema failure — for example, sending the legacy installment_key_list (removed) or an installment_list item that is not an integer ≥ 1.
EVC100005	400	amount does not cover all the selected instalments (not applicable to early_amortization).
EVC100006	400	total_discount exceeds the sum of the Present Value of the selected instalments.
EVC100007	400	For matured_installments, all the selected instalments must be overdue.
EVC100008	400	There is already a pending extraordinary amortization for the instalment — cancel it before creating another.
EVC100013	424	Security API unavailable (Failed Dependency). Transient — retry once it is restored.
EVC100015	400	early_amortization requires exactly 1 instalment in installment_list.
EVC100016	400	The target instalment of early_amortization must not be overdue.
EVC100017	400	In early_amortization, amount must be less than or equal to the Present Value of the instalment.
EVC100030	400	In nominal_amount, every selected instalment must be a future one (not overdue on the reference_date).
EVC100031	400	In nominal_amount, amount must be less than or equal to the sum of the nominal values of the selected instalments.
EVC100032	400	No selected instalment would receive a positive expected_amount — the event is not created.
EVC100033	400	The sum of the distributed expected_amount differs from the declared amount by more than R$ 0.01.
EVC100034	400	A selected instalment would end with an expected_amount of zero — select only instalments the amount covers.
EVC100035	400	amount exceeds the sum of the selected instalments' Present Values (Present-Value-priced types).

Refer to the Error catalog for complete resolution.

---

See also

• Simulate Present Value of the Extraordinary Amortization
• Query Extraordinary Amortization
• Concept
• Integration Guide
• Business Rules
• Examples