Private Payroll Manual - Legacy Rollover
The API is still in development phase, therefore this manual is subject to changes.
1 - Prerequisites
To roll over a contract to the new payroll loan model, it must have been previously informed and be in "active" status. If there are still any legacy contracts that have not been informed or are not in the correct status, please urgently inform the operations team. The legacy contracts manual contains the documentation to check informed contracts.
Additionally, per DATAPREV requirement, it's necessary that the borrower is still employed in the same employment relationship as the informed contract. It's possible to check the borrower's active employment relationships without sending an authorization term using the call below (it will validate if there's an active legacy contract for the same CPF):
2 - Employment relationships inquiry for rollover:
The employment relationships inquiry is an asynchronous operation. When sending the request, QI Tech will process the inquiry in the background and return the result through a webhook when completed. The webhook will be sent to the URL configured in your environment.
To check the active employment relationships of a borrower who has an active legacy contract, an employment relationships inquiry should be made using the same endpoint as the issuance flow, adding an extra field to the request payload root.
Request
Request Body
{
"document_number" : "<CPF FUNCIONÁRIO>",
"inquiry_type" : "legacy"
}
Response
Response Body
{
"employment_relationships_inquiry_key": "<UUID>",
"employment_relationships_inquiry_status": "pending_inquiry"
}
Webhooks
Employment relationships inquiry result:
Webhook Body
{
"key": "<Employment Relationships Inquiry Key>",
"status": "completed",
"webhook_type": "laas.private_payroll.employment_relationships_inquiry_status_change",
"event_datetime": "2025-03-24T15:28:31Z",
"data": {
"inquiry_type": "legacy",
"employment_relationships": [
{
"eligible": true,
"document_number": "47812365409",
"registration_number": "99999999999-A",
"employer_document_type": "cnpj",
"employer_document_number": "12345678000173"
},
{
"eligible": true,
"document_number": "47812365409",
"registration_number": "11111111111-B",
"employer_document_type": "cnpj",
"employer_document_number": "43211234000189"
}
]
}
}
Webhook Body
{
"key": "<Employment Relationships Inquiry Key>",
"status": "failure",
"webhook_type": "laas.private_payroll.employment_relationships_inquiry_status_change",
"event_datetime": "2025-03-24T15:28:31Z"
}
3 - Legacy contract rollover call:
The borrower name, employer document, and employment relationship registration number fields must be filled with the data returned in the employment relationships inquiry, otherwise DATAPREV will return an error in the endorsement.
If a registration fee (TAC) was charged in the original operation, the value of this fee will be calculated by the difference between the issuance amount and the sum of the disbursed amount with the IOF amount.
Request
- Legacy contract issued externally
{
"requester_identifier_key": "d6a931e8-1655-479e-97a8-df8b426f49a0",
"borrower": {
"name": "Nome devedor",
"role_type": "issuer",
"person_type": "natural",
"individual_document_number": "14471835092",
},
"collaterals": [
{
"percentage": 1,
"collateral_type": "private_payroll",
"collateral_data": {
"legacy_contract_number": "109230148",
"operation_category": "legacy_contract_rollover",
"employer_document_number": "07940839000159",
"registration_number": "99999999999-A",
},
}
],
"control_number": "CTRL-2025-0001",
"purchaser_document_number": "32402502000135",
"disbursement_bank_account": {
"name": "NOME DEVEDOR",
"bank_code": "001",
"account_digit": "0",
"branch_number": "2874",
"account_number": "000057555",
"document_number": "14471835092",
"transfer_method": "pix",
"percentage_receivable": 100,
},
"financial": {
"interest_type": "pre_price_days",
"disbursement_date": "2024-11-07",
"fine_configuration": {
"monthly_rate": 0.0186,
"interest_base": "calendar_days_365",
"contract_fine_rate": 0,
},
"monthly_interest_rate": 0.04,
"credit_operation_type": "ccb",
"principal_grace_period": 0,
"interest_grace_period": 0,
"total_iof": 50,
"amount": 700,
"disbursed_amount": 500,
"monthly_cet": 0.015,
"annual_cet": 31.81,
"installment_face_value": 82.57,
"installments" : [
{
"due_date":"2025-04-07",
"control_number": "CTRL-2025-1001",
"status": "paid"
},
{
"due_date":"2025-05-07",
"control_number": "CTRL-2025-1002",
"status": "paid"
},
{
"due_date":"2025-06-07",
"control_number": "CTRL-2025-1003",
"status": "opened"
},
{
"due_date":"2025-08-07",
"due_balance": 11.20,
"control_number": "CTRL-2025-1004",
"status": "paid_partial"
},
{
"due_date":"2025-09-07",
"control_number": "CTRL-2025-1005",
"status": "opened"
},
{
"due_date":"2025-10-07",
"control_number": "CTRL-2025-1006",
"status": "opened"
},
{
"due_date":"2025-11-07",
"due_balance": 70.09,
"control_number": "CTRL-2025-1007",
"status": "paid_partial"
}
]
},
}
All installments must be informed, even if they have already been paid. The installment statuses must be informed according to the description below.
Status Description
| Status | Description |
|---|---|
opened | Open installment |
paid_partial | Partially paid installment |
paid | Fully paid installment |
overdue | Overdue and unpaid installment |
Response
Response Body
{
"issue_date": "2024-11-07",
"issuer_name": "Nome Devedor",
"disbursement_start_date": "2024-11-07",
"credit_operation_status_enumerator": "opened",
"original_total_iof": null,
"origin_key": "<UUID>",
"contract_number": "LEG0123456789",
"first_due_date": "2025-04-07",
"disbursement_end_date": "2024-11-07",
"requester_identifier_key": "<KEY>",
"credit_operation_key": "<UUID>",
"operation_type_enumerator": "external_operation",
"issue_amount": 700,
"requester_key": "<UUID>",
"disbursement_date": "2024-11-07",
"total_iof": 50,
"external_contract_fees": [
{
"tax_amount": 50,
"cofins_amount": 0,
"fee_type": {
"enumerator": "tac"
},
"fee_amount": 150,
"csll_amount": 0,
"amount_released": 135,
"irrf_amount": 0,
"billing_type": {
"enumerator": "rebate"
},
"amount": 150,
"amount_type": {
"enumerator": "absolute"
},
"pis_amount": 0,
"rebate_account": null,
"description": null,
"created_at": "2024-11-07T01:51:41",
"net_fee_amount": 135
}
],
"installments": [
{
"principal_amortization_amount": 23.2268766,
"qr_code_url": null,
"installment_type": "principal",
"due_interest": 0,
"paid_amount": 82.57,
"original_total_amount": 82.57,
"tax_amount": 0.12951306,
"due_principal": 10,
"bank_slip_key": null,
"total_accrual_amount": null,
"total_amount": 82.57,
"calendar_days": 145,
"installment_key": "f9d8ecae-a314-460a-987c-3a48afc283ef",
"has_interest": true,
"due_date": "2025-04-07",
"original_principal_amortization_amount": 23.2268766,
"pre_fixed_amount": 82.57,
"digitable_line": null,
"accrual_reference_date": null,
"qr_code_key": null,
"advanced_paid_amount": 0,
"post_fixed_amount": 0,
"original_pre_fixed_amount": 82.57,
"original_due_principal": 635,
"business_due_date": "2025-04-22",
"workdays": 145,
"installment_status": "paid",
"total_paid_amount": 82.57,
"renegotiation_proposal_key": null,
"fine_amount": null
},
{
"principal_amortization_amount": 23.2268766,
"qr_code_url": null,
"installment_type": "principal",
"due_interest": 0,
"paid_amount": 82.57,
"original_total_amount": 82.57,
"tax_amount": 0.12951306,
"due_principal": 10,
"bank_slip_key": null,
"total_accrual_amount": null,
"total_amount": 82.57,
"calendar_days": 145,
"installment_key": "f9d8ecae-a314-460a-987c-3a48afc283ef",
"has_interest": true,
"due_date": "2025-05-07",
"original_principal_amortization_amount": 23.2268766,
"pre_fixed_amount": 82.57,
"digitable_line": null,
"accrual_reference_date": null,
"qr_code_key": null,
"advanced_paid_amount": 0,
"post_fixed_amount": 0,
"original_pre_fixed_amount": 82.57,
"original_due_principal": 635,
"business_due_date": "2025-04-22",
"workdays": 145,
"installment_status": "paid",
"total_paid_amount": 82.57,
"renegotiation_proposal_key": null,
"fine_amount": null
},
...
]
}