Skip to main content

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_payload": "00020101021226850014br.gov.bcb.pix2563qrcodepix.bb.com.br/pix/v2/d373e385-dfe7-49f6-b9ec-14ba60a9b8285204000053039865802BR5925TESTE62070503***63047B7D"
}
FieldTypeDescriptionMax length
qr_code_payload *stringEMV payload of the Pix QR Code (copy-and-paste).340

Response Body​

The response returns the decoded fields under a nested qr_code_data object. The content varies by QR Code type — select the matching tab.

{
   "qr_code_type": "static",
   "qr_code_payload": "00020126580014br.gov.bcb.pix0136a23bf0e9-5175-4829-bf89-e8fe6ac09aa1520400005303986540530.005802BR5914TywinLannister6008saopaulo62070503***6304D4FD",
   "qr_code_data": {
      "target_pix_key": "a23bf0e9-5175-4829-bf89-e8fe6ac09aa1",
      "amount": "30.00",
      "receiver_conciliation_id": "***",
      "additional_data": [],
      "category_code": "0000",
      "city": "saopaulo",
      "postal_code": null,
      "reusable_qrcode": "no"
   }
}
Static QR Code — unavailable fields

Per the BR Code specification, static QR Codes do not carry expected payer data, expiration date, fines, interest, discounts, or reductions. Those fields exist only on dynamic QR Codes.

Also, qr_code_data.amount may come as null on static QR Codes when the merchant issued an "open-amount" QR — the payer defines the value at payment time.

Response fields​

FieldTypeDescriptionPresent in
qr_code_typestringQR Code type: static, dynamic_instant, or dynamic_term.All
qr_code_payloadstringOriginal EMV payload sent in the request.All
qr_code_data.target_pix_keystringRecipient's Pix key.All
qr_code_data.amountstring/decimalCharge amount. In dynamic_term, the final amount (after fine/interest/discount/reduction). In static, may be null.All
qr_code_data.receiver_conciliation_idstringRecipient's reconciliation identifier (txid).All
qr_code_data.additional_dataarrayList of additional information {name, value}.All
qr_code_data.category_codestringMerchant category code (MCC).All
qr_code_data.citystringRecipient's city.All
qr_code_data.postal_codestringRecipient's postal code.All
qr_code_data.reusable_qrcodestringyes if the QR can be paid multiple times, no otherwise.All
qr_code_data.receiver_urlstringRecipient PSP URL (loc field of the BR Code).dynamic_*
qr_code_data.statusstringCharge status — see enumerators below.dynamic_*
qr_code_data.revisionintegerCurrent charge version.dynamic_*
qr_code_data.created_atstring ISOCharge creation date at the recipient PSP.dynamic_*
qr_code_data.presented_atstring ISOCharge presentation date to the payer.dynamic_*
qr_code_data.question_to_payerstringMessage from recipient to the payer (solicitacaoPagador).dynamic_*
qr_code_data.payer_namestringExpected payer's name, when informed by the recipient.dynamic_*
qr_code_data.payer_document_numberstringExpected payer's CPF/CNPJ.dynamic_*
qr_code_data.payer_person_typestringnatural or legal.dynamic_*
qr_code_data.target_namestringRecipient's name.dynamic_*
qr_code_data.expiration_secondsintegerQR validity in seconds from created_at.dynamic_instant
qr_code_data.can_changestringyes if the payer can change the amount, no otherwise.dynamic_instant
qr_code_data.original_amountstring/decimalOriginal charge amount before fine/interest/discount.dynamic_term
qr_code_data.due_datestring (date)Charge due date.dynamic_term
qr_code_data.days_after_due_acceptedintegerDays after due date during which payment is still accepted.dynamic_term
qr_code_data.fine_amountstring/decimalFine applied after the due date.dynamic_term
qr_code_data.fee_amountstring/decimalInterest applied after the due date.dynamic_term
qr_code_data.discount_amountstring/decimalDiscount granted before the due date.dynamic_term
qr_code_data.reduction_amountstring/decimalReduction applied to the charge.dynamic_term
qr_code_data.target_trading_namestringRecipient's trade name.dynamic_term
qr_code_data.addressstringRecipient's street address.dynamic_term
qr_code_data.statestringRecipient's state.dynamic_term

Status enumerators (dynamic QR Code)​

ValueDescription
ATIVACharge available, no payment yet.
CONCLUIDACharge paid and finalized.
REMOVIDA_PELO_USUARIO_RECEBEDORRemoved by the recipient user.
REMOVIDA_PELO_PSPRemoved by the recipient bank.

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​

FieldTypeDescriptionMax chars
additional_data *objectContract metadata and signature evidence under additional_data.contract (contract number, signed flag, signatures[] with signer and evidence).-
borrower *objectBorrower object — Natural person taking out the credit operation.-
disbursement_bank_accounts *arrayDisbursement bank accounts — array containing the QR Code that receives the disbursement (single item in this flow).-
financial *objectFinancial object — Financial terms; use disbursed_amount for the cash payout to the borrower.-
purchaser_document_number *stringAssignee (purchaser) CNPJ (digits only, no formatting).-
requester_identifier_keystringClient tracking key for the request.50
document_template_keystringKey of the contract template to be used for the operation.UUID

Borrower object​

FieldTypeDescriptionMax chars
name *stringBorrower full name100
emailstringBorrower email254
phoneobjectPhone object — Contact phone-
is_pep *booleanPEP indicator (http://www.portaldatransparencia.gov.br/download-de-dados/pep)-
address *objectAddress object — Borrower address-
role_typeenumBorrower role in the contract. Default: issuer.-
birth_date *dateBorrower birth date (YYYY-MM-DD)-
mother_name *stringMother's full name100
nationalitystringNationality50
professionstringBorrower profession100
person_type *stringPerson type — must be natural for individuals-
individual_document_number *stringBorrower CPF (digits only)11
document_identification *stringDOCUMENT_KEY of the borrower's photo ID PDF (RG or CNH), uploaded beforehandUUID
document_identification_backstringDOCUMENT_KEY of the back of the photo ID (uploaded beforehand)UUID
document_identification_numberstringBorrower ID document number (RG or CNH), digits only20

Address object​

FieldTypeDescriptionMax chars
city *stringCity100
state *stringState (two uppercase letters)2
number *stringStreet number10
street *stringStreet name100
complement *stringAddress complement (free text)100
postal_code *stringPostal code (https://www.buscacep.correios.com.br/)8
neighborhood *stringNeighborhood100

Phone object​

FieldTypeDescriptionMax chars
number *stringPhone number10
area_code *stringArea code (https://ddd.guiamais.com.br/)2
country_code *stringCountry 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:

FieldTypeDescriptionMax chars
qr_code_url *stringEMV 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.

Recipient data filled in the response

When issuing with qr_code_url, QI Tech decodes the QR Code and automatically fills the recipient's data in the disbursement_account of the response/webhook:

  • name: recipient's full name (always in clear text, no masking).
  • document_number: recipient's document — CPF (11 digits) is returned masked as ***XXXXXX**; CNPJ (14 digits) is returned in full, without masking.
  • ispb / financial_institutions / financial_institutions_code_number: recipient's financial institution.
  • pix_key, receiver_conciliation_id, end_to_end_id, amount_receivable: extracted from the decoded QR Code.

The account_branch, account_number, and account_digit fields remain null for dynamic QR Codes, since those values are not encoded in the EMV.

Financial object​

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

FieldTypeDescriptionMax chars
disbursed_amount *floatCash payout disbursed to the borrower (principal of the credit operation)-
interest_typeenumInterest type — Amortization and interest calculation-
credit_operation_typeenumCredit operation type — Agreement type-
monthly_interest_ratefloatMonthly prefixed interest rate as a decimal-
disbursement_datedateDisbursement date (YYYY-MM-DD)-
first_due_datedateFirst installment due date (YYYY-MM-DD)-
interest_grace_periodintInterest grace period (months)-
principal_grace_periodintPrincipal grace period-
number_of_installmentsintNumber of installments-
fine_configurationobjectFine configuration — Late interest and penalty-

Fine configuration object​

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

FieldTypeDescriptionMax chars
contract_fine_ratefloatLate penalty rate-
interest_baseenumInterest base — Interest calculation basis-
monthly_ratefloatMonthly late interest rate-

Enumerators​

Person type​

ValueDescription
naturalNatural person
legalLegal entity

Account type​

ValueDescription
checking_accountChecking account
deposit_accountDeposit account
guaranteed_accountGuaranteed account
investment_accountInvestment account
payment_accountPayment account
saving_accountSavings account
salary_accountSalary account

Interest type​

ValueDescription
pre_price_daysPrice method (equal installments) with daily prefixed interest
pre_pricePrice method (equal installments) with prefixed interest in fixed 30-day periods
pre_sacSAC (constant amortization) with daily prefixed interest
post_sacSAC with prefixed rate plus post-fixed index (CDI, IPCA, or IGP-M), daily
post_pricePrice method with prefixed rate plus post-fixed index in fixed 30-day periods
post_price_daysPrice method with prefixed rate plus post-fixed index, daily

Credit operation type​

ValueDescription
ccbBank credit note (Cédula de Crédito Bancário)
cceExport credit note (Cédula de Crédito à Exportação)
nceExport credit note (Nota de Crédito à Exportação)
BNPL

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

Interest base​

ValueDescription
workdaysBusiness days, 252-day year
calendar_daysCalendar days, 360-day year
calendar_days_365Calendar 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
{
   "webhook_type": "debt",
   "key": "4e1ed268-9f29-44ce-9991-3bdf036aeacd",
   "status": "issued",
   "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": [
         {
            "due_date": "2026-05-10",
            "due_principal": 151131.6,
            "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
         },
         {
            "due_date": "2026-06-10",
            "due_principal": 77854.31484159,
            "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
         }
      ],
      "total_pre_fixed_amount": 15852.8,
      "disbursement_account": [
         {
            "name": "Logcard Meios De Pagamento Ltda",
            "document_number": "18236120000158",
            "pix_key": "d6e2d611-6c68-4f84-9be5-962ad2f2bcb6",
            "qr_code_key": null,
            "qr_code_url": "00020126930014br.gov.bcb.pix2571qrcode-h.sandbox.qitech.app/bacen/cobv/3fecc731adf542659b84be038ec4151e5204000053039865802BR5925LogcardMeiosDePagamentoLt6008SaoPaulo61080145200062070503***6304A936",
            "account_branch": null,
            "account_number": null,
            "account_digit": null,
            "account_type": "checking_account",
            "ispb": "18236120",
            "percentage_receivable": 100,
            "amount_receivable": 150000,
            "end_to_end_id": "E32402502202606270040dNdgaZPUHxT"
         }
      ]
   }
}

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,
      "disbursement_account": [
         {
            "name": "Logcard Meios De Pagamento Ltda",
            "document_number": "18236120000158",
            "pix_key": "d6e2d611-6c68-4f84-9be5-962ad2f2bcb6",
            "qr_code_key": null,
            "qr_code_url": "00020126930014br.gov.bcb.pix2571qrcode-h.sandbox.qitech.app/bacen/cobv/3fecc731adf542659b84be038ec4151e5204000053039865802BR5925LogcardMeiosDePagamentoLt6008SaoPaulo61080145200062070503***6304A936",
            "account_branch": null,
            "account_number": null,
            "account_digit": null,
            "account_type": "checking_account",
            "ispb": "18236120",
            "percentage_receivable": 100,
            "amount_receivable": 150000,
            "end_to_end_id": "E32402502202606270040dNdgaZPUHxT"
         }
      ]
   }
}

Cancellation Webhook​

If the debt fails to disburse, or is returned, you will receive a cancellation webhook.

WEBHOOK_TYPE
debt
STATUS
canceled
Webhook Body
{
    "webhook_type": "debt",
    "key": "1ebd4a90-2721-4c39-a399-427fa16bca65",
    "event_datetime": "2025-10-27T16:38:59Z",
    "data": {
        "cancel_reason": "Operacao cancelada manualmente",
        "cancel_reason_enumerator": "manual"
    },
    "status": "canceled"
}

Cancellation Webhook Fields​

FieldTypeDescription
keystringUnique debt key (DEBT-KEY)
statusstringEvent status: canceled
webhook_typestringWebhook type: debt
event_datetimestringEvent date and time
data.cancel_reasonstringTextual description of the cancellation reason
data.cancel_reason_enumeratorstringCancellation reason enumerator

Cancellation Enumerators​

EnumeratorDescription
disbursing_errorOperation canceled due to an error during disbursement
waiting_signatureOperation canceled due to missing signature
pix_max_retryOperation canceled because the receiving bank could not process the disbursement
manualOperation canceled manually
agencia_conta_invalidaInvalid agency or recipient account number
invalid_accountThe destination account number is nonexistent or invalid
invalid_document_numberThe CPF/CNPJ of the destination account is incorrect
unsupported_transactionThe destination account does not support this type of transaction
invalid_ispbThe ISPB number is invalid or nonexistent
rejected_paymentPayment order was rejected by the receiving bank
refund_after_payee_requestRefund requested by the payee
blocked_accountThe destination account is blocked
amount_too_greatPayment/refund amount exceeds the limit for the credited destination account
receiver_errorTransaction interrupted due to error on the receiver's PSP
closed_accountThe destination account is closed
disbursing_hour_closedDisbursement occurred outside of the allowed time frame
unregistered_pix_keyThe Pix key is not registered
spi_timeoutTimeout control in SPI

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​

FieldTypeDescriptionMax chars
requester_identifier_key *stringClient tracking key sent on debt issuance50
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​

FieldTypeDescription
calendar_daysintegerNumber of calendar days between installments
due_datestringInstallment due date in calendar days
due_principalfloatRemaining principal on the installment due date before its payment
has_interestbooleanIf true, interest applies to the installment
installment_numberintegerInstallment number
pre_fixed_amountfloatFixed interest amount paid on the installment
principal_amortization_amountfloatPrincipal amount paid on the installment
tax_amountfloatBase IOF amount of installment
total_amountfloatInstallment total value
due_interestfloatRemaining interest after the installment due date before its payment
workdaysintegerBusiness days between installments

Interest rate object​

FieldDescription
annual_rateAnnual fixed/floating interest rate expressed as a decimal
daily_rateDaily fixed/floating interest rate expressed as a decimal
interest_baseInterest base — Interest calculation basis
monthly_rateMonthly fixed/floating interest rate expressed as a decimal

Tax configuration object​

FieldDescription
base_rateBase IOF rate value
additional_rateAdditional 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
{
    "debt_key": "72760166-4ddf-41fb-8a8c-605f8f4fc35c",
    "amortization_type": "equal_amount",
    "reference_date": "2026-04-13",
    "payment_amount": 50.00
}

Body parameters​

FieldTypeDescriptionMax length
debt_key *stringUnique credit operation key (DEBT-KEY)UUID
amortization_type *stringRefund modalityAmortization type values
payment_amount *floatRefund 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_datestringReference date used to compute the present value (YYYY-MM-DD). Cannot be earlier than the disbursement date.10
discount_percentagefloatOptional discount percentage over the present value. Cannot be sent together with discount_amount.-
discount_amountfloatOptional discount amount over the present value. Cannot be sent together with discount_percentage.-

Amortization type values​

ValueDescription
equal_amountPartial refund. payment_amount is distributed proportionally across the open installments; the operation remains active with remaining installments open.
full_settleFull 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
{
    "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"
}

Body parameters​

FieldTypeDescriptionMax length
debt_key *stringUnique credit operation key (DEBT-KEY)UUID
payment_type *stringFor refund flows, use internal.Payment type values
amortization_type *stringRefund modalityAmortization type values
payment_amount *floatRefund amount in BRL.15,2
account_key *stringInternal account key from which the value is debited.UUID
request_control_key *stringClient-side idempotency key. Use a unique value per attempt.50
reference_datestringReference date used to compute the present value (YYYY-MM-DD). Cannot be earlier than the disbursement date.10
discount_percentagefloatOptional discount percentage over the present value. Cannot be sent together with discount_amount.-
discount_amountfloatOptional discount amount over the present value. Cannot be sent together with discount_percentage.-

Payment type values​

ValueDescription
internalInternal debit from account_key (automatic, no bank slip or Pix). Used for refund flows.
bank_slipGenerates bank slip and Pix.
pixPix only.
manualManual payment (no payment method generated).

Amortization type values​

ValueDescription
equal_amountPartial refund. payment_amount is distributed proportionally across the open installments; the operation remains active with remaining installments open.
full_settleFull 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​

FieldTypeDescription
proposal_keystringUnique proposal key (UUID). Use it for queries and webhook correlation.
proposal_statusstringProposal state. Starts at pending_payment; moves to paid once the internal debit settles.
affected_installmentsarrayInstallments that received the refund. Shows the split of paid_amount across principal, interest and fine.
remaining_installmentsarrayInstallments that remain open after the refund. Empty in full_settle.
payment.payment_data.target_account_keystringDestination account of the internal debit.
payment.payment_data.transaction_amountfloatAmount actually debited from account_key.
devolution_amountfloatOverpayment returned to the fund. Non-zero only when a prior payment plus this refund exceeds the outstanding balance.
request_control_keystringEcho 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​

FieldTypeDescriptionMax length
proposal_key *stringProposal 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:

StatusDescription
pending_paymentProposal created, awaiting internal debit processing.
paidDebit processed. In full_settle, the operation is already settled.
canceledProposal 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​

FieldTypeDescriptionMax length
amortization_type *stringBatch amortization typeBatch amortization type values
operations *arrayOperations to renegotiateOperations object
reference_datestringReference date for present-value calculation (YYYY-MM-DD).10
discount_percentagefloatOptional discount percentage over present value (root level, global).-
discount_amountfloatOptional discount amount over present value (root level, global).-

Operations object​

FieldTypeDescriptionMax length
debt_key *stringUnique credit operation key (DEBT-KEY)UUID
installments *arrayInstallments to renegotiateInstallments object

Installments object​

FieldTypeDescriptionMax length
installment_key *stringInstallment keyUUID

Batch amortization type values​

ValueDescription
installment_paymentPay specific installments. Each installments[] entry contains only installment_key.
overdue_installment_paymentPay overdue installments. Same shape as installment_payment.
present_amountPresent 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
{
   "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" }
         ]
      }
   ]
}

Body parameters​

FieldTypeDescriptionMax length
amortization_type *stringBatch amortization typeBatch amortization type values
payment_type *stringBatch payment typeBatch payment type values
operations *arrayOperations to renegotiateOperations object
proposal_due_date *stringProposal due date (YYYY-MM-DD)10
reference_date *stringReference date (YYYY-MM-DD)10
request_control_keystringClient-side idempotency key for tracking and cancellation. Required for cancellation by request_control_key.50
discount_percentagefloatOptional global discount percentage on present value.-
discount_amountfloatOptional global discount amount on present value.-
payer_document_numberstringPayer CNPJ (digits only).14
payer_namestringPayer name. Required when payer_document_number is sent.200

Operations object​

FieldTypeDescriptionMax length
debt_key *stringUnique credit operation key (DEBT-KEY)UUID
installments *arrayInstallments to renegotiateInstallments object

Installments object​

FieldTypeDescriptionMax length
installment_key *stringInstallment keyUUID
paid_amountfloatAmount paid/allocated to the installment (BRL). Required when amortization_type is present_amount.15,2
discount_amountfloatDiscount in BRL applied to the installment. Required when amortization_type is present_amount (use 0 if none).15,2

Batch payment type values​

ValueDescription
bank_slipBank slip (also generates Pix).
pixPix only.
manualManual payment (no payment method generated).

Batch amortization type values​

ValueDescription
installment_paymentPay specific installments — each entry under operations[].installments[] requires installment_key only.
overdue_installment_paymentPay overdue installments — same shape as installment_payment.
present_amountPresent 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​

FieldTypeDescriptionMax length
batch_proposal_key *stringBatch 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​

FieldTypeDescriptionMax length
request_control_key *stringIdempotency key sent on POST /renegotiation/batch_proposal.50

Response​

Both routes return the same response.

STATUS
204

Simulate the PIX Chargeback (CNPJ) Flow — Sandbox Runbook

Audience: clients driving the full pix-parcelado merchant-chargeback flow end-to-end in sandbox, through the gandalf gateway (https://api-auth.sandbox.qitech.app).

This is the hands-on companion to client-chargeback-renegotiation.md. That guide explains the semantics (what each webhook and field means). This one is the runbook: the exact calls you make, in order, to produce and settle a hold yourself.

You will:

  1. Get your opened credit operation (CO) — the CNPJ disbursement you'll charge back.
  2. Trigger a chargeback, which fires the refund webhook and parks a pending_requester_action hold.
  3. Read the hold, then call renegotiation to act on it.
  4. Confirm the hold settles.

All calls go through your gandalf integration (signed requests).

0. Before you start — prerequisites​

QI configures these per-account; confirm they're in place before you begin (see client-chargeback-renegotiation.md §2):

  • Your transitory account is onboarded with a chargeback account and gated for issuer-document conciliation.
  • Your callback endpoint is registered for laas.transitory_conciliation.refund. Without it, the webhook is silently dropped.

Reference keys used in the examples below (swap in your own):

account_key           (transitory)  1b50f04e-8f90-4b89-8604-22eee1b2755f
chargeback_account_key               6268e5a7-4998-44ed-b128-9639fef0c678
CNPJ (merchant / disbursement)       62244815000173

Step 1 — Get your opened CO​

Create (or reuse) a signed CNPJ consumer-loan disbursement. The disbursement PIX targets the merchant CNPJ; its credit_operation_key is the CO you'll charge back.

POST /debt                       # disbursement_document_number = 62244815000173 (CNPJ)
POST /debt/{credit_operation_key}/signed

Disbursement is async — wait for the CO to reach opened. Record the credit_operation_key; that's the only identifier the rest of the flow needs (the chargeback resolves the outgoing PIX and the transitory account from it server-side).

Step 2 — Trigger the chargeback (fires the refund webhook)​

Mint a merchant chargeback against the original outgoing PIX. This credits the transitory account and — because the account is gated — parks a pending_requester_action hold and fires your laas.transitory_conciliation.refund webhook.

Endpoint:

POST /mock/transitory_conciliation/incoming_pix_chargeback
curl -X POST "https://api-auth.sandbox.qitech.app/mock/transitory_conciliation/incoming_pix_chargeback" \
  -H "Content-Type: application/json" \
  <your gandalf signed-request headers> \
  -d '{
    "credit_operation_key": "9aeaa029-eec8-4bea-bf81-367ad0dfd1ee",
    "amount": 50.0
  }'

Fields:

FieldRequiredNotes
credit_operation_keyyesyour opened CO (36 chars). The mock resolves the outgoing PIX end_to_end_id and the transitory account from it.
amountyesmust be < disbursed amount (partial). A full-amount chargeback within 7 days auto-reverses instead of holding.
payer_document_numbernothe CNPJ — 14 digits. Defaults to the merchant CNPJ on the CO if omitted.
pix_messagenofree text.

Response: 201. Fails 400 MOC000008 if the CO has no settled PIX disbursement to charge back.

Why partial matters: the hold path triggers when the chargeback is partial or lands >7 calendar days after the original disbursement. A same-amount chargeback ≤7 days takes the auto-reversal path (pending_reversal → finished) and never becomes a pending_requester_action hold — so there's nothing for renegotiation to act on.

Step 3 — Read the hold​

The webhook payload (data.callback.data) carries everything you need — the callback key is the transitory_conciliation_key, and origin_key is the credit_operation_key. Take both straight from the payload.

To poll instead of waiting on the webhook:

GET /transitory_conciliation/credit_operation_key/{credit_operation_key}?status=pending_requester_action

Returns the hold DTO (transitory_conciliation_key, amount, credit_operation_key, chargeback_account_key, document_number, transitory_conciliation_status, …).

Record transitory_conciliation_key and credit_operation_key for Step 4.

Step 4 — Act on the hold via renegotiation​

Create a renegotiation proposal against the held CO. Reneg validates the keys against the hold (source of truth), creates the proposal at pending_payment, then auto-liquidates by moving the held funds from the chargeback account.

Endpoint:

POST /renegotiation/proposal
{
  "transitory_conciliation_key": "<from Step 3>",
  "debt_key": "<credit_operation_key from Step 3>",
  "amortization_type": "full_settle",
  "reference_date": "2026-07-22",
  "request_control_key": "<your idempotency key>"
}

Rules (enforced server-side):

  • Only these fields are accepted. Sending payment_type / account_key / payment_amount → 400 RN0000064. Amount and source account come from the hold, not you.
  • amortization_type must be full_settle or equal_amount → else 400 RN0000063.
  • debt_key must equal the hold's credit_operation_key → else 400 RN0000061.
  • One active proposal per hold → else 409 RN0000062.

Success: 201, proposal_status = pending_payment.

See client-chargeback-renegotiation.md §3 for the full error table and the migration-path (no-key) payload variant.

Step 5 — Confirm settlement​

Once the proposal pays, QI settles the hold: pending_requester_action → finished (resolution renegotiation). Verify with the event history:

GET /transitory_conciliation/{transitory_conciliation_key}/events

You should see the finishing event with resolution_type = renegotiation and external_key = the proposal key. If you consume proposal webhooks, you also receive the paid callback.

Flow at a glance​

Step 1  POST /debt (+ /signed)                  → opened CO (credit_operation_key)
Step 2  POST /mock/.../incoming_pix_chargeback  → {credit_operation_key, amount} → hold + refund webhook
Step 3  (webhook payload) or GET .../credit_operation_key/{k}?status=pending_requester_action
Step 4  POST /renegotiation/proposal            → proposal pending_payment → auto-liquidates
Step 5  hold → finished (resolution renegotiation)

Validated end-to-end in sandbox (2026-07-22): CO 9aeaa029… → chargeback {credit_operation_key, amount:50} → hold d5e4d0a1… pending_requester_action → proposal ed30395e… → hold finished (resolution renegotiation).

Reference​

ThingValue
Sandbox gateway (gandalf)https://api-auth.sandbox.qitech.app
Chargeback triggerPOST /mock/transitory_conciliation/incoming_pix_chargeback
Refund webhook eventlaas.transitory_conciliation.refund
Read holdGET /transitory_conciliation/credit_operation_key/{key}?status=pending_requester_action
Renegotiation actionPOST /renegotiation/proposal
Allowed amortizationsfull_settle, equal_amount
Hold status enumpending_requester_action → finished