Collateral execution

---

Introduction

This resource is used to execute a collateral constituted on an investor's quotas, converting the lock into a payment to the creditor.

Unlike the other lock events, the collateral execution generates a redemption request in the fund class and the determined value is paid nominally to the creditor registered in the collateral — not to the investor. The investor's position is reduced in proportion to the redeemed quotas.

Prerequisites

Before requesting the execution, confirm that:

Requirement	Detail
Approved lock	The quota lock must be in the approved status.
Collateral-type lock	Only locks with the collateral object can be executed. Judicial attachment locks cannot.
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 bank account are registered at the time of the quota lock request. An execution requested on a collateral with an incomplete registration is not recorded.

Attention

The bank account given 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 of the investor and does not take part in the execution.

Available on

Profile	Host	Required permission
Manager	manager-api	Write

Base URL for each host: Environments (Hosts).

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 collateral execution: collateral_execution	up to 255	Yes
net_value	float	Net value to be executed and paid to the creditor	-	Yes

The value given in net_value cannot exceed the locked financial value 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 created execution event	36

What happens after the request

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

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

Event Status

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

Tracking

The execution status is queried through the quota lock query endpoint, in 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"
                }
            ]
        }
    ]
}

info

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 is completed, the same event shows status: "done" and the new_locked_quotas field with the number of quotas remaining in the lock.

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

Errors

Status	Code	When it happens
400	QLK000044	The given net_value is null, zero or negative
400	QLK000042	The given net_value 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

Authentication, permission and host errors: see API Errors.