Private Payroll Manual - Internal Auction

1. Auction Start

After configuring the loan request filters, the partner will start receiving webhooks notifying these requests.

{
    "status": "ongoing",
    "event_datetime": "2025-03-20T14:47:43Z",
    "key": "88b0203d-31ad-48c6-a795-b6d45ab4898a",
    "webhook_type": "laas.private_payroll_auction.new_issuer_proposal_request",
    "data": {
        "issuer_proposal_request_key": "88b0203d-31ad-48c6-a795-b6d45ab4898a",
        "status": "ongoing",
        "expiration_datetime": "2025-03-21T11:47:12Z",
        "inclusion_limit_datetime": "2025-03-20T11:49:43Z",
        "issuer_proposal_request_data": {
            "issuer_registration_number": "TESTE123",
            "birth_date": "1973-03-14",
            "disbursed_issue_amount": 2100,
            "admission_date": "2020-03-10",
            "consigned_credit_balance": 10000,
            "eligible": true,
            "employer_document_type": "cnpj",
            "document_number": "00737823780",
            "employer_document_number": "29113956000181",
            "number_of_installments": 10,
            "political_exposition": "not_exposed",
            "name": "VALENTINA SANTOS",
            "alerts": [
                {
                    "alert_type": "leave",
                    "description": "Afastamento",
                    "reference_date": "2025-02-11",
                    "event_id": "123456",
                    "leave_reason_code": 3,
                    "leave_start_date": "2025-02-11",
                    "leave_end_date": "2025-03-11"
                },
                {
                    "alert_type": "termination",
                    "description": "Desligamento",
                    "reference_date": "2025-02-11", 
                    "event_id": "789012",
                    "termination_reason_code": 1,
                    "termination_date": "2025-02-11",
                    "notice_period_start_date": "2025-01-11",
                    "notice_period_end_date": "2025-02-11"
                }
            ]
        },
    }
}

Each loan request goes through two stages: the internal auction and the auction in the CTPS app. The internal auction starts as soon as the webhook is received and ends at the timestamp indicated in the inclusion_limit_datetime field. During this period, proposals from all partners are received and ranked based on the rate. Once the internal auction ends, the proposal with the best conditions is sent to the borrower's CTPS where proposals from all FIs are presented. If no proposal is sent by the end of the internal auction, the first proposal sent after the inclusion_limit_datetime will automatically win and be sent to the CTPS.

2. Credit Proposal

Request

ENDPOINT

- /private_payroll_auction/issuer_proposal_request/{issuer_proposal_request_key}/auction_proposal

METHOD

- POST

Request Body: Including an AuctionProposal in the auction

Disbursed Amount & Interest Rate

{
    "request_control_key" : "111e7ed3-4080-4cae-a853-8e12812817ea",
    "disbursed_issue_amount": 15000,
    "monthly_interest_rate": 0.02,
    "number_of_installments": 48,
    "purchaser_document_number": "01272247000120",
    "days_to_expiration": 10,
    "rebates": [
        {
            "fee_type": "spread",
            "amount_type": "percentage",
            "amount": 4.17
        }
    ]
}

Installment Value & Interest Rate

{
    "request_control_key" : "111e7ed3-4080-4cae-a853-8e12812817ea",
    "installment_face_value": 1000,
    "monthly_interest_rate": 0.02,
    "number_of_installments": 48,
    "purchaser_document_number": "01272247000120",
    "days_to_expiration": 10,
    "rebates": [
        {
            "fee_type": "spread",
            "amount_type": "percentage",
            "amount": 4.17
        }
    ]
}

Response

STATUS

- 200 (Accepted)

Response Body: Proposal created

{
  "auction_proposal_key": "814e7ed3-4080-4cae-a853-8e12812817ea",
  "issuer_proposal_request_key" : "100e7ed3-4080-4cae-a853-8e12812817ea",
  "request_control_key" : "111e7ed3-4080-4cae-a853-8e12812817ea",
  "status": "bid",
  "proposal_score" : 0.4,
  "inclusion_date" : "2025-03-18T14:52:07.123456",
  "rank_position" : null,
  "proposal_data": {
        "simulation": {
            "total_iof": 15.46,
            "annual_cet": 0.0603,
            "monthly_cet": 0.0049,
            "issue_amount": 1015.46,
            "annual_interest_rate": 0.0180272568,
            "monthly_interest_rate": 0.00149,
            "disbursed_issue_amount": 1000.0,
            "installment_face_value": 102.25,
            "number_of_installments" : 48
        },
        "monthly_interest_rate": null,
        "disbursed_issue_amount": 15000,
        "installment_face_value": 102.25,
        "number_of_installments": 48
  },
}

STATUS

- 400 (Rejected)

Response Body: Bad Request

{
  "title": "Bad Request",
  "description": "Calculated installment face value is greater than consigned credit balance",
  "translation": "Schema Invalido",
  "extra_fields": {},
  "code": "QIT000001"
}

3. Auction Closure

When the internal auction ends, a webhook is sent updating the partner on whether they won or lost the auction. In case of victory, the credit operation is created and the QI Sign formalization link is sent to the borrower's CTPS app. From this moment on, the operation monitoring should be performed through the credit_operation_key.

WEBHOOK_TYPE

laas.private_payroll_auction.end_of_auction

{
    "key": "250cfea5-99dc-4c80-be3e-2231350cf9a2", // esta chave é igual à auction_proposal_key
    "data": {
        "auction_proposal_key": "250cfea5-99dc-4c80-be3e-2231350cf9a2",
        "status": "won",
        "type": "auction",
        "rank_position": 1,
        "signature_url": "https://sandbox.sign.qitech.com.br/r/3D1s523",
        "credit_operation_key": "9e06ca79-3610-4794-8312-9663e0343f6b",
        "issuer_proposal_request_key": "262d0584-9827-4652-9b27-6a46c9832f38"
    },
    "status": "won",
    "event_datetime": "2025-03-20T14:48:43Z",
    "webhook_type": "laas.private_payroll_auction.end_of_auction"
}

The credit operation key will be sent with a null value for losing proposals.

Attention

The signature link will not be sent in the production environment, only in sandbox so that it is possible to simulate the borrower's signature.

Attachments

IssuerProposalRequest Object Definition

Name	Type	Description
issuer_proposal_request_key	string	Unique identifier of the Proposal Request
issuer_proposal_request_data	object	Object that describes the Proposal Request data
status	string	Status of the Proposal Request (ongoing, finished, expired)

IssuerProposalRequestData Object Definition

Name	Type	Description
name	string	Full name of the Borrower
document_number	string	CPF of the Borrower
birth_date	string	Date of birth of the Borrower in YYYY-MM-DD format
disbursed_amount	float	Disbursement amount requested by the borrower
number_of_installments	integer	Number of installments requested by the borrower
consigned_credit_balance	float	Available consigned credit balance of the borrower
admission_date	string	Date of admission of the worker in the current position in YYYY-MM-DD format
issuer_registration_code	string	eSocial registration number of the employee
employer_document_number	string	CNPJ of the employer
eligible	boolean	True if eligible, False if not eligible
employer_document_type	string	CNPJ or CPF
alerts	List with history of leaves and employment termination notices, for field details check the table alerts object details

alerts object details

Field	Description
alert_type	Alert type, check possible enumerators in the table Alert types
reference_date	Event reference date
event_id	Event identifier
leave_reason_code	Leave reason in accordance with the eSocial website
leave_start_date	Leave start date
leave_end_date	Leave end date
termination_reason_code	Termination reason in accordance with the eSocial website
termination_date	Employment termination date
notice_period_start_date	Prior notice period start date
notice_period_end_date	Prior notice period end date

Alert types

ENUMERATOR

alert_type

Enumerator	Description
leave	Leave of absence
termination	Prior notice of termination

Proposal Request Status Details

Status	Description
ongoing	Proposal Request in progress, the auction remains active.
finished	Proposal Request completed, the auction has ended and a submitted Proposal was accepted and included.
expired	Proposal Request expired, the auction has ended without the inclusion of any Proposal in due time.

Auction Proposal Request Details

Field	Type	Description	Required
issuer_proposal_request_key	string	Unique identification key of the IssuerProposalRequest included in uuid v4 format.	Yes
auction_proposal_key	string	Unique identification key of the AuctionProposal included in uuid v4 format.	Yes
disbursed_issue_amount	float	Disbursement amount intended by the Proposal.	Yes
purchaser_document_number	integer	CNPJ of the debt purchaser	Yes
monthly_interest_rate	float	Monthly interest rate of the Proposal in the range of 0 to 1 (0% to 100%, respectively).	No
installment_face_value	float	Installment value intended by the Proposal.	No
number_of_installments	integer	Number of installments of the proposal.	Yes
days_to_expiration	integer	Number of days until the proposal expires. If the key is not included, the proposal validity will be 7 days	No
rebates	list	List of credit operation rebates. Uses the same standard as active issuance (/debt)	No