Collateral execution

---

Introduction

This resource executes a collateral constituted over an investor's quotas, converting the lock into a payment to the creditor.

Unlike the other lock events, a collateral execution creates a redemption request in the fund class, and the resulting amount is paid in the name of the creditor registered in the collateral — not to the investor. The investor's position is reduced by the number of quotas actually redeemed.

Prerequisites

Before requesting an execution, make sure that:

Requirement	Detail
Approved lock	The quota lock must be in approved status.
Collateral-type lock	Only locks carrying the collateral object are executable. Lawsuit locks are not.
Identified creditor	collateral.recipient must contain name and document_number.
Creditor bank account	collateral.recipient.bank_account must contain account_number, account_branch, account_digit and financial_institution_ispb.

The creditor and the bank account are registered when the lock is created — see request a quota lock. An execution requested over a collateral with incomplete registration is not recorded.

Attention

The bank account provided in collateral.recipient.bank_account is the creditor's account and is the destination of the execution payment. Do not confuse it with collateral.bank_account_key, which identifies an account belonging to the investor and takes no part in the execution.

Request

ENDPOINT

/quota_lock/investor/INVESTOR_KEY/quota_lock/QUOTA_LOCK_KEY/investor_position_lock/INVESTOR_POSITION_LOCK_KEY/event

METHOD

POST

STATUS

201

Collateral execution

{
    "type": "collateral_execution",
    "net_value": 1000.00
}

Collateral Execution Event

Field	Type	Description	Characters	Required
type	string	Event type enumerator. For a collateral execution: collateral_execution	up to 255	Yes
net_value	float	Net amount to be executed and paid to the creditor	-	Yes

The amount provided in net_value cannot exceed the financial value locked at the time of the request.

Response

Execution recorded

{
    "investor_position_lock_event_key": "UUID"
}

Field	Type	Description	Characters
investor_position_lock_event_key	string	Identifier of the execution event	36

What happens after the request

1. The execution event is recorded with status pending_processing. The locked values remain fully locked at this point.
2. A net_value_redemption redemption request is automatically opened in the fund class, for the amount provided.
3. The redemption request is quoted in the fund class's regular cycle. The payment is issued to the creditor's account, net of income tax (IR) and IOF.
4. Once quotation completes, the number of quotas actually redeemed is deducted from the lock and the event moves to done.

If the redemption request is canceled before quotation, the execution event moves to canceled and the locked values are fully preserved — there is no partial deduction.

Event Status

Enumerator	Description
pending_processing	Execution recorded, awaiting quotation of the redemption request
done	Execution completed, quotas deducted from the lock
canceled	Execution canceled, locked values preserved

Tracking

The execution status is retrieved through the quota lock query endpoint, inside the investor_position_locks[].events[] object.

Event in the lock query

{
    "investor_position_locks": [
        {
            "investor_position_lock_key": "UUID",
            "current_locked_quotas": 100.00000000000000,
            "events": [
                {
                    "quota_lock_event_key": "UUID",
                    "type": "collateral_execution",
                    "status": "pending_processing"
                }
            ]
        }
    ]
}

note

In the query response, the event identifier is returned in the quota_lock_event_key field. It corresponds to the investor_position_lock_event_key returned on creation.

Once the execution completes, the same event shows status: "done" and the new_locked_quotas field with the quantity of quotas remaining in the lock.

There is no dedicated webhook for collateral execution events. The webhooks available for quota locks are described in Quota lock webhooks.

Errors

Status	Code	Description
400	QLK000044	The net_value provided is null, zero or negative
400	QLK000042	The net_value provided exceeds the locked value
400	QLK000036	The selected agent is not the requester of the lock
404	QLK000022	Quota lock not found
404	QLK000037	Locked position not found