Manual Consignado Privado - Registration and Disbursement
- External Formalization (previous)
QI Tech webhooks should not be mapped strictly. Additional fields may be included in the webhook payloads returned by our APIs.
You can check and resend webhooks following the detailed instructions in the documentation: Webhook Resend.
1. Proposal confirmation
In the active flow, it's possible to configure the environment so that the operation proceeds to registration and disbursement stages right after the debt formalization is completed by the borrower. Otherwise, a webhook will be sent informing that the operation is awaiting an authorization call to continue the flow (this configuration must be aligned with the operations team).
Registration pending authorization
Webhook Body
{
"webhook_type": "laas.private_payroll.reservation_status_change",
"data": {
"reservation_status": "pending_requester_authorization"
},
"key": "<Debt Key>",
"event_datetime": "2025-04-09T20:00:20Z",
"status": "pending_requester_authorization"
}
At this moment the partner can make the decision to proceed with the operation disbursement or cancel the proposal:
Authorize Registration
To proceed with registration, the following call must be made:
Request
Response
Response Body
{
"reservation_key": "<Debt Key>",
"document_number": "12345678901",
"registration_number": "99999999999-A",
"employer_document_number": "12345678901234",
"external_key": "abc123def456",
"contract_number": "2024001234",
"inclusion_date": "2024-03-18",
"disbursement_date": "2024-03-20",
"contract_data": {
"amount": 5000.00,
"installments": 12,
"interest_rate": 0.018
},
"reservation_data": {
"installment_value": 500.00,
"margin_value": 450.00
},
"reservation_status": "authorized"
}
Cancel operation
To not proceed with registration, it's necessary to cancel the operation.
If the operation was originated in the active flow, this can be done through the permanent cancellation endpoint, in the same way as done in item 5 - Deregistration.
If the operation was originated via auction, the cancellation should be done through the proposal cancellation endpoint, as per the Auction documentation.
The external_key field is the credit operation UUID, the same as debt_key and credit_operation_key.
2 - Registration
Successful registration
In case of successful registration the partner will receive the following webhook:
Webhook Body
{
"webhook": {
"key": "<UUID>",
"data": {
"collateral_data": {},
"collateral_type": "private_payroll",
"collateral_constituted": true
},
"event_time": "2025-07-10 02:15:01",
"webhook_type": "credit_operation.collateral"
}
}
Registration failure
If there's a registration failure, a webhook will be sent with the DATAPREV critique. The possible reasons for registration failure can be consulted in the table Registration failure reason. Depending on the registration error, QI will keep the proposal in "retry" mode making new registration attempts until the operation is manually cancelled or runs out of disbursement options.
Webhook Body
{
"key": "72926c65-35a5-4060-b5ec-af8661d8546a",
"data": {
"collateral_data": {
"status": "pending_reservation",
"last_response": {
"errors": [
{
"enumerator": "monthly_interest_rate_exceeds_active_proposal"
}
]
},
"last_response_event_datetime": "2025-10-10T19:45:39Z"
},
"collateral_type": "private_payroll",
"collateral_constituted": false
},
"event_time": "2025-10-10 00:07:21",
"webhook_type": "credit_operation.collateral"
}
3 - Disbursement
After successful registration, the operation will automatically proceed to disbursement.
Successful disbursement
Webhook Body
{
"key": "8351238-1272-46b2-292b-7161a05c5161",
"data": {
"installments": [
{
"due_date": "2026-04-28",
"total_amount": 180.75,
"installment_key": "6286548-015a-4f26-8fb5-0d23f34554e",
"pre_fixed_amount": 180.75,
"installment_number": 1,
"principal_amortization_amount": 0.0
},
{
"due_date": "2026-05-28",
"total_amount": 180.75,
"installment_key": "b3e719e6-24fc-4ddf-a8b8-ee9012342ba6",
"pre_fixed_amount": 180.75,
"installment_number": 2,
"principal_amortization_amount": 0.0
},
{
"due_date": "2026-06-28",
"total_amount": 180.75,
"installment_key": "3652fb45-4304-4f8e-84ff-1234307042cc",
"pre_fixed_amount": 180.75,
"installment_number": 3,
"principal_amortization_amount": 0.0
},
{
"due_date": "2026-07-28",
"total_amount": 180.75,
"installment_key": "7e2d4334-b963-4a77-1234-4e4fcb1986f8",
"pre_fixed_amount": 180.75,
"installment_number": 4,
"principal_amortization_amount": 0.0
},
{
"due_date": "2026-08-28",
"total_amount": 180.75,
"installment_key": "a1ab6f5b-321b-41a0-a608-0eb54a261014",
"pre_fixed_amount": 180.75,
"installment_number": 5,
"principal_amortization_amount": 0.0
},
{
"due_date": "2026-09-28",
"total_amount": 180.75,
"installment_key": "7d423192-10d4-45c6-8353-7c3be28ee368",
"pre_fixed_amount": 180.75,
"installment_number": 6,
"principal_amortization_amount": 0.0
}
],
"ted_receipt_list": [
{
"fee": 0,
"url": "[URL]",
"amount": 2444.15,
"origin": {
"name": "QI SOCIEDADE DE CRÉDITO DIRETO S.A.",
"type": "payment_account",
"branch": "0001",
"document": "32402502000135",
"bank_code": "329",
"account_key": "65463575-3456-4345-9787-146868523667",
"branch_digit": null,
"account_digit": "1",
"account_branch": "0001",
"account_number": "0000025",
"financial_institution_name": "QI SCD S.A."
},
"timestamp": "2026-01-29T20:03:44",
"description": "12431420 0134 71234489-3 99999999999 - Lucas Blau Mattos",
"destination": {
"name": "Lucas Blau Mattos",
"type": "checking_account",
"branch": "0001",
"purpose": "Crédito PIX em Conta",
"document": "99999999999",
"bank_ispb": "18236120",
"branch_digit": null,
"account_digit": "3",
"account_number": "71234489",
"financial_institution_name": "NU PAGAMENTOS - IP"
},
"end_to_end_id": "E32402502202601291954msTASDFEGS",
"transaction_key": "e89dc7af-165d-4534-b345-11345625d2c6",
"origin_transaction_key": "3415085f-1254-2153-a254-b1254215279e"
}
],
"requester_identifier_key": "1235cd2f-6345-4025-a334-a1435269fe11"
},
"status": "disbursed",
"webhook_type": "debt",
"event_datetime": "2026-01-29 20:03:45"
}
Disbursement failure
TED
In case of TED disbursement failure
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 PIX disbursement failure
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."
}
}
}
In case of disbursement failure, it's critical that action is taken on the proposal, as the margin is not deregistered automatically.
It's necessary for the partner to make the decision to contact the borrower to request an update of banking details so that it's possible to resubmit the debt payment, or for the partner to make the permanent cancellation call to deregister the payroll deduction margin.
4 - Payment resubmission
To retry debt disbursement, the following call should be made updating both the disbursement date and banking details (if the retry is to the same bank account, only the disbursement date parameter can be sent).
The possible disbursement account payloads are available on the disbursement payload examples page.
Request
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
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
}
]
}
5 - Deregistration
Contract deregistration is performed through the permanent cancellation route. This route sets a final status on the contract, which is not subject to retry and triggers the deregistration of the registered margin.
To perform permanent cancellation, the following endpoint should be used:
Request
Webhooks
Webhook Body
{
"key": "<Debt Key>",
"status": "canceled_permanently",
"webhook_type": "debt",
"event_datetime": "2025-03-18 16:41:28",
"data": {}
}
6 - Registration query
To check registration data and registration or deregistration protocol receipts, you can use the endpoint:
It's possible to check registration, deregistration and suspension receipts with this method. The possible enumerators for protocol_type are available in the table Protocol types
Response
Response Body
{
"data": [
{
"reservation_key": "310754e1-cef2-4b19-ba04-7b1c0b575276",
"document_number": "04142652117",
"registration_number": "SECAIXADEA00000000000000006258",
"employer_name": null,
"admission_date": null,
"employer_document_number": "04311093000126",
"external_key": "1d900fed-5ed2-4149-8702-f8dab595b590",
"contract_number": "179799466",
"inclusion_date": "2025-09-30",
"disbursement_date": "2025-02-06",
"contract_data": {
"iof": 227.64,
"periods": [
{
"amount": 338.22,
"due_date": "2025-04-20"
},
{
"amount": 338.22,
"due_date": "2025-05-20"
},
{
"amount": 338.22,
"due_date": "2025-06-20"
},
{
"amount": 338.22,
"due_date": "2025-07-20"
},
{
"amount": 338.22,
"due_date": "2025-08-20"
}
],
"total_amount": 6680.9,
"annual_cet_rate": 0.7176,
"contract_number": "179799466",
"disbursed_amount": 6090.9,
"monthly_cet_rate": 0.0461,
"disbursement_date": "2025-02-06",
"annual_interest_rate": 0.6163544955,
"disbursement_end_date": "2025-02-06",
"monthly_interest_rate": 0.0408
},
"reservation_type": "rollover",
"reservation_status": "reserved",
"protocols": {
"reservation": {
"receipt_url": "[URL]",
"receipt_data": {
"contract_number": "XXX0123456789",
"protocol_number": "21134056260",
"reservation_competence": "2026-03",
"installment_value": 468.6,
"protocol_type": "reservation",
"number_of_installments": 12,
"operation_datetime": "30/01/2026 20:21:22"
},
"protocol_key": "d32342f-369a-4e12-8634-4dfb494d3038"
},
"documents_inclusion": {
"receipt_data": {
"contract_number": "XXX0123456789",
"operation_datetime": "30/01/2026 20:21:29",
"number_of_installments": 12,
"protocol_number": "21134054053",
"installment_value": 468.6,
"protocol_type": "documents_inclusion"
},
"receipt_url": "[URL]",
"protocol_key": "ae018749-7982-4547-92aa-12455e8bafe7"
}
},
}
],
"pagination": {
"current_page": 1,
"next_page": 2,
"rows_per_page": 1
}
}
Attachments
Registration failure reason
| Enumerator | Description | QI Action |
|---|---|---|
| monthly_interest_rate_exceeds_active_proposal | There's an active proposal in the borrower's CTPS app sent by QI with a rate lower than the registration attempt | Retry |
| margin_exceeded | Payroll deduction margin exceeded | Retry |
| allowed_number_of_contracts_exceeded | Maximum number of contracts exceeded | Operation cancellation |
| employment_relationship_blocked | Employment relationship blocked by borrower (can be unblocked via CTPS app) | Operation cancellation |
Protocol types
| Enumerator | Description |
|---|---|
| reservation | Registration |
| documents_inclusion | Document submission (process of sending formalization documents to DATAPREV) |
| suspension | Suspension |
| deletion | Deletion |