Skip to main content

Insurance

This manual goes through the steps of the payroll credit issuance flow linked to insurance contracting. The disbursement of these operations will be carried out in an internal account owned by the borrower, opened during the issuance flow. From this account, a split will occur in the credit disbursement, transferring part of the disbursed amount to an external account to QI owned by the borrower and the remainder for the insurance premium payment.

1. BC PROTEGE+ Query​

The insurance issuance flow along with a credit operation will involve opening an internal account at QI owned by the borrower. To open the account, it is necessary that the borrower is not on the BC PROTEGE+ list. It is possible to perform the query via API using the following endpoint. If the borrower is on the list, the insurance will be canceled after formalization.

GET
/bacen_protect/validate/[document_number]
Response Body
{
    "permission_result": "approved"
}
Sandbox Testing

CPFs starting with 9 will return rejected permission.

2. Debt simulation and issuance​

To simulate and issue a debt linked to insurance issuance, an object must be added to the rebates list within the financial object.

Rebate Object
{
  "rebates": [
    {
      "fee_type": "insurance_premium_qi",
      "description": "insurance_premium_description"
    }
  ]
}

Simulation payload example​

POST
/debt
request_body
{
    "borrower": {
        "person_type": "natural"
    },
    "financial": {
        "first_due_date": "2024-12-07",
        "installment_face_value": 100,
        "disbursement_date": "2024-11-05",
        "limit_days_to_disburse": 3,
        "number_of_installments": 4,
        "monthly_interest_rate": 0.018,
        "interest_type": "pre_price_days",
        "fine_configuration": {
            "monthly_rate": 0.01,
            "interest_base": "calendar_days",
            "contract_fine_rate": 0.02
        },
        "credit_operation_type": "ccb",
        "interest_grace_period": 0,
        "principal_grace_period": 0,
        "rebates": [
          {
            "fee_type": "insurance_premium_qi",
            "description": "insurance_premium_description"
          }
        ]
    }
}

Issuance payload example​

POST
/debt_simulation
request_body
{
    "borrower": {
        "name": "Nome devedor",
        "email":"email.devedor@gmail.com",
        "phone": {
            "number": "999538380",
            "area_code": "84",
            "country_code": "055"
        },
        "gender": "female",
        "political_exposition": "not_exposed",
        "address": {
            "city": "Natal",
            "state": "RN",
            "number": "1984",
            "street": "Rua",
            "complement": "complemento",
            "postal_code": "59065720",
            "neighborhood": "bairro"
        },
        "role_type": "issuer",
        "birth_date": "1959-07-08",
        "mother_name": "NOME DA MAE",
        "nationality": "Brasileiro",
        "person_type": "natural",
        "marital_status": "single",
        "attached_documents_list": [],
        "individual_document_number": "14471835092",
        "document_identification_date": "2015-10-02",
        "document_identification_type": "rg",
        "document_identification_number": "003709888"
    },
    "financial": {
        "interest_type": "pre_price_days",
        "first_due_date": "2023-09-21",
        "disbursement_date": "2024-11-07",
        "fine_configuration": {
            "monthly_rate": 0.0166,
            "interest_base": "calendar_days",
            "contract_fine_rate": 0
        },
        "credit_operation_type": "ccb",
        "interest_grace_period": 0,
        "monthly_interest_rate": 0.0166,
        "installment_face_value": 101.84,
        "limit_days_to_disburse": 7,
        "number_of_installments": 10,
        "principal_grace_period": 0,
        "rebates": [ // Opcional
          {
            "fee_type": "insurance_premium_qi",
            "description": "insurance_premium_description"
          }
        ]
    },
    "simplified": true,
    "collaterals": [
        {
            "percentage": 1,
            "collateral_type": "private_payroll",
            "collateral_data": {
                "employer_document_number": "07940839000159",
                "registration_number": "99999999999-A"
            }
        }
    ],
    "additional_data": {
        "contract": {
            "contract_number": "TST0000644799"
        }
    },
    "purchaser_document_number": "32402502000135",
    "disbursement_bank_accounts": [
        {
            "name": "NOME DEVEDOR",
            "bank_code": "001",
            "account_digit": "0",
            "branch_number": "2874",
            "account_number": "000057555",
            "document_number": "14471835092",
            "transfer_method": "pix",
            "percentage_receivable": 100
        }
    ]
}
Product Selection

The description enumerator is used to define the type of insurance product that will be issued, which directly affects the premium amount and coverages. Consult the operations team to know which enumerators should be used in your integration.

3. Formalization​

During the debt formalization flow in QI Sign, some screens will be presented to ensure the borrower's awareness and consent regarding insurance contracting.

OPT-OUT

It is possible that the borrower decides to abandon the insurance contracting and proceed only with credit contracting. In this case, the amount that would be destined for the insurance premium will also be disbursed to the borrower's account.

Along with the credit formalization webhook, an event will be sent informing whether the insurance was accepted or rejected in the formalization flow.

WEBHOOK_TYPE
insurance_premium.status_change
Webhook Body
{
  "data": {
    "credit_operation_key": "5ae2c008-44c1-4435-bbfa-094a4b11d962",
    "payment_account": {
      "account_number": "1234567",
      "account_digit": "8",
      "account_branch": "0001",
      "owner_document_number": "98765432100",
      "ispb": "32402502"
    }
  },
  "event_datetime": "2023-03-03 22:39:39",
  "key": "dc575950-dcce-48e1-99a6-5fb0ada63d86",
  "status": "accepted",
  "webhook_type": "insurance_premium.status_change"
}
Rejection Reason

The possible rejection reason enumerators can be consulted in the Rejection reasons table.

Account Opening

After debt formalization with insurance, an internal account is opened where the full credit operation disbursement amount will be deposited and from which the split between the amount disbursed to the borrower and the insurance premium amount will be performed. The bank account details are provided in the payment_account object.

4. Internal disbursement​

After the endorsement stage, the operation will be disbursed to the internal account opened after formalization and the following disbursement webhook will be sent.

WEBHOOK_TYPE
debt
STATUS
disbursed
payload
{
    "key": "53f23b3be-2bc8-46fb-943f-5d4532eecf5e",
    "data": {
      "installments": [
        {
          "due_date": "2026-01-24",
          "total_amount": 4645.64,
          "installment_key": "80f8f098-0232-4543-1e6b-50f970bac6e2",
          "pre_fixed_amount": 74.31,
          "installment_number": 1,
          "principal_amortization_amount": 4571.33
        }
      ],
      "ted_receipt_list": [],
    "status": "disbursed",
    "webhook_type": "debt",
    "event_datetime": "2025-12-26 18:56:45"
  }
}

5. Post-disbursement actions​

To monitor success or failure in transfer attempts to the external account owned by the borrower, the following webhook should be monitored.

WEBHOOK_TYPE
after_disbursement_action_update
Webhook Body
{
  "data": [
    {
      "action_error": {
        "description": "An error occurred while sending pix_transfer bfea6188-879c-46e5-b842-d1e934d44775 to SPI",
        "error_code": "disbursing_error"
      },
      "status": "error",
      "action_data": {
        "pix_transfer_type": "manual",
        "target_account": {
          "document_number": "98765432100",
          "financial_institution_code": 1,
          "ispb": 0,
          "name": "Nome Tomador",
          "financial_institution_code_number": "341",
          "account_branch": "9123",
          "account_digit": "0",
          "account_number": "9999"
        },
        "transaction_amount": 100
      },
      "action_key": "fcec7529-3598-4ce2-9448-4c24d1cb9df0",
      "execution_data": null,
      "action_type": "pix"
    }
  ],
  "event_datetime": "2025-12-30 13:25:08",
  "key": "e7a73248-d737-4cb4-ad07-6d303fc4b96c",
  "webhook_type": "debt_actions"
}

Post-disbursement action resubmission​

In case of failure, the following endpoint should be used for post-disbursement action resubmission

ENDPOINT
/baas/action/ACTION-KEY
METHOD
PATCH
payload
{
  "pix_transfer_type": "manual",
  "target_account": {
      "name": "Nome Tomador",
      "account_digit": "0",
      "account_branch": "9123",
      "account_number": "9999",
      "document_number": "98765432100",
      "financial_institution_code_number": "341"
  }
}
Sandbox Testing

To test a post-disbursement action failure, you can use account number 11581339 for manual pix or key b9380607-dac6-4e17-8ca7-eb761e3aa1dc for pix key.

payload
	"disbursement_bank_accounts": [{
			"document_number": "77564023082",
			"name": "Jorge Augusto Salgado Salhani",
			"pix_transfer_type": "manual",
			"bank_code": "001",
			"branch_number": "0001",
			"account_number": "11581339",
			"account_digit": "0",
			"percentage_receivable": 100
		}]

To test a TED transfer refusal, use the endpoint:

ENDPOINT
/mock/ted/ted_refusal
METHOD
POST
Request Body
{
  "transaction_key": "\<Chave unitária da transação\>"
}

6. Cancellation in case of post-disbursement action failure​

In case of failure where internal disbursement has already been done, post-disbursement action with failure and no action resubmission, the following endpoint should be used for cancellation.

ENDPOINT
/debt/DEBT-KEY/reversal
METHOD
PUT
payload
{}

7. Insurance issuance​

After success in the post-disbursement action, the premium amount transfer will be performed and insurance will be issued. To monitor the insurance status, the following webhook should be monitored.

WEBHOOK_TYPE
insurance_premium.status_change
Webhook Body
{
  "data": {
    "credit_operation_key": "5ae2c008-44c1-4435-bbfa-094a4b11d962",
    "insurance_policy_document_key": "9990ce22-aeac-4728-82da-d1f22c33873f",
    "insurance_date": "2024-09-11",
    "term_start_date": "2024-09-11",
    "term_end_date": "2025-09-11",
    "insurance_amount": 1600,
    "operation_amount": 6400,
    "covers": [
      {
        "cover_amount": 200,
        "cover_type": "permanent_disability",
        "cover_prize_amount": 572.82
      },
      {
        "cover_amount": 100,
        "cover_type": "accidental_death",
        "cover_prize_amount": 572.82
      },
      {
        "capitalcover_amount_segurado": 300,
        "cover_type": "unemployment",
        "cover_prize_amount": 572.82
      }
    ],
    "policy_number": "1098200000008",
    "prize_number": "3907",
    "insurance_premium_net_amount": 1145.63,
    "iof_amount": 4.37
  },
  "event_datetime": "2023-03-03 22:39:39",
  "key": "dc575950-dcce-48e1-99a6-5fb0ada63d86",
  "status": "active",
  "webhook_type": "insurance_premium.status_change"
}
Insurance Cancellation

To check the possible reasons for insurance cancellation, consult the Cancellation reason table.

Mandatory policy ticket sending to borrower

It is mandatory that the policy pdf is sent to the borrower after insurance issuance. The document can be consulted through the document query using the insurance_policy_document_key provided in the insurance issuance webhook.

Sandbox Testing

To test insurance cancellation, you can use the following endpoint:

POST
/mock/insurance_premium/[INSURANCE-PREMIUM-KEY]/cancel

Insurance query​

To actively query insurance information, the following endpoint can be used.

GET
/debt/[DEBT-KEY]/insurance_premium/[INSURANCE-PREMIUM-KEY]
STATUS
200
Response Body
{
  "insurance_premium_key": "e4fe84e3-cc71-481b-87ea-8a07f7d69079",
  "status": "active",
  "credit_operation_key": "5ae2c008-44c1-4435-bbfa-094a4b11d962",
  "disbursement_key": "bd0ea133-ff47-4a21-a3e6-24186e5e2fc1",
  "contract_number": "4069550961/QIT",
  "requester_key": "1040ce22-aeac-4728-82da-d1f22c33873f",
  "insurance_policy_document_key": "9990ce22-aeac-4728-82da-d1f22c33873f",
  "insurance_date": "2024-09-11",
  "term_start_date": "2024-09-11",
  "term_end_date": "2025-09-11",
  "insurance_amount": 1600,
  "operation_amount": 6400,
  "customer": {
    "customer_key": "cd587fa8-3abd-4023-99ab-957df60933a5",
    "document_number": "08556878350",
    "name": "Wilker Oliveiraço",
    "birth_date": "1998-03-21",
    "gender": "male",
    "email": "urich.oliveira@yopmail.com",
    "phone": {
      "country_code": "55",
      "area_code": "11",
      "number": "966931427"
    },
    "address": {
      "postal_code": "56821686",
      "state": "CE",
      "city": "Ceará",
      "neighborhood": "Marmiteiros",
      "street": "Conjunto João Gabriel da Mata",
      "number": "95",
      "complement": ""
    }
  },
  "covers": [
    {
      "cover_amount": 300,
      "cover_type": "permanent_disability",
      "cover_prize_amount": 572.82
    },
    {
      "cover_amount": 300,
      "cover_type": "accidental_death",
      "cover_prize_amount": 572.82
    },
    {
      "cover_amount": 300,
      "cover_type": "unemployment",
      "cover_prize_amount": 572.82
    }
  ],
  "policy_number": "1098200000008",
  "prize_number": "3907",
  "insurance_premium_net_amount": 1145.63,
  "iof_amount": 4.37
}

Flowchart​

Attachments​

Rejection reason​

EnumeratorDescription
insurance_rejectedinsurance rejected
bacen_protectbc protect+

Cancellation reason​

EnumeratorDescription
reversed_operationOperation reversed and insurance canceled
cover_limit_amount_exceededOnly insurance was canceled. Some coverage limit was exceeded and insurance issuance was not possible
insurance_premium_cancelOnly insurance was canceled. Borrower cancellation directly with the insurer