APP Integration

Summary

This guide describes how to issue a debt (credit operation) for a natural person through the BNPL / e-commerce flow using the POST /signed_debt endpoint.

This flow supports QR Code payments, allowing you to collect the required disbursement information directly from the QR Code, including the beneficiary's document number, account number, account digit, branch number, and the disbursement amount.

A natural-person issuance represents a standard loan. In this scenario:

• The financial.disbursed_amount field specifies the principal amount to be disbursed to the borrower. It must equal the amount registered in the Pix QR Code informed in disbursement_bank_accounts.
• borrower.person_type must be set to natural.
• The refinanced_credit_operations field must not be provided.

The structure of the borrower, additional_data.contract (opt-in signatures), disbursement_bank_accounts, and the remaining request objects is described in the following sections.

disbursed_amount must equal the QR Code amount

The cash payout (financial.disbursed_amount) must be equal to the amount registered in the Pix QR Code. Decode the QR Code first using POST /pix/decode_qrcode_payload (step 1) to retrieve the amount, then use that value as disbursed_amount on the debt issuance.

1. QR Code decoding

Request

ENDPOINT

pix/decode_qrcode_payload

METHOD

POST

Test in Playground

Request Body

{
   "qr_code_type": "dynamic_instant",
   "qr_code_payload": "00020101021226850014br.gov.bcb.pix2563qrcodepix.bb.com.br/pix/v2/d373e385-dfe7-49f6-b9ec-14ba60a9b8285204000053039865802BR5925TESTE62070503***63047B7D",
   "pix_key": "teste.cobrancapix@gmail.com.br",
   "receiver_conciliation_id": "fgnb4NTt7pOUBGfrcporERwVVqr0f8PWRfK",
   "amount": "9367.61",
   "status": "ATIVA"
}

Response Body

Field	Type	Description	Available
qr_code_type	string	QR Code type: static, dynamic_instant, or dynamic_term.	All
qr_code_payload	string	Original EMV payload received in the request.	All
pix_key	string	Recipient's Pix key extracted from the QR Code payload.	All
transfer_amount	string	Transfer amount, when specified in the QR Code.	static
additional_data	string	Additional data contained in the static QR Code.	static
receiver_conciliation_id	string	Recipient's reconciliation identifier (txid).	dynamic_*
amount	string	Original charge amount.	dynamic_*
status	string	Status of the dynamic charge.	dynamic_*

Status

For dynamic QR Codes, the QR Code status is returned according to the enumeration table below.

Errors

QR Code with invalid format

{
  "data": "{\"title\": \"Invalid Qr Code Format\", \"description\": \"The Qr Code format is invalid, please enter a valid Qr Code\", \"translation\": \"O formato do Qr Code é inválido, por favor insira um Qr Code válido\", \"extra_fields\": {}, \"code\": \"PXT000070\"}"
}

QR Code type not identified in payload

{
  "data": "{\"title\": \"Invalid Qr Code Type\", \"description\": \"The Qr Code payload given did not provide a propper Qr Code type\", \"translation\": \"O payload de QR Code fornecido não contêm um tipo de Qr Code Válido\", \"extra_fields\": {}, \"code\": \"PXT000071\"}"
}

Error requesting QR Code payload from the registry institution

{
  "data": "{\"title\": \"Error in Qr Code Payload Request\", \"description\": \"An error occurred while requesting the qr code payload to the registry institution\", \"translation\": \"Um erro ocorreu durante a requisição do payload do qr code para a instituição de registro\", \"extra_fields\": {}, \"code\": \"PXT000069\"}"
}

2. Debt issuance

Request

ENDPOINT

/signed_debt

METHOD

POST

Test in Playground

Request Body

{
   "additional_data": {
      "contract": {
         "contract_number": null,
         "signed": true,
         "signatures": [
            {
               "signer": {
                  "name": "Alan Mathison Turing",
                  "phone": {
                     "number": "912345678",
                     "area_code": "11",
                     "country_code": "055"
                  },
                  "email": "alan.turing@email.com",
                  "document_number": "96969879003"
               },
               "signature": {
                  "ip_address": "168.211.22.84",
                  "timestamp": "27-10-2025 11:07:15",
                  "signature_file": {
                     "file_url": "http://qitech.com.br/signature.pdf",
                     "file_type": "pdf"
                  },
                  "geolocation": {
                     "long": "-46.63611",
                     "lat": "-23.5475"
                  },
                  "fingerprint_device": null
               }
            }
         ]
      }
   },
   "financial": {
      "number_of_installments": 2,
      "credit_operation_type": "ccb",
      "interest_type": "pre_price_days",
      "monthly_interest_rate": 0.07,
      "disbursed_amount": 150000,
      "fine_configuration": {
         "contract_fine_rate": 0.02,
         "monthly_rate": 0.15,
         "interest_base": "calendar_days"
      },
      "interest_grace_period": 0,
      "disbursement_date": "2026-04-11",
      "first_due_date": "2026-05-10",
      "principal_grace_period": 0
   },
   "purchaser_document_number": "32402502000135",
   "requester_identifier_key": "40822732-c4ce-41fb-9ee5-5e0304cd04a7",
   "document_template_key": "518a0b57-2ce3-4309-94e5-6a95bc056d12",
   "borrower": {
      "email": "alan.turing@email.com",
      "document_identification": "494598fd-c226-4332-a500-591ae3884673",
      "document_identification_back": "494598fd-c226-4332-a500-591ae3884673",
      "birth_date": "1998-06-03",
      "person_type": "natural",
      "is_pep": false,
      "mother_name": "Mother's full name",
      "profession": "Public server",
      "individual_document_number": "82744088021",
      "address": {
         "city": "São Paulo",
         "neighborhood": "CENTRO",
         "street": "Avenida Feliz",
         "complement": "",
         "postal_code": "49026100",
         "state": "SP",
         "number": ""
      },
      "phone": {
         "country_code": "055",
         "number": "912345678",
         "area_code": "11"
      },
      "document_identification_number": "47003534819",
      "name": "Alan Mathison Turing"
   },
   "disbursement_bank_accounts": [
      {
         "qr_code_url": "00020126930014br.gov.bcb.pix2571qrcode-h.sandbox.qitech.app/bacen/cobv/3fecc731adf542659b84be038ec4151e5204000053039865802BR5925LogcardMeiosDePagamentoLt6008SaoPaulo61080145200062070503***6304A936"
      }
   ]
}

Attention

Natural-person issuance uses borrower.person_type: "natural" and an individual_document_number (CPF). financial.disbursed_amount must equal the amount registered in the Pix QR Code sent inside disbursement_bank_accounts — decode the QR Code first via POST /pix/decode_qrcode_payload. Omit refinanced_credit_operations (those are only used when settling existing operations in a refinancing).

Body parameters

Field	Type	Description	Max chars
additional_data *	object	Contract metadata and signature evidence under additional_data.contract (contract number, signed flag, signatures[] with signer and evidence).	-
borrower *	object	Borrower object — Natural person taking out the credit operation.	-
disbursement_bank_accounts *	array	Disbursement bank accounts — array containing the QR Code that receives the disbursement (single item in this flow).	-
financial *	object	Financial object — Financial terms; use disbursed_amount for the cash payout to the borrower.	-
purchaser_document_number *	string	Assignee (purchaser) CNPJ (digits only, no formatting).	-
requester_identifier_key	string	Client tracking key for the request.	50
document_template_key	string	Key of the contract template to be used for the operation.	UUID

Borrower object

Field	Type	Description	Max chars
name *	string	Borrower full name	100
email	string	Borrower email	254
phone	object	Phone object — Contact phone	-
is_pep *	boolean	PEP indicator (http://www.portaldatransparencia.gov.br/download-de-dados/pep)	-
address *	object	Address object — Borrower address	-
role_type	enum	Borrower role in the contract. Default: issuer.	-
birth_date *	date	Borrower birth date (YYYY-MM-DD)	-
mother_name *	string	Mother's full name	100
nationality	string	Nationality	50
profession	string	Borrower profession	100
person_type *	string	Person type — must be natural for individuals	-
individual_document_number *	string	Borrower CPF (digits only)	11
document_identification *	string	DOCUMENT_KEY of the borrower's photo ID PDF (RG or CNH), uploaded beforehand	UUID
document_identification_back	string	DOCUMENT_KEY of the back of the photo ID (uploaded beforehand)	UUID
document_identification_number	string	Borrower ID document number (RG or CNH), digits only	20

Address object

Field	Type	Description	Max chars
city *	string	City	100
state *	string	State (two uppercase letters)	2
number *	string	Street number	10
street *	string	Street name	100
complement *	string	Address complement (free text)	100
postal_code *	string	Postal code (https://www.buscacep.correios.com.br/)	8
neighborhood *	string	Neighborhood	100

Phone object

Field	Type	Description	Max chars
number *	string	Phone number	10
area_code *	string	Area code (https://ddd.guiamais.com.br/)	2
country_code *	string	Country code (https://ddi.guiamais.com.br/)	3

Disbursement bank accounts

In this flow, the disbursement is settled by paying the dynamic Pix QR Code provided by the merchant. Instead of sending the beneficiary bank coordinates, send the QR Code payload inside disbursement_bank_accounts — QI Tech decodes it and routes the disbursement to the QR Code owner.

disbursement_bank_accounts is an array with a single item containing only the QR Code payload:

Field	Type	Description	Max chars
qr_code_url *	string	EMV payload of the dynamic Pix QR Code to be paid.	250

Amount consistency

The amount registered in the QR Code must match financial.disbursed_amount. Decode the QR Code with POST /pix/decode_qrcode_payload (step 1) to retrieve the amount, then use that value as disbursed_amount on the debt issuance.

Financial object

The financial object describes the credit operation's financial terms.

Field	Type	Description	Max chars
disbursed_amount *	float	Cash payout disbursed to the borrower (principal of the credit operation)	-
interest_type	enum	Interest type — Amortization and interest calculation	-
credit_operation_type	enum	Credit operation type — Agreement type	-
monthly_interest_rate	float	Monthly prefixed interest rate as a decimal	-
disbursement_date	date	Disbursement date (YYYY-MM-DD)	-
first_due_date	date	First installment due date (YYYY-MM-DD)	-
interest_grace_period	int	Interest grace period (months)	-
principal_grace_period	int	Principal grace period	-
number_of_installments	int	Number of installments	-
fine_configuration	object	Fine configuration — Late interest and penalty	-

Fine configuration object

Fine configuration defines late penalty and interest for the credit operation.

Field	Type	Description	Max chars
contract_fine_rate	float	Late penalty rate	-
interest_base	enum	Interest base — Interest calculation basis	-
monthly_rate	float	Monthly late interest rate	-

Enumerators

Person type

Value	Description
natural	Natural person
legal	Legal entity

Account type

Value	Description
checking_account	Checking account
deposit_account	Deposit account
guaranteed_account	Guaranteed account
investment_account	Investment account
payment_account	Payment account
saving_account	Savings account
salary_account	Salary account

Interest type

Value	Description
pre_price_days	Price method (equal installments) with daily prefixed interest
pre_price	Price method (equal installments) with prefixed interest in fixed 30-day periods
pre_sac	SAC (constant amortization) with daily prefixed interest
post_sac	SAC with prefixed rate plus post-fixed index (CDI, IPCA, or IGP-M), daily
post_price	Price method with prefixed rate plus post-fixed index in fixed 30-day periods
post_price_days	Price method with prefixed rate plus post-fixed index, daily

Credit operation type

Value	Description
ccb	Bank credit note (Cédula de Crédito Bancário)
cce	Export credit note (Cédula de Crédito à Exportação)
nce	Export credit note (Nota de Crédito à Exportação)

BNPL

For the BNPL / e-commerce flow, ccb is the value used in practice.

Interest base

Value	Description
workdays	Business days, 252-day year
calendar_days	Calendar days, 360-day year
calendar_days_365	Calendar days, 365-day year

Response (HTTP 200)

The synchronous response echoes the request body with fields completed by the platform (for example contract.contract_number and requester_identifier_key).

STATUS

200

Response Body

{
   "additional_data": {
      "contract": {
         "contract_number": "TEST7886216399",
         "signed": true,
         "signatures": [
            {
               "signer": {
                  "name": "Alan Mathison Turing",
                  "phone": { "number": "912345678", "area_code": "11", "country_code": "055" },
                  "email": "alan.turing@email.com",
                  "document_number": "96969879003"
               },
               "signature": {
                  "ip_address": "168.211.22.84",
                  "timestamp": "27-10-2025 11:07:15",
                  "signature_file": { "file_url": "http://qitech.com.br/signature.pdf", "file_type": "pdf" },
                  "geolocation": { "long": "-46.63611", "lat": "-23.5475" },
                  "fingerprint_device": null
               }
            }
         ]
      }
   },
   "financial": {
      "number_of_installments": 2,
      "credit_operation_type": "ccb",
      "interest_type": "pre_price_days",
      "monthly_interest_rate": 0.07,
      "disbursed_amount": 150000,
      "fine_configuration": { "contract_fine_rate": 0.02, "monthly_rate": 0.15, "interest_base": "calendar_days" },
      "interest_grace_period": 0,
      "disbursement_date": "2026-04-11",
      "first_due_date": "2026-05-10",
      "principal_grace_period": 0
   },
   "purchaser_document_number": "32402502000135",
   "requester_identifier_key": "40822732-c4ce-41fb-9ee5-5e0304cd04a7",
   "document_template_key": "518a0b57-2ce3-4309-94e5-6a95bc056d12",
   "borrower": {
      "email": "alan.turing@email.com",
      "document_identification": "494598fd-c226-4332-a500-591ae3884673",
      "document_identification_back": "494598fd-c226-4332-a500-591ae3884673",
      "birth_date": "1998-06-03",
      "person_type": "natural",
      "is_pep": false,
      "mother_name": "Mother's full name",
      "profession": "Public server",
      "individual_document_number": "82744088021",
      "address": { "city": "São Paulo", "neighborhood": "CENTRO", "street": "Avenida Feliz", "complement": "", "postal_code": "49026100", "state": "SP", "number": "" },
      "phone": { "country_code": "055", "number": "912345678", "area_code": "11" },
      "document_identification_number": "47003534819",
      "name": "Alan Mathison Turing"
   },
   "disbursement_bank_accounts": [
      {
         "qr_code_url": "00020126930014br.gov.bcb.pix2571qrcode-h.sandbox.qitech.app/bacen/cobv/3fecc731adf542659b84be038ec4151e5204000053039865802BR5925LogcardMeiosDePagamentoLt6008SaoPaulo61080145200062070503***6304A936"
      }
   ]
}

Webhook (webhook_type: debt)

Once the operation is processed, QI Tech notifies your endpoint with the consolidated debt data, including the issued amount, IOF breakdown, prefixed interest rate, and installment schedule.

Webhook Body

{
   "webhook_type": "debt",
   "key": "4e1ed268-9f29-44ce-9991-3bdf036aeacd",
   "status": "waiting_disbursement",
   "event_datetime": "2026-04-14 03:38:14",
   "data": {
      "borrower": {
         "name": "Alan Mathison Turing",
         "document_number": "82744088021",
         "related_party_key": "71b28fde-5d75-48b4-9c3f-ee531dccac66"
      },
      "contract": {
         "document_key": null,
         "number": "TEST7886216399",
         "urls": [],
         "signature_information": [
            {
               "signer_name": "Alan Mathison Turing",
               "signer_document_number": "82744088021",
               "signer_role": "issuer",
               "signer_email": null,
               "signer_external_key": null,
               "signature_url": null
            }
         ]
      },
      "requester_identifier_key": "40822732-c4ce-41fb-9ee5-5e0304cd04a7",
      "iof_charge_method": "financed",
      "collaterals": [],
      "contract_fees": [ { "fee_type": "spread", "fee_amount": 453.39 } ],
      "external_contract_fees": [ { "fee_type": "tac", "fee_amount": 0, "tax_amount": 0, "net_fee_amount": 0 } ],
      "external_contract_fee_amount": 0,
      "net_external_contract_fee_amount": 0,
      "contract_fee_amount": 453.39,
      "issue_amount": 151131.6,
      "assignment_amount": 151584.99,
      "cet": "7,6600%",
      "annual_cet": "142,4473%",
      "number_of_installments": 2,
      "base_iof": 557.3,
      "additional_iof": 574.3,
      "total_iof": 1131.6,
      "ipoc_code": "324025020203182744088021TEST7886216399",
      "prefixed_interest_rate": {
         "annual_rate": 1.252191589,
         "created_at": "2026-04-14T03:38:10",
         "daily_rate": 0.0022578334,
         "interest_base": "calendar_days",
         "monthly_rate": 0.07
      },
      "installments": [
         {
            "business_due_date": "2026-05-11",
            "calendar_days": 29,
            "due_date": "2026-05-10",
            "due_interest": 0,
            "due_principal": 151131.6,
            "has_interest": true,
            "installment_key": "c00dbecc-efb9-4384-8db3-dadba82f2d70",
            "installment_number": 1,
            "installment_status": "created",
            "installment_type": "principal",
            "pre_fixed_amount": 10214.91484159,
            "principal_amortization_amount": 73277.28515841,
            "tax_amount": 174.25338411,
            "total_amount": 83492.2,
            "workdays": 18
         },
         {
            "business_due_date": "2026-06-10",
            "calendar_days": 31,
            "due_date": "2026-06-10",
            "due_interest": 0,
            "due_principal": 77854.31484159,
            "has_interest": true,
            "installment_key": "d3a2f42d-80cb-4891-b2be-ce80ffd383b2",
            "installment_number": 2,
            "installment_status": "created",
            "installment_type": "principal",
            "pre_fixed_amount": 5637.88515841,
            "principal_amortization_amount": 77854.31484159,
            "tax_amount": 383.04322902,
            "total_amount": 83492.2,
            "workdays": 22
         }
      ],
      "total_pre_fixed_amount": 15852.8
   }
}

3. Debt inquiry

You can query the debt later to retrieve information or track its current status.

Request

ENDPOINT

/v2/credit_operation/requester_identifier_key/REQUESTER-IDENTIFIER-KEY

METHOD

GET

Test in Playground

Path params

Field	Type	Description	Max chars
requester_identifier_key *	string	Client tracking key sent on debt issuance	50

Alternative route

If you have the credit_operation_key (UUID) instead, use GET /v2/credit_operation/{credit_operation_key}.

Response

STATUS

200

Response Body

{
   "credit_operation_key": "0773a1b1-675a-4a10-80a2-a10308c7281e",
   "issue_amount": 151131.6,
   "origin_key": "0773a1b1-675a-4a10-80a2-a10308c7281e",
   "total_iof": 1131.6,
   "assigned_at": null,
   "disbursement_start_date": "2026-04-11",
   "disbursement_end_date": "2026-04-11",
   "issue_date": "2026-04-11",
   "requester_identifier_key": "40822732-c4ce-41fb-9ee5-5e0304cd04a7",
   "installments": [
      {
         "due_date": "2026-05-10",
         "calendar_days": 29,
         "due_principal": 151131.6,
         "has_interest": true,
         "installment_key": "c00dbecc-efb9-4384-8db3-dadba82f2d70",
         "installment_number": 1,
         "installment_status": "created",
         "installment_type": "principal",
         "pre_fixed_amount": 10214.91484159,
         "principal_amortization_amount": 73277.28515841,
         "tax_amount": 174.25338411,
         "total_amount": 83492.2
      }
   ]
}

4. Technical specifications and enums

Installments object

Field	Type	Description
calendar_days	integer	Number of calendar days between installments
due_date	string	Installment due date in calendar days
due_principal	float	Remaining principal on the installment due date before its payment
has_interest	boolean	If true, interest applies to the installment
installment_number	integer	Installment number
pre_fixed_amount	float	Fixed interest amount paid on the installment
principal_amortization_amount	float	Principal amount paid on the installment
tax_amount	float	Base IOF amount of installment
total_amount	float	Installment total value
due_interest	float	Remaining interest after the installment due date before its payment
workdays	integer	Business days between installments

Interest rate object

Field	Description
annual_rate	Annual fixed/floating interest rate expressed as a decimal
daily_rate	Daily fixed/floating interest rate expressed as a decimal
interest_base	Interest base — Interest calculation basis
monthly_rate	Monthly fixed/floating interest rate expressed as a decimal

Tax configuration object

Field	Description
base_rate	Base IOF rate value
additional_rate	Additional IOF rate value

---

Refund Flow

This guide explains how to process full and partial refunds for credit operations originated through the BNPL / e-commerce flow using the POST /signed_debt endpoint.

The refund flow consists of two major steps:

1. Chargeback notification — a webhook is sent whenever a chargeback is processed, regardless of whether it represents a full or partial refund. The webhook contains all the information required to identify and process the chargeback.
2. Renegotiation — after successfully processing the webhook, you may initiate a renegotiation to generate a new installment schedule that reflects the refunded amount. The renegotiation terms are fully configurable and should follow your business rules and policies.

Webhook — Refund received

Overview

As soon as an identified refund is received, QI Tech will send a webhook containing the refund details, including whether it is a full or partial refund and the amount credited to the FIDC account.

Based on this information, you can apply your business policies and determine how to proceed with the refund requested by your customer.

Webhook Body

{
   "origin_key": "d5c88545-4d17-4679-b262-ae170618078a",
   "refund_date": "2026-06-26",
   "webhook_type": "laas.transitory_conciliation.refund",
   "amount": "200.00",
   "event_datetime": "2026-06-12T11:52:22"
}

Renegotiation — Simulation

Overview

Before creating a proposal, you can simulate the refund values for the operation. The simulation returns the affected installments, the present value of the discount and the total amount.

The refund flow uses two amortization types:

• equal_amount — partial refund. Distributes payment_amount across the open installments, reducing the outstanding balance. The operation stays active with remaining installments still open.
• full_settle — full refund. Fully settles the operation on the reference_date. The operation moves to settled and no installments remain.

Request

ENDPOINT

/renegotiation/simulation

METHOD

POST

Test in Playground

Request Body

equal_amount (partial)

{
    "debt_key": "72760166-4ddf-41fb-8a8c-605f8f4fc35c",
    "amortization_type": "equal_amount",
    "reference_date": "2026-04-13",
    "payment_amount": 50.00
}

full_settle (total)

{
    "debt_key": "72760166-4ddf-41fb-8a8c-605f8f4fc35c",
    "amortization_type": "full_settle",
    "reference_date": "2026-04-13",
    "payment_amount": 1043.55
}

Body parameters

Field	Type	Description	Max length
debt_key *	string	Unique credit operation key (DEBT-KEY)	UUID
amortization_type *	string	Refund modality	Amortization type values
payment_amount *	float	Refund amount in BRL. In equal_amount, the partial amount to be amortized. In full_settle, must cover the total outstanding balance on the reference_date.	15,2
reference_date	string	Reference date used to compute the present value (YYYY-MM-DD). Cannot be earlier than the disbursement date.	10
discount_percentage	float	Optional discount percentage over the present value. Cannot be sent together with discount_amount.	-
discount_amount	float	Optional discount amount over the present value. Cannot be sent together with discount_percentage.	-

Amortization type values

Value	Description
equal_amount	Partial refund. payment_amount is distributed proportionally across the open installments; the operation remains active with remaining installments open.
full_settle	Full refund. Fully settles the operation on the reference_date. The operation moves to settled and no installments remain.

Response

STATUS

200

Example response body

{
    "amortization_type": "equal_amount",
    "payment_amount": 50.00,
    "discount_percentage": 0,
    "discount_amount": 0,
    "reference_date": "2026-04-13",
    "affected_installments": [
        {
            "installment_key": "ca5741c7-99a2-42e7-92a1-9328a36e4e88",
            "due_date": "2026-05-07",
            "principal_amount": 15.71,
            "interest_amount": 4.07,
            "fine_amount": 0,
            "total_amount": 19.78,
            "present_amount": 18.00,
            "paid_amount": 18.00,
            "principal_amortization_payment_amount": 18.00,
            "prefixed_interest_payment_amount": 0,
            "fine_payment_amount": 0
        }
    ],
    "remaining_installments": [
        {
            "installment_key": "370e73d1-55d8-431e-9b22-d08fb8297999",
            "due_date": "2026-06-07",
            "principal_amount": 15.71,
            "interest_amount": 4.07,
            "fine_amount": 0,
            "total_amount": 19.78
        }
    ]
}

Renegotiation — Proposal

Overview

After validating the simulation, create a renegotiation proposal. For refund use cases, send payment_type: "internal" so the funds are debited directly from the account_key provided, with no bank slip or Pix generated.

Attention

• The operation must be active and already disbursed.
• reference_date cannot be earlier than the disbursement date.
• request_control_key is required for idempotency.

Request

ENDPOINT

/renegotiation/proposal

METHOD

POST

Test in Playground

Request Body

equal_amount (partial)

{
    "debt_key": "72760166-4ddf-41fb-8a8c-605f8f4fc35c",
    "payment_type": "internal",
    "amortization_type": "equal_amount",
    "reference_date": "2026-04-13",
    "payment_amount": 50.00,
    "account_key": "5ae72355-1e47-4624-9915-ceb93d872194",
    "request_control_key": "94b31045-c8e7-45be-a88d-2ae25c5df5db"
}

full_settle (total)

{
    "debt_key": "72760166-4ddf-41fb-8a8c-605f8f4fc35c",
    "payment_type": "internal",
    "amortization_type": "full_settle",
    "reference_date": "2026-04-13",
    "payment_amount": 1043.55,
    "account_key": "5ae72355-1e47-4624-9915-ceb93d872194",
    "request_control_key": "e5f6c3d4-e5f6-7890-abcd-ef1234567890"
}

Body parameters

Field	Type	Description	Max length
debt_key *	string	Unique credit operation key (DEBT-KEY)	UUID
payment_type *	string	For refund flows, use internal.	Payment type values
amortization_type *	string	Refund modality	Amortization type values
payment_amount *	float	Refund amount in BRL.	15,2
account_key *	string	Internal account key from which the value is debited.	UUID
request_control_key *	string	Client-side idempotency key. Use a unique value per attempt.	50
reference_date	string	Reference date used to compute the present value (YYYY-MM-DD). Cannot be earlier than the disbursement date.	10
discount_percentage	float	Optional discount percentage over the present value. Cannot be sent together with discount_amount.	-
discount_amount	float	Optional discount amount over the present value. Cannot be sent together with discount_percentage.	-

Payment type values

Value	Description
internal	Internal debit from account_key (automatic, no bank slip or Pix). Used for refund flows.
bank_slip	Generates bank slip and Pix.
pix	Pix only.
manual	Manual payment (no payment method generated).

Amortization type values

Value	Description
equal_amount	Partial refund. payment_amount is distributed proportionally across the open installments; the operation remains active with remaining installments open.
full_settle	Full refund. Fully settles the operation on the reference_date. The operation moves to settled and no installments remain.

Response

STATUS

201

Example response body

{
    "proposal_key": "bcc16a6d-ce21-4cd4-8d8c-d26f89ccc685",
    "contract_number": "DWF1761222116",
    "amortization_type": "equal_amount",
    "payment_amount": 50.00,
    "discount_percentage": 0,
    "discount_amount": 0,
    "requester_name": "Dante Ltda",
    "requester_key": "78287247-947d-4730-9bd1-7efb068175b6",
    "origin_key": null,
    "issuer_name": "Dante Ferrarini",
    "issuer_document_number": "31057466093",
    "affected_installments": [
        {
            "installment_key": "ca5741c7-99a2-42e7-92a1-9328a36e4e88",
            "due_date": "2026-05-07",
            "principal_amount": 15.71,
            "interest_amount": 4.07,
            "fine_amount": 0,
            "total_amount": 19.78,
            "present_amount": 18.00,
            "paid_amount": 18.00,
            "principal_amortization_payment_amount": 18.00,
            "prefixed_interest_payment_amount": 0,
            "fine_payment_amount": 0
        }
    ],
    "remaining_installments": [
        {
            "installment_key": "370e73d1-55d8-431e-9b22-d08fb8297999",
            "due_date": "2026-06-07",
            "principal_amount": 15.71,
            "interest_amount": 4.07,
            "fine_amount": 0,
            "total_amount": 19.78
        }
    ],
    "proposal_status": "pending_payment",
    "payment_type": "internal",
    "payment": {
        "digitable_line": null,
        "qr_code_url": null,
        "qr_code_key": null,
        "bank_slip_key": null,
        "paid_method_type": "internal",
        "source_account_key": "5ae72355-1e47-4624-9915-ceb93d872194",
        "payment_data": {
            "target_account_key": "6108dd45-580d-48c4-b3bb-74c1e843be49",
            "transaction_amount": 50.00
        }
    },
    "proposal_due_date": "2026-04-13",
    "reference_date": "2026-04-13",
    "devolution_amount": 0,
    "request_control_key": "94b31045-c8e7-45be-a88d-2ae25c5df5db"
}

Response details

Field	Type	Description
proposal_key	string	Unique proposal key (UUID). Use it for queries and webhook correlation.
proposal_status	string	Proposal state. Starts at pending_payment; moves to paid once the internal debit settles.
affected_installments	array	Installments that received the refund. Shows the split of paid_amount across principal, interest and fine.
remaining_installments	array	Installments that remain open after the refund. Empty in full_settle.
payment.payment_data.target_account_key	string	Destination account of the internal debit.
payment.payment_data.transaction_amount	float	Amount actually debited from account_key.
devolution_amount	float	Overpayment returned to the fund. Non-zero only when a prior payment plus this refund exceeds the outstanding balance.
request_control_key	string	Echo of the idempotency key sent in the request.

Settlement webhook

When a refund settles the operation in full — typically full_settle, also possible when stacked equal_amount proposals zero the balance — QI Tech sends a webhook_type: debt with status: settled. Use it to confirm settlement asynchronously.

Renegotiation — Cancel proposal

Overview

DELETE /renegotiation/proposal/{proposal_key} cancels a proposal that has not been finalized. Only proposals with proposal_status: "pending_payment" are cancellable. Any associated payment method (bank slip, Pix) is invalidated.

Request

ENDPOINT

/renegotiation/proposal/{proposal_key}

METHOD

DELETE

Path params

Field	Type	Description	Max length
proposal_key *	string	Proposal key returned on POST /renegotiation/proposal.	UUID

Response

STATUS

200

Example response body

{
    "proposal_key": "bcc16a6d-ce21-4cd4-8d8c-d26f89ccc685",
    "proposal_status": "canceled",
    "request_control_key": "94b31045-c8e7-45be-a88d-2ae25c5df5db"
}

Query proposal status

After creating the proposal, you can poll its status by request_control_key.

ENDPOINT

/renegotiation/proposal/request_control_key/REQUEST-CONTROL-KEY

METHOD

GET

The response follows the same format as the POST /renegotiation/proposal body. proposal_status indicates the progress:

Status	Description
pending_payment	Proposal created, awaiting internal debit processing.
paid	Debit processed. In full_settle, the operation is already settled.
canceled	Proposal canceled via DELETE /renegotiation/proposal/{proposal_key}.

---

Batch renegotiation

For scenarios where you need to renegotiate multiple operations of the same issuer in one shot — generating a single payment method (bank slip and/or Pix) covering the whole batch — use the batch endpoints.

Attention

• Batch renegotiation can only include operations from the same issuer and the same integration key.
• Limit of 50 operations per batch.
• Batch endpoints support a different set of amortization types: installment_payment, overdue_installment_payment, present_amount. equal_amount and full_settle are not available on batch.

Renegotiation — Batch simulation

Overview

Before creating a batch proposal, simulate the values. The simulation returns affected installments, discounts and the total amount due across all operations.

For present_amount on simulation, each installments[] entry contains only installment_key. Per-installment paid_amount and discount_amount are required only on the batch proposal endpoint.

Request

ENDPOINT

/renegotiation/batch_proposal_simulation

METHOD

POST

Test in Playground

Warning

At the root, discount_amount and discount_percentage are mutually exclusive.

Request Body

{
   "amortization_type": "installment_payment",
   "reference_date": "2026-04-08",
   "operations": [
      {
         "debt_key": "1baea8a0-0fca-4f7c-8857-a227d4da72f8",
         "installments": [
            { "installment_key": "ca5741c7-99a2-42e7-92a1-9328a36e4e88" }
         ]
      },
      {
         "debt_key": "2cbfb9b1-1fdb-5f8d-9967-b338e5eb83f9",
         "installments": [
            { "installment_key": "2ef25ed8-7124-44f5-9e3d-1d1a7196166e" }
         ]
      }
   ]
}

Body parameters

Field	Type	Description	Max length
amortization_type *	string	Batch amortization type	Batch amortization type values
operations *	array	Operations to renegotiate	Operations object
reference_date	string	Reference date for present-value calculation (YYYY-MM-DD).	10
discount_percentage	float	Optional discount percentage over present value (root level, global).	-
discount_amount	float	Optional discount amount over present value (root level, global).	-

Operations object

Field	Type	Description	Max length
debt_key *	string	Unique credit operation key (DEBT-KEY)	UUID
installments *	array	Installments to renegotiate	Installments object

Installments object

Field	Type	Description	Max length
installment_key *	string	Installment key	UUID

Batch amortization type values

Value	Description
installment_payment	Pay specific installments. Each installments[] entry contains only installment_key.
overdue_installment_payment	Pay overdue installments. Same shape as installment_payment.
present_amount	Present value per installment. On simulation, send only installment_key. On the proposal endpoint, also send paid_amount and discount_amount.

Response

STATUS

200

Example response body

{
   "batch_proposal_key": "429fd784-e13e-47a1-ad9f-291209e0e621",
   "amortization_type": "installment_payment",
   "payment_amount": 78389.55,
   "discount_percentage": 0,
   "discount_amount": 0,
   "requester_name": "Castello (BNPL)",
   "requester_key": "3e69b448-9afb-4aef-9c0d-0a3059350d80",
   "issuer_name": "Alan Mathison Turing",
   "issuer_document_number": "82744088021",
   "reference_date": "2026-04-08",
   "operations": [
      {
         "requester_key": "3e69b448-9afb-4aef-9c0d-0a3059350d80",
         "contract_number": "TEST00790",
         "payment_amount": 78389.55,
         "discount_amount": 0,
         "affected_installments": [
            {
               "installment_key": "24b5deae-304e-4773-9b25-e42dbd450241",
               "due_date": "2026-05-10",
               "principal_amount": 73107.75,
               "interest_amount": 10580.11,
               "fine_amount": 0,
               "total_amount": 83687.87,
               "present_amount": 78389.55,
               "paid_amount": 78389.55,
               "principal_amortization_payment_amount": 78048.30,
               "prefixed_interest_payment_amount": 341.25,
               "fine_payment_amount": 0,
               "discount_amount": 0
            }
         ],
         "remaining_installments": [
            {
               "installment_key": "2b1d9423-4dab-44b3-bf8c-efc8433176dd",
               "due_date": "2026-06-10",
               "principal_amount": 73096.23,
               "interest_amount": 10591.64,
               "fine_amount": 0,
               "total_amount": 83687.87
            }
         ],
         "debt_key": "388c47fa-6c6c-4d2b-8f00-ccc2d571fcb0"
      }
   ]
}

Renegotiation — Batch proposal

Overview

After simulating the values, create the batch renegotiation proposal. The proposal generates a single payment method (bank slip and/or Pix) covering all operations in the batch.

For amortization_type: present_amount, each entry in operations[].installments[] must include paid_amount and discount_amount (in addition to installment_key). For installment_payment / overdue_installment_payment, only installment_key is required.

Request

ENDPOINT

/renegotiation/batch_proposal

METHOD

POST

Test in Playground

Request Body

installment_payment

{
   "amortization_type": "installment_payment",
   "reference_date": "2026-04-08",
   "proposal_due_date": "2026-04-15",
   "payment_type": "pix",
   "request_control_key": "94b31045-c8e7-45be-a88d-2ae25c5df5db",
   "operations": [
      {
         "debt_key": "1baea8a0-0fca-4f7c-8857-a227d4da72f8",
         "installments": [
            { "installment_key": "ca5741c7-99a2-42e7-92a1-9328a36e4e88" }
         ]
      },
      {
         "debt_key": "2cbfb9b1-1fdb-5f8d-9967-b338e5eb83f9",
         "installments": [
            { "installment_key": "2ef25ed8-7124-44f5-9e3d-1d1a7196166e" }
         ]
      }
   ]
}

present_amount

{
   "amortization_type": "present_amount",
   "reference_date": "2026-04-08",
   "proposal_due_date": "2026-04-15",
   "payment_type": "pix",
   "request_control_key": "94b31045-c8e7-45be-a88d-2ae25c5df5db",
   "operations": [
      {
         "debt_key": "1baea8a0-0fca-4f7c-8857-a227d4da72f8",
         "installments": [
            { "installment_key": "ca5741c7-99a2-42e7-92a1-9328a36e4e88", "paid_amount": 500, "discount_amount": 50 }
         ]
      },
      {
         "debt_key": "2cbfb9b1-1fdb-5f8d-9967-b338e5eb83f9",
         "installments": [
            { "installment_key": "2ef25ed8-7124-44f5-9e3d-1d1a7196166e", "paid_amount": 150, "discount_amount": 10 }
         ]
      }
   ]
}

Body parameters

Field	Type	Description	Max length
amortization_type *	string	Batch amortization type	Batch amortization type values
payment_type *	string	Batch payment type	Batch payment type values
operations *	array	Operations to renegotiate	Operations object
proposal_due_date *	string	Proposal due date (YYYY-MM-DD)	10
reference_date *	string	Reference date (YYYY-MM-DD)	10
request_control_key	string	Client-side idempotency key for tracking and cancellation. Required for cancellation by request_control_key.	50
discount_percentage	float	Optional global discount percentage on present value.	-
discount_amount	float	Optional global discount amount on present value.	-
payer_document_number	string	Payer CNPJ (digits only).	14
payer_name	string	Payer name. Required when payer_document_number is sent.	200

Operations object

Field	Type	Description	Max length
debt_key *	string	Unique credit operation key (DEBT-KEY)	UUID
installments *	array	Installments to renegotiate	Installments object

Installments object

Field	Type	Description	Max length
installment_key *	string	Installment key	UUID
paid_amount	float	Amount paid/allocated to the installment (BRL). Required when amortization_type is present_amount.	15,2
discount_amount	float	Discount in BRL applied to the installment. Required when amortization_type is present_amount (use 0 if none).	15,2

Batch payment type values

Value	Description
bank_slip	Bank slip (also generates Pix).
pix	Pix only.
manual	Manual payment (no payment method generated).

Batch amortization type values

Value	Description
installment_payment	Pay specific installments — each entry under operations[].installments[] requires installment_key only.
overdue_installment_payment	Pay overdue installments — same shape as installment_payment.
present_amount	Present value per installment — each entry requires installment_key, paid_amount, discount_amount.

Response

STATUS

201

Example response body

{
   "batch_proposal_key": "37879d40-c16e-4d7f-a16f-d79d20c50d42",
   "amortization_type": "installment_payment",
   "payment_amount": 78206.27,
   "discount_percentage": 0,
   "discount_amount": 0,
   "requester_name": "Castello (BNPL)",
   "requester_key": "3e69b448-9afb-4aef-9c0d-0a3059350d80",
   "issuer_name": "Alan Mathison Turing",
   "issuer_document_number": "82744088021",
   "reference_date": "2026-04-08",
   "proposal_due_date": "2026-04-15",
   "payment_type": "pix",
   "batch_proposal_status": "pending_payment",
   "request_control_key": "94b31045-c8e7-45be-a88d-2ae25c5df5db",
   "operations": [
      {
         "requester_key": "3e69b448-9afb-4aef-9c0d-0a3059350d80",
         "contract_number": "TEST1570594223",
         "payment_amount": 78206.27,
         "debt_key": "6564493d-75c3-4efe-9f11-82fa5cff9a78",
         "affected_installments": [
            {
               "installment_key": "1162e382-8bd6-4c0b-9111-8390d9794102",
               "due_date": "2026-05-10",
               "principal_amount": 73277.29,
               "interest_amount": 10214.91,
               "fine_amount": 0,
               "total_amount": 83492.20,
               "present_amount": 78206.27,
               "paid_amount": 78206.27,
               "principal_amortization_payment_amount": 78206.27,
               "prefixed_interest_payment_amount": 0,
               "fine_payment_amount": 0,
               "discount_amount": 0
            }
         ],
         "remaining_installments": [
            {
               "installment_key": "58eea645-5682-440d-aa6b-a3b124253684",
               "due_date": "2026-06-10",
               "principal_amount": 72925.33,
               "interest_amount": 10566.87,
               "fine_amount": 0,
               "total_amount": 83492.20
            }
         ]
      }
   ],
   "payment": {
      "digitable_line": null,
      "qr_code_url": "00020126930014br.gov.bcb.pix2571qrcode-h.sandbox.qitech.app/bacen/cobv/426661142f5d4cd9954dcae3725d020d5204000053039865802BR5925QISOCIEDADEDECREDITODIRET6008SaoPaulo61080145200062070503***6304B878",
      "qr_code_key": "42666114-2f5d-4cd9-954d-cae3725d020d",
      "bank_slip_key": null,
      "paid_method_type": "pix",
      "source_account_key": null,
      "payment_data": {
         "creditor_bank_account_key": "6108dd45-580d-48c4-b3bb-74c1e843be49",
         "batch_renegotiation_proposal_key": "37879d40-c16e-4d7f-a16f-d79d20c50d42"
      }
   }
}

Renegotiation — Cancel batch proposal

Overview

Cancels a batch proposal still in a cancellable state. Only proposals with batch_proposal_status: "pending_payment" are cancellable. Any associated payment method (bank slip, Pix) is invalidated.

Two routes are available:

• By batch_proposal_key (UUID returned on POST /renegotiation/batch_proposal)
• By request_control_key (idempotency key sent on creation) — useful when the client tracks operations by its own key

Cancel by batch_proposal_key

ENDPOINT

/renegotiation/batch_proposal/{batch_proposal_key}

METHOD

DELETE

Path params

Field	Type	Description	Max length
batch_proposal_key *	string	Batch proposal key returned on POST /renegotiation/batch_proposal.	UUID

Cancel by request_control_key

ENDPOINT

/renegotiation/batch_proposal/request_control_key/{request_control_key}

METHOD

DELETE

Path params

Field	Type	Description	Max length
request_control_key *	string	Idempotency key sent on POST /renegotiation/batch_proposal.	50

Response

Both routes return the same response.

STATUS

204