Private Payroll Manual - Legacy Contracts
API under development
The API is still in development phase, therefore this manual is subject to changes.
The renegotiation of a legacy contract is done by creating a new debt, with the legacy contract data informed in the collateral_data field.
To verify the legacy contracts that have been included in the system, you should perform a query for legacy loans. If not found, please contact support to request inclusion.
Due to Private Payroll business rules, currently the worker can have only one active contract. Therefore, if the worker has more than one legacy contract, only one of them can be renegotiated. Similarly, if the worker has an active contract, it will not be possible to create a renegotiation for them.
The debt creation and signature flow is the same used for creating a new credit. The difference is in the debt registration, which is done automatically by the system after contract signature, not requiring manual approval and not needing SCR consultation.
1 - Legacy loans query
GET
/private_payroll/legacy_contractsQuery Parameters
| Parameter | Type | Required | Description | Default Value |
|---|---|---|---|---|
| page | integer | No | Page number to be returned | 1 |
| page_size | integer | No | Number of records per page | 100 |
| document_number | string | No | Customer CPF without punctuation | N/A |
info
Pagination is one-based, therefore the first page is page 1.
Response
STATUS
200 OK{
"data": [
{
"legacy_contract_key": "123e4567-e89b-12d3-a456-426614174000",
"document_number": "29883927061",
"contract_number": "1234567890",
"legacy_contract_data": {
"cet": 0.0637,
"due_balance": 1935,
"total_amount": 2405.76,
"contract_type": "consigned_loan",
"interest_rate": 0.0409,
"period_amount": 129.33,
"contract_end_date": "2026-10-05",
"number_of_periods": 36,
"contract_start_date": "2023-10-06",
"registration_number": "11841",
"number_of_paid_periods": 17,
"employer_document_number": "43028211000145"
},
"status": "active"
}
],
"pagination": {
"current_page": 1,
"next_page": 2,
"rows_per_page": 100,
"total_pages": 1,
"total_rows": 1
}
}
Response Body
The paginated response consists of an array of contracts (data) and a pagination object (pagination).
Contracts list
Description of the data array items:
| Parameter | Type | Required | Description |
|---|---|---|---|
| legacy_contract_key | string | Yes | Legacy contract unique identifier |
| document_number | string | Yes | Customer CPF |
| contract_number | string | Yes | Contract number |
| legacy_contract_data | object | Yes | Legacy contract data |
| status | string | Yes | Contract status |
Legacy contract data
Data contained in the legacy_contract_data object:
| Parameter | Type | Required | Description |
|---|---|---|---|
| cet | decimal | Yes | Total Effective Cost |
| due_balance | decimal | Yes | Outstanding balance |
| total_amount | decimal | Yes | Total contract amount |
| contract_type | string | Yes | Contract type |
| interest_rate | decimal | Yes | Interest rate |
| period_amount | decimal | Yes | Installment amount |
| contract_end_date | string | Yes | Contract end date |
| number_of_periods | integer | Yes | Total number of installments |
| contract_start_date | string | Yes | Contract start date |
| registration_number | string | Yes | Employee registration number |
| number_of_paid_periods | integer | Yes | Number of paid installments |
| employer_document_number | string | Yes | Employer CNPJ |
Pagination data
Data contained in the pagination object:
| Parameter | Type | Required | Description |
|---|---|---|---|
| current_page | integer | Yes | Current page |
| next_page | integer | Yes | Next page |
| rows_per_page | integer | Yes | Number of records per page |
| total_pages | integer | Yes | Total pages |
| total_rows | integer | Yes | Total records |
2 - Legacy Contract Deletion
The deletion of a legacy contract is performed by the following endpoint:
DELETE
/private_payroll/legacy_contract/contract_numberWhere the path parameter "contract_number" should be the contract to be deleted, in string format.
Response
In case of success the following response will be returned:
STATUS
200 OK While in the case where the indicated legacy contract does not exist, a NotFound error will be returned, with error code "PRP000079".
STATUS
404 NOT FOUND 3 - Renegotiation creation
The renegotiation of a legacy contract is performed by creating a debt similar to creating a new credit, with the difference that the legacy contract data must be informed in the collateral_data field as exemplified below:
POST
/debt{
"simplified": true,
"requester_identifier_key": "05a9c4cc-39d5-48fe-ab47-8f1b37d8bffb",
"purchaser_document_number": "30620610000159",
"borrower": {
"role_type": "issuer",
"person_type": "natural",
"name": "EXEMPLO",
"email": "exemplo@exemplo.com",
"individual_document_number": "48674911013",
"birth_date": "1991-01-01",
"mother_name": "MÃE DO EXEMPLO",
"phone": {
"country_code": "55",
"area_code": "11",
"number": "999999999"
},
"address": {
"street": "RUA EXEMPLO",
"number": "123",
"complement": "APTO 123",
"neighborhood": "BAIRRO EXEMPLO",
"postal_code": "12345678",
"city": "SÃO PAULO",
"state": "SP"
},
},
"disbursement_bank_accounts": [
{
"name": "EXEMPLO",
"document_number": "48674911013",
"pix_transfer_type": "key",
"pix_key": "pix03@pix03.com",
"amount_receivable": 2000
},
{
"name": "Cel-lep Ensino De Idiomas S.a.",
"document_number": "10772420000140",
"digitable_line": "32990001039000210987502864982109595090000063958",
"amount_receivable": 639.58
}
],
"financial": {
"credit_operation_type": "ccb",
"interest_type": "pre_price_days",
"interest_grace_period": 0,
"principal_grace_period": 0,
"limit_days_to_disburse": 1,
"number_of_installments": 12,
"installment_face_value": 250,
"disbursement_date": "2025-05-12",
"disbursed_amount": 2639.58,
"first_due_date": "2025-07-28",
"fine_configuration": {
"interest_base": "calendar_days",
"contract_fine_rate": 0.02,
"monthly_rate": 0.01
},
},
"collaterals": [
{
"percentage": 1,
"collateral_type": "private_payroll",
"collateral_data": {
"registration_number": "g7D1IFvUmq2s7zE9UVsV0HQwfcbHj",
"employer_document_number": "60518978000171",
"operation_category": "legacy_contract_refinancing",
"legacy_contract_numbers": ["0000001523EMP"],
}
}
]
}
info
If there is a legal representative, they should be informed in the related_parties field as exemplified in the new credit example.
{
"related_parties": [
{
"role_type": "issuer_legal_representative",
"person_type": "natural",
"name": "REPRESENTANTE EXEMPLO",
"email": "representante.exemplo@exemplo.com",
"individual_document_number": "79795844067",
"birth_date": "1970-04-20",
"mother_name": "MÃE DO REPRESENTANTE",
"phone": {
"country_code": "55",
"area_code": "11",
"number": "999999999"
},
"address": {
"street": "RUA EXEMPLO",
"number": "123",
"complement": "APTO 123",
"neighborhood": "BAIRRO EXEMPLO",
"postal_code": "12345678",
"city": "SÃO PAULO",
"state": "SP"
}
}
]
}
Response
STATUS
201 CreatedResponse Body
{
"webhook_type": "debt",
"key": "<Debt Key>",
"status": "waiting_signature",
"event_datetime": "2025-05-06 10:00:00",
"data": {
"borrower": {
"name": "Nome devedor",
"document_number": "58307769019",
"related_party_key": "28b7fc16-6d1f-467d-9667-62a8c13daea6"
},
"contract": {
"number": "0000644710/NDV",
"urls": [
"https://storage.googleapis.com/sandbox-doc-api/documents/a2e9c83a-3666-4def-8b27-e96fabb8705c/NOME_DEVEDOR-CCB-TST0000644710-20241107231916.pdf"
],
"signature_information": [
{
"signer_name": "Nome devedor",
"signer_document_number": "14471835092",
"signer_role": "issuer",
"signer_email": null,
"signer_external_key": null,
"signature_url": null
}
]
},
"requester_identifier_key": "05a9c4cc-39d5-48fe-ab47-8f1b37d8bffb",
"iof_charge_method": "financed",
"collaterals": [
{
"absolute_amount": null,
"collateral_constituted": false,
"collateral_data": {
"operation_category": "legacy_contract_refinancing",
"legacy_contract_number": "1234567890"
},
"collateral_key": "26c7f4f4-51f3-41fa-b880-9691211136aa",
"collateral_type": "private_payroll",
"created_at": "2024-11-07T23:19:16.413448",
"external_key": null,
"percentage": 1,
"updated_at": "2024-11-07T23:19:16.413441"
}
],
"disbursement_options": [
{
"disbursement_date": "2024-11-07",
"contract_fees": [
{
"fee_type": "spread",
"fee_amount": 4.55
},
{
"fee_type": "ted_fee",
"fee_amount": 1.5
}
],
"external_contract_fees": [
{
"fee_type": "spread",
"fee_amount": 0.0,
"tax_amount": 0.0,
"net_fee_amount": 0.0
}
],
"contract_fee_amount": 6.05,
"external_contract_fee_amount": 0.0,
"net_external_contract_fee_amount": 0.0,
"assignment_amount": 914.3,
"issue_amount": 909.75,
"cet": "2,0100%",
"annual_cet": "27,0481%",
"base_iof": 16.259002146803677,
"additional_iof": 3.45705,
"total_iof": 19.72,
"total_pre_fixed_amount": 108.6508885851,
"installments": [
{
"additional_costs": [],
"business_due_date": "2025-01-21",
"calendar_days": 74,
"due_date": "2025-01-21",
"due_interest": 0.0,
"due_principal": 909.75,
"fine_amount": null,
"has_interest": true,
"installment_number": 1,
"post_fixed_amount": null,
"pre_fixed_amount": 37.1789024864,
"principal_amortization_amount": 64.6610975136,
"tax_amount": 0.3923635397125248,
"total_amount": 101.84,
"workdays": 49.0,
"installment_status": null,
"installment_type": null
},
{
"additional_costs": [],
"business_due_date": "2025-02-21",
"calendar_days": 31,
"due_date": "2025-02-21",
"due_interest": 0.0,
"due_principal": 845.0889024864,
"fine_amount": null,
"has_interest": true,
"installment_number": 2,
"post_fixed_amount": null,
"pre_fixed_amount": 14.2997636051,
"principal_amortization_amount": 87.5402363949,
"tax_amount": 0.753721435360089,
"total_amount": 101.84,
"workdays": 23.0,
"installment_status": null,
"installment_type": null
},
{
"additional_costs": [],
"business_due_date": "2025-03-21",
"calendar_days": 28,
"due_date": "2025-03-21",
"due_interest": 0.0,
"due_principal": 757.5486660915,
"fine_amount": null,
"has_interest": true,
"installment_number": 3,
"post_fixed_amount": null,
"pre_fixed_amount": 11.5685715131,
"principal_amortization_amount": 90.2714284869,
"tax_amount": 0.9845001990781314,
"total_amount": 101.84,
"workdays": 18.0,
"installment_status": null,
"installment_type": null
}
],
"first_due_date": "2025-01-21",
"prefixed_interest_rate": {
"monthly_rate": 0.0166,
"daily_rate": 0.00054142,
"annual_rate": 0.21843191,
"interest_base": "calendar_days_365"
}
}
]
}
}