Skip to main content

Private Pension Manual - Collateral Registration and Disbursement

Navigation
API under development

The API is still in development phase, therefore, this manual is subject to changes.

Attention!

QI Tech webhooks should not be mapped strictly. Additional fields may be included in the webhook payloads returned by our APIs.

Webhook Resending

You can consult and resend webhooks following the detailed instructions in the documentation: Webhook Resending.

1 - Collateral Registration​

Webhooks​

In case of successful collateral registration, the partner will receive the following webhook:

WEBHOOK TYPE
credit_operation.collateral
STATUS
Opened
Webhook Body
{
  "webhook": {
    "key": "<Debt Key>",
    "data": {
      "collateral_data": "collateral_data": {
            "total_gross_amount_lock": 1500,
            "investment_funds": [
                {
                    "susep_process_number": "111111111111",
                    "certificate": "12345678",   
                    "name": "QI Fund Alpha",
                    "document_number": "32402502000135",
                    "class": "",
                    "subclass": "",
                    "lock_gross_amount": 500,
                },
                {
                    "susep_process_number": "222222222222",
                    "certificate": "87654321",
                    "name": "QI Fund Beta",
                    "document_number": "32402502000135",
                    "class": "",
                    "subclass": "",
                    "lock_gross_amount": 500,
                },
                {
                    "susep_process_number": "333333333333",
                    "certificate": "56781234",  
                    "name": "QI Fund Gama",
                    "document_number": "32402502000135",
                    "class": "",
                    "subclass": "",
                    "lock_gross_amount": 500,
                }
            ]
        },
      "collateral_type": "private_pension",
      "collateral_constituted": true
    },
    "event_time": "2025-07-10 02:15:01",
    "webhook_type": "credit_operation.collateral"
  }
}

Collateral Registration Failure​

If a reservation fails, a webhook will be sent in the following format to inform the occurrence:

WEBHOOK TYPE
private_pension_failed_reservation
STATUS
Failed
Webhook Body
Webhook Body
{
    "key": "<Debt Key>",
    "status": "failed",
    "webhook_type": "private_pension_failed_reservation",
    "event_datetime": "2025-10-26 16:41:28",
    "data": {
        "enumerator": "Fail enumerator.",
        "description": "Descrição da falha.",
    }
}

2 - Collateral Deregistration​

Deregistration of a contract is performed through the permanent cancellation route. This route puts a final status on the contract, which is not subject to retry and triggers the deregistration of the registered collateral.

To perform permanent cancellation, the following endpoint should be used:

POST
/debt/DEBT-KEY/cancel_permanently

Webhooks​

WEBHOOK TYPE
debt
STATUS
canceled_permanently
Webhook Body
{
    "key": "<Debt Key>",
    "status": "canceled_permanently",
    "webhook_type": "debt",
    "event_datetime": "2025-03-18 16:41:28",
    "data": {}
}

3 - Disbursement Failure​

TED​

In case of disbursement failure via TED

WEBHOOK TYPE
debt
STATUS
canceled
Webhook Body
 {
     "key": "<Debt Key>",
     "status": "canceled",
     "webhook_type": "debt",
     "event_datetime": "2025-03-18 16:41:28",
     "data": {
         "ted_refusal": {
             "transaction_key": "16faabfc-3876-437d-a4f6-aae17a1d68c9",
             "description": "341 0000 000000-7 12345678900 - NOME DO EMPREGADO",
             "origin": {
                 "account_key": "a1d2dea5-fa90-4676-a125-da355fdc3ed0",
                 "account_number": "00086",
                 "bank_code": "329",
                 "name": "ACCOUNT TRANSITORY",
                 "type": "payment_account",
                 "document": "32402502000135",
                 "branch_digit": null,
                 "account_digit": "8",
                 "branch": "0001"
             },
             "fee": 0,
             "reason_enumerator": "agencia_conta_invalida",
             "timestamp": "2022-11-07T14:36:05",
             "amount": 483.6,
             "reason": "Agência ou Conta Destinatária do Crédito Inválida",
             "destination": {
                 "branch": "0000",
                 "account_number": "000000",
                 "name": "NOME DO EMPREGADO",
                 "purpose": "Crédito em Conta",
                 "type": "checking_account",
                 "branch_digit": null,
                 "document": "12345678900",
                 "bank_code": "341",
                 "account_digit": "7"
             }
         },
         "cancel_reason": "ted_refusal"
     }
 }

PIX​

In case of disbursement failure via PIX

WEBHOOK TYPE
debt
STATUS
canceled
Webhook Body
{
    "key": "<Debt Key>",
    "status": "canceled",
    "webhook_type": "debt",
    "event_datetime": "2025-03-18 16:41:28",
    "data": {
        "cancel_reason": "pix_refusal",
        "pix_refusal": {
            "reason_enumerator": "invalid_document_number",
            "reason": "CPF/CNPJ do usuário recebedor não é compatível com o titular da conta de destino."
        }
    }
}

4 - Payment Resubmission​

Changes the disbursement date without affecting the financial values of the operation.

POST
/debt/DEBT-KEY/change_disbursement_date

Request​

Request Body
{
    "disbursement_date": "2025-03-19",
    "disbursement_bank_accounts": [
        {
            "branch_number": "1232",
            "account_digit": "4",
            "account_number": "412412412",
            "account_type": "checking_account",
            "document_number": "<CPF DO TRABALHADOR>",
            "bank_code": 184,
            "ispb_number": "17298092",
            "name": "<NOME DO TRABALHADOR>",
            "percentage_receivable": 100
        }
    ]
}

Response​

STATUS
200 OK
Response Body
{
    "disbursement_date": "2025-03-19",
    "disbursement_accounts": [
        {
            "account_branch": "1232",
            "account_digit": "4",
            "account_number": "412412412",
            "account_type": "checking_account",
            "amount_receivable": null,
            "created_at": "2022-05-24T14:51:46",
            "digitable_line": null,
            "disbursement_type": "ted",
            "document_number": "37197645832",
            "financial_institutions": {
                "code_number": 184,
                "ispb": 17298092,
                "name": "BCO ITAÚ BBA S.A."
            },
            "financial_institutions_code_number": 184,
            "is_pix_disbursement": false,
            "ispb": "17298092",
            "name": "Márcio e Catarina Gráfica Ltda",
            "percentage_receivable": 50.0,
            "pix_key": null,
            "pix_transfer_key": null,
            "pix_type": null,
            "qr_code_key": null,
            "retry_counter": 0,
            "retry_vector": null,
            "transaction_key": null,
            "webhook_key": null
        }
    ]
}