Private Payroll Manual - Credit Operation Tracking
1. Formalization
After winning the internal auction, the partner must wait to receive the formalization webhook, indicating that the borrower has completed the QI Sign signature flow.
{
"key": "<credit_operation_key>",
"status": "signed",
"signers": [
{
"id": "3271efd3-89ba-43aa-b032-af9a459e6096",
"images": {
"face_image_url": "https://qisign-face-images-bucket-sandbox.s3.amazonaws.com/fad7f924-d210-4ec4-9565-a57662a0a65a.jpeg",
"document_back_url": "https://qisign-personal-documents-bucket-sandbox.s3.amazonaws.com/8c7b68ba-07ad-4188-82ae-679833b2843b.jpeg",
"document_front_url": "https://qisign-personal-documents-bucket-sandbox.s3.amazonaws.com/f63cd291-5668-4926-be5d-9290aeda3f6e.jpeg",
"document_back_template": "cnh_back",
"document_front_template": "cnh_front"
},
"biometry": {
"face_validation": {
"score": 80,
"provider": "qitech",
"available": true
},
"fraud_base_flag": false
},
"document": {
"template": "cnh_front",
"face_match_score": 100
},
"liveness": {
"result": "live"
},
"signed_at": "2025-04-09T19:59:39Z",
"ip_address": "182.224.219.198",
"signer_data": {
"name": "Nome Trabalhador",
"email": "exemplo@qitech.com.br",
"phone": {
"number": "829549234",
"area_code": "11",
"international_dial_code": "55"
},
"address": {
"uf": "SP",
"city": "Sao Paulo",
"number": "123",
"street": "Rua tal do sal",
"complement": "Ap 23",
"postal_code": "00000-000",
"neighborhood": "Pinheiros"
},
"pix_key": "pix03@pix03.com",
"birthdate": "1996-03-13",
"document_number": "504.856.400-66",
"document_submission_method": "email",
"authentication_submission_method": "sms"
}
}
],
"webhook_type": "laas.credit_operation.status_change",
"event_datetime": "2025-04-09 20:00:19",
"signed_contract_url": "https://storage.googleapis.com/sandbox-doc-api/documents/9b55450e-fca5-44f2-9118-5851ed4bd92e/RESTAURANTEBEBBER-TRABALHADOR_SICQ-CCB-0000195364-2230409195718_signed.pdf"
}
In cases of signature failure, the partner will receive a webhook in this format.
{
"key": "e8e28023-fa00-4d12-a410-ede4157957ea",
"data": {
"cancel_reason": "Validação facial não alcançou a pontuação mínima permitida",
"cancel_reason_enumerator": "face_validation_score"
},
"status": "canceled",
"webhook_type": "laas.credit_operation.status_change",
"event_datetime": "2025-11-28 17:35:07"
}
2. Proposal Confirmation
A second webhook is sent informing that the operation is waiting for the endorsement authorization call.
Webhook Body
{
"webhook_type": "laas.private_payroll.reservation_status_change",
"data": {
"reservation_status": "pending_requester_authorization"
},
"key": "<credit_operation_key>",
"event_datetime": "2025-04-09T20:00:20Z",
"status": "pending_requester_authorization"
}
At this moment, the partner can decide to proceed with the operation disbursement or cancel the proposal:
Authorize Endorsement
To proceed with the endorsement, the following call must be made:
Request
Response
Response Body
{
"reservation_key": "<credit_operation_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 the endorsement, it is necessary to cancel the operation.
If the operation was originated via auction, this can be done through the permanent cancellation endpoint, in the same way as done in item 6 - De-endorsement.
If the operation was originated in the active flow, the cancellation must be done through the endpoint that appears in this manual.
The external_key field is the UUID of the credit operation, the same as debt_key and credit_operation_key.
3 - Endorsement
Endorsement Success
In case of successful endorsement, the partner will receive the following webhook:
Webhook Body
{
"webhook": {
"key": "<credit_operation_key>",
"data": {
"collateral_data": {},
"collateral_type": "private_payroll",
"collateral_constituted": true
},
"event_time": "2025-07-10 02:15:01",
"webhook_type": "credit_operation.collateral"
}
}
Endorsement Failure
In case of endorsement failure, a webhook will be sent with the DATAPREV criticism. The possible reasons for endorsement failure can be consulted in the Endorsement failure reason table. Depending on the endorsement error, QI will keep the proposal in "retry mode" making new endorsement attempts until the operation is manually canceled or disbursement options are exhausted.
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"
}
4 - Disbursement
After successful endorsement, the operation will automatically proceed to disbursement.
Disbursement Success
Webhook Body
Disbursement Failure
Webhook Body
{
"key": "<UUID>",
"data": {
"cancel_reason": "A conta de destino encontra-se bloqueada.",
"cancel_reason_enumerator": "blocked_account"
},
"status": "canceled",
"webhook_type": "laas.credit_operation.status_change",
"event_datetime": "2025-10-12 09:54:46"
}
In case of disbursement failure, it is critical that there is action on the proposal, as the margin is not automatically de-endorsed.
It is necessary for the partner to decide whether to contact the borrower to request an update of banking data, making it possible to resubmit the debt payment, or for the partner to make the permanent cancellation call to de-endorse the payroll margin.
5 - Payment Resubmission
To retry the debt disbursement, the following call must be made, updating both the disbursement date and banking data (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. For this API, the payload name was changed from disbursement_bank_accounts to disbursement_account.
To resubmit a debt, a request must be made using the auction_proposal_key.
/private_payroll_auction/auction_proposal/{auction_proposal_key}/change_disbursement_datePATCH{
"disbursement_date": "2025-12-12",
"disbursement_account": {
"document_number": "31233261000185",
"name": "Jorge Augusto Salgado Salhani",
"pix_key": "2f205c99-3161-4120-badd-854039d12de6",
"pix_transfer_type": "key"
}
}
6 - De-endorsement
To permanently cancel the operation and de-endorse the margin, the following call must be made:
Request
/private_payroll_auction/auction_proposal/{auction_proposal_key}/cancelPATCHResponse
Response Body: Canceled proposal
{
"auction_proposal_key": "814e7ed3-4080-4cae-a853-8e12812817ea",
"status": "cancelled"
}
In case of successful change, status 200 will be returned.
If there is any error in the format of the payload sent for the change, an invalid schema error will be returned
7 - Endorsement Query
To query endorsement data and endorsement or de-endorsement protocol receipts, the following endpoint can be used:
It is possible to query endorsement, de-endorsement and suspension receipts with this method. The possible enumerators for protocol_type are available in the Protocol types table
Request
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",
"disbursement_end_date": "2025-02-06",
"annual_interest_rate": 0.6163544955,
"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
Disbursement Resubmission Details
| Field | Type | Description |
|---|---|---|
disbursement_date | string | New disbursement date in YYYY-MM-DD format, not required |
disbursement_account | dict | disbursement account data, not required |
Endorsement Failure Reason
| Enumerator | Description | QI Action |
|---|---|---|
| monthly_interest_rate_exceeds_active_proposal | There is an active proposal in the borrower's CTPS app sent by QI with a lower rate than the endorsement attempt | Retry mode |
| margin_exceeded | Payroll margin exceeded | Retry mode |
| 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 | Endorsement |
| documents_inclusion | Document submission (process of sending formalization documents to DATAPREV) |
| suspension | Suspension |
| deletion | Deletion |