Credit Rights Assignment Manual
This manual describes the step-by-step process involved in Credit Rights Assignment to Funds administered by QI CTVM. It also explains the business rules of the product and the key points that the integrating partner must be aware of for a faster and more efficient integration.
Prerequisites
-
An Assignment Contract must have been established and the respective Product must have been activated (see Assignor Onboarding APIs);
-
Only the Fund Manager, the Assignor party to the Contract, and linked Originators can access this service.
-
The unique identification key of the Assignee Fund (fund_class_key) and the unique identification key of the Assignment Configuration (assignment_configuration_key) must be stored.
BASE_URL = "/fund_class/{fund_class_key}/assignment_configuration/{assignment_configuration_key}"
The BASE_URL will be the path used in all endpoints of this API.
State Flow
The Assignment pipeline has two main entities with related state machines. On one side we have the Batch, called assignment, and on the other we have the Assets, called asset. For the former, the flow is as follows:
For the Asset:
Integration Summary
In summary, to reach Asset Portfolio Inclusion, the following steps apply:
- Batch Creation;
- Asset Insertion;
- Close Asset Insertion;
- Asset Eligibility Webhook;
- Document Submission;
- Batch Eligibility Webhook;
- Manager Approval;
- Assignment Term Signature;
- Assignment Payment;
- Asset Portfolio Inclusion;
1 - Batch Creation
For Batch creation, only a unique identifier generated in the integrating partner's system is required. This will be the identifier used both in Webhook responses and in the routes for other features explained below.
It is critically important that this identifier is unique — the QI CTVM system will not allow the partner to send the same Batch twice.
2 - Asset Insertion
Asset insertion is the most delicate part of the entire integration. This section explains the business rules involved in creating Assets, both those independent of asset type and those specific to a particular type.
It is important for understanding this API to understand the concept of Asset Value and Asset Purchase Value. For this, the following notation is used:
[A] as the Asset Purchase Value, provided at the root of the object — it means how much the Fund should pay for this Asset.
[B] as the total sum of Premiums for the operation. It can be obtained by summing all total_values of the premiums provided.
[C] as the total sum of Discounts for the operation. It can be obtained by summing all total_values of the deductions provided.
[D] as the Asset Value, which can be inferred using the following formula:
2.1 - Asset Type-Independent Rules
2.1.1 - Asset Type Compatibility with Assignment Configuration
Each Assignment Configuration is unique per asset type. It is never possible to place CCBs and Invoices in the same batch, for example. The activated product that generated the assignment_configuration_key contains a specific asset type, and that will be the only type accepted in a given Configuration. If this is violated, the following error will be returned:
Response Body
{
"code": "TRC000025"
}
2.1.2 - Insertion into Closed Batches
If an attempt is made to insert an asset into batches that have already been closed, the integrating partner will receive the following error:
Response Body
{
"code": "TRC000022"
}
2.1.3 - Postal Code Validation
The postal code of the borrower's address object must be valid. If an invalid one is provided, the request will not be accepted and will return the following error:
Response Body
{
"code": "TRC000070"
}
2.1.4 - External ID Uniqueness
The same asset cannot be assigned twice by the partner. Therefore, if the asset already exists in our database and has not been discarded, the following error will be raised:
Response Body
{
"code": "TRC000054"
}
2.2 - Rules for Credit Operations
Credit Operations are assets that derive from a commitment made by a Borrower, who borrows money at a given rate and honors a payment commitment according to a specific flow. Therefore, these assets always have an outstanding principal and an interest rate that increases this value. The data structure required for creating a Credit Operation can be found on this page.
2.2.1 - Asset Value vs Outstanding Principal Divergence
For a Credit Operation, the Asset Value must always be greater than or equal to the Outstanding Principal (the principal_value field of the Credit Operation object). The error related to this business rule is:
Response Body
{
"code": "TRC000054"
}
2.2.2 - Contract Issue Value vs Outstanding Principal Divergence
The Contract Issue Value must always be greater than or equal to the Outstanding Principal. The error related to this business rule is:
Response Body
{
"code": "TRC000054"
}
2.2.3 - Sequential Installments
All installments of a credit operation must be ordered in ascending order by maturity date (maturity_date) with sequential numbers (installment_number). If the flow starts with installment number 1, the next must be 2, then 3, and so on.
The errors related to these rules are respectively:
Response Body
{
"code": "TRC000054"
}
Response Body
{
"code": "TRC000054"
}
2.2.4 - Pre-fixed and Post-fixed Objects
According to the interest rate type (interest_rate_type) of an operation, pre-fixed and/or post-fixed objects must be provided. If the interest rate type is pre-fixed, only the pre-fixed object is required. For post-fixed, the post-fixed object is mandatory and the pre-fixed is optional.
3 - Close Asset Insertion
After all assets in the Batch have been created, the partner can trigger closure of Asset Insertion. This process is important so that the QI CTVM system knows that from this point, once all assets have been properly analyzed by Eligibility with all documentation provided, the Eligibility of the entire Batch can be analyzed.
It is not necessary to wait for the Webhook of all Assets before performing this action. As soon as no more assets are to be inserted, this command can be executed.
4 - Asset Eligibility Webhook
As Assets are analyzed against the Fund's Eligibility rules, the system returns Webhooks, one by one. These Webhooks will be identified by the unique asset identifier provided by the partner at creation time.
Only two outcomes can result from this analysis: asset approval or rejection. If the former occurs, the Asset will proceed in the pipeline, subject to document insertion. Otherwise, it moves to the discarded state and will not proceed to the next steps.
5 - Document Submission
Upon approval of an asset in Eligibility, the partner can proceed with document insertion required by the product. Each required document must be submitted in a separate request. Content is transmitted as a Base64 binary, making it possible via JSON like all other APIs in our system.
Note that this request requires, in addition to the file binary, the document type. The Asset will only proceed in the pipeline when all required documents have been submitted. When that happens, it will move to the Pre-Approved (pre_approved) state.
The required documents depend on the Product type and the Fund Regulations. This can be obtained by retrieving the Product from the Assignment Contract that was activated to obtain the assignment_configuration_key for this batch.
It is not necessary to have triggered the Asset Insertion Closure. If you want to link the Document Submission logic to the Receipt of the Webhook, this is entirely possible and recommended.
6 - Batch Eligibility Webhook
As soon as a Batch that has had asset insertion closed, and all its Assets have been either discarded or pre-approved, it will proceed to a Batch-wide Eligibility analysis. Even if all Assets have been approved, the Batch as a whole may cause fund non-compliance. This is why a second eligibility step is needed.
Similar to the Asset, there are two possible outcomes from Eligibility: approval or rejection. The result will be reported through a Webhook, this time identified by the Batch external_id.
If the Batch is rejected, it will be discarded and the process ends. Otherwise, it will proceed to a Manager review and approval step.
7 - Manager Approval
Manager approval must be done through a specific request, or through our Portal. If the Batch is denied, it will be discarded and the process ends. Otherwise, the system generates the Assignment Term and sends it for signature, putting the Batch in the pending_assignment_term_signature state, where it will remain until all related parties sign the Document.
8 - Assignment Term Signature
Once signed, we send a Webhook notifying that the Term has been signed and should proceed to payment, moving to pending_payment.
9 - Assignment Payment
At this point, the system pays the Assignor the total amount of the Assignment — the sum of all total_purchase_value of non-discarded assets — to the account provided at the time of Product activation. Once this payment is confirmed, we send a Webhook and assets begin to be included in the portfolio.
10 - Asset Portfolio Inclusion
Finally, once all assets have been properly included in the portfolio, the Batch becomes completed. From this point, the integrating partner can be fully certain that all those assets are properly within the Fund's inventory.