Homologation Roadmap - BNPL

Summary

The objective of this document is to guide all clients through the integration process of Buy Now Pay Later (BNPL) with QI Tech's platform.

This document outlines the key steps involved and addresses potential questions. For further details, please refer to the full documentation provided in item 10.

1. Document upload

To receive the document_key for the debt issuance documents, you must upload them using the following request:

Request Body Upload

ENDPOINT

/upload

MÉTODO

POST

Response Body

{
  "document_key": "cfbc8469-89ea-4a80-9f64-ba7b1566c68b",
  "document_md5": "cd451103fa512frc98ce684d3896698c"
}

Atenção

Lembrar de salvar a document_key, chave essa necessária para a consulta do documento.

Exemplo de chamada

Exemplo para upload de uma imagem a partir de uma URL.

Python
Node.js

import jwt
import hashlib
import requests
from requests_toolbelt.multipart.encoder import MultipartEncoder
import json
from datetime import datetime

BASE_URL = "https://api-auth.sandbox.qitech.app"
API_KEY = "4c268c0a-53ff-429b-92b6-47ef98a6d89a" # Esta chave é um exemplo, por favor utilize sua própria chave
CLIENT_PRIVATE_KEY = ''''
-----BEGIN EC PRIVATE KEY-----
MIHbAgEBBEHh1hIeOPE5XNNhn6bxRAmVswsPZ0wZCmzVvP8Tl/LZK9ofVmRVGzll
srU1uezJEyHKYdOHrE2p52xUj+pHzjJvb6AHBgUrgQQAI6GBiQOBhgAEAAofUz1J
hBSOyGHLsnV9Sz0DSWmhl7U+ljqbfa8PKVFWSV3w16I1v2zME5/UzUhHn1gWsjnv
7/ekcLLAQbvqMPNXAfjIhFXLAPzqbB9iCuVua1v0Vgy52rBemOWrJka/Ws2bnKR8
h1N1OxOYeYr6C2jqMygBLktKMAs+282CEiEb4bIv
-----END EC PRIVATE KEY----- 
''' # Esta chave é um exemplo, por favor utilize sua própria chave

def get_document(url):
    try:
        response = requests.get(url)
        return response.content
    except Exception as error:
        print("Error fetching document:", error)
        raise

def upload_document(array_buffer):
    endpoint = "/upload"
    method = "POST"
    timestamp = datetime.utcnow().strftime("%Y-%m-%dT%H:%M:%S.%f")[:-3] + "Z"
    md5_hash = hashlib.md5(array_buffer).hexdigest()

    jwt_header = {
        "typ": "JWT",
        "alg": "ES512",
    }

    jwt_body = {
        "payload_md5": md5_hash,
        "timestamp": timestamp,
        "method": method,
        "uri": endpoint,
    }

    encoded_header_token = jwt.encode(jwt_body, CLIENT_PRIVATE_KEY, algorithm="ES512", headers=jwt_header)

    signed_header = {
        "Authorization": encoded_header_token,
        "API-CLIENT-KEY": API_KEY,
        "Content-Type": "multipart/form-data",
    }

    url = f"{BASE_URL}{endpoint}"
    multipart_data = MultipartEncoder(
        fields={'file': ('image.jpeg', array_buffer, 'image/jpeg')}
    )
    signed_header['Content-Type'] = multipart_data.content_type

    try:
        response = requests.post(url, headers=signed_header, data=multipart_data)
        response_data = response.json()
        document_key = response_data.get('document_key')
        print(f'Response data is: {response_data} and document_key is: {document_key}')
        return document_key
    except Exception as error:
        print('Error:', error)
        raise


def main():
    file_url = "{FILE_URL}"

    document_buffer = get_document(file_url)

    document_key = upload_document(document_buffer)

    print("document_key is", document_key)

if __name__ == "__main__":
    main()

const jwt = require('jsonwebtoken')
const crypto = require('crypto')
const axios = require('axios')
const FormData = require('form-data')
const fs = require('fs')
const fetch = require('node-fetch')

async function getDocument(url) {
  try {
    const response = await axios.get(url, { responseType: 'arraybuffer' })
    return response.data
  } catch (error) {
    console.error('Error fetching document:', error)
    throw error
  }
}

async function uploadDocument(arrayBuffer) {
  const endpoint = '/upload'
  const method = 'POST'
  const timestamp = new Date().toISOString()
  const md5_hash = crypto.createHash('md5').update(arrayBuffer).digest('hex')
  const client_private_key = `-----BEGIN EC PRIVATE KEY-----
    MIHbAgEBBEHh1hIeOPE5XNNhn6bxRAmVswsPZ0wZCmzVvP8Tl/LZK9ofVmRVGzll
    srU1uezJEyHKYdOHrE2p52xUj+pHzjJvb6AHBgUrgQQAI6GBiQOBhgAEAAofUz1J
    hBSOyGHLsnV9Sz0DSWmhl7U+ljqbfa8PKVFWSV3w16I1v2zME5/UzUhHn1gWsjnv
    7/ekcLLAQbvqMPNXAfjIhFXLAPzqbB9iCuVua1v0Vgy52rBemOWrJka/Ws2bnKR8
    h1N1OxOYeYr6C2jqMygBLktKMAs+282CEiEb4bIv
    -----END EC PRIVATE KEY-----`; // Esta chave é um exemplo, por favor utilize sua própria chave
  const api_key = '4c268c0a-53ff-429b-92b6-47ef98a6d89a' // Esta chave é um exemplo, por favor utilize sua própria chave

  try {
    const jwt_header = {
      typ: 'JWT',
      alg: 'ES512',
    }

    const jwt_body = {
      payload_md5: md5_hash,
      timestamp: timestamp,
      method: method,
      uri: endpoint,
    }

    const encoded_header_token = jwt.sign(jwt_body, client_private_key, {
      algorithm: 'ES512',
      header: jwt_header,
    })

    const signed_header = {
      AUTHORIZATION: encoded_header_token,
      'API-CLIENT-KEY': api_key,
      'Content-Type': 'multipart/form-data',
    }

    const url = `${base_url}${endpoint}`
    const formData = new FormData()
    formData.append('file', Buffer.from(arrayBuffer), {
      filename: 'image.jpeg',
    })

    fetch(url, {
      method: 'POST',
      headers: signed_header,
      body: formData,
    })
      .then(data => {
        console.log('Response data is: ' + data)

        return data.document_key
      })
      .catch(error => {
        console.log('Error: ' + error)
      })
  } catch (error) {
    console.error('Error:', error)
  }
}

async function main() {
  const fileUrl = '<URL_LINK_TO_DOCUMENT_IMAGE>'
  const documentBuffer = await getDocument(fileUrl)
  const documentKey = await uploadDocument(documentBuffer)

  console.log('Document key is: ' + documentKey)
}

main()

OBS: The example above uses the library node-fetch to make the call, but you can use the library of your choice. The important thing is that the call must be made using the POST method, with the Content-Type header set to multipart/form-data and the body must be a FormData object with the key file and the value as the file binary to be sent.

Aviso

The 'Axios' library has a bug that causes FormData to be sent empty. The issue can be seen on the GitHub repository. If this problem has not yet been resolved at the time of your integration, we suggest using the 'node-fetch' library to make this call.

2. Debt Simulation

Request Debt Simulation

At QI Tech, we provide our clients with the ability to simulate the values of a credit operation before it is actually issued. The simulation follows the same pattern as the debt issuance request, but it is not necessary to provide the debtor’s registration and disbursement account details. The following endpoint is a simplified version of /debt_simulation, but much more optimized. It is used to calculate only one disbursement option.

ENDPOINT

/v2/credit_operation/simulation

METHOD

POST

Request Body

{
    "credit_operation_type": "ccb",
    "disbursed_issue_amount": 2800,
    "disbursement_date": "2025-09-24",
    "first_due_date": "2025-10-24",
    "force_installments_on_workdays": true,
    "interest_type": "pre_price_days",
    "issuer_person_type": "natural",
    "monthly_interest_rate": 0.04488,
    "number_of_installments": 12,
    "principal_amortization_month_period": 1
}

Request Body Details

Field	Type	Description	Max. Char.
credit_operation_type*	enum	Enumerator Credit Operation Type - Type of credit agreement	-
disbursed_issue_amount*	float	The value actually released to the borrower	-
disbursement_date*	date	The specific date the loan funds are made available	-
first_due_date*	date	Due date of the first installment	-
force_installments_on_workdays*	boolean	true - If true, all due dates will fall on business days	-
interest_type*	enum	Enumerator Interest Type - Amortization method	-
issuer_person_type*	enum	Enumerator Person Type	-
monthly_interest_rate*	float	Monthly interest rate	-
number_of_installments*	int	Number of installments	-
principal_amortization_month_period*	int	Period, in months, between installments	-

Response Debt Simulation

STATUS

200

Response Body

{
  "additional_iof": 0.14,
  "annual_cet": 145.08,
  "assignment_amount": 36.21,
  "base_iof": 0.1,
  "cet": 7.76,
  "disbursed_amount": 35.9,
  "disbursement_date": "2024-09-06",
  "fees": [
    {
      "amount": 0.0,
      "fee_amount": 0.0,
      "amount_type": "absolute",
      "fee_type": "tac",
      "type": "external"
    },
    {
      "amount": 0.0,
      "fee_amount": 0.0,
      "amount_type": "absolute",
      "fee_type": "spread",
      "type": "external"
    },
    {
      "amount": 0.2,
      "fee_amount": 0.07,
      "amount_type": "percentage",
      "fee_type": "spread",
      "type": "internal"
    }
  ],
  "first_due_date": "2024-09-25",
  "installments": [
    {
      "due_date": "2024-09-25",
      "amount": 19.5,
      "due_principal": 36.14,
      "due_interest": 0.0,
      "has_interest": true,
      "period": 0.6129032258064516,
      "period_workdays": 0.6190476190476191,
      "calendar_days": 19,
      "workdays": 13,
      "installment_number": 1,
      "period_to_disbursement": 0.6129032258064516,
      "prefixed_amount": 1.58227236,
      "period_workdays_to_disbursement": 1.0,
      "calendar_days_to_disbursement": 19,
      "workdays_to_disbursement": 13,
      "tax_amount": 0.02791582,
      "principal_amortization_amount": 17.91772764
    },
    {
      "due_date": "2024-10-25",
      "amount": 19.5,
      "due_principal": 18.22227236,
      "due_interest": 0.0,
      "has_interest": true,
      "period": 1.0,
      "period_workdays": 1.0,
      "calendar_days": 30,
      "workdays": 22,
      "installment_number": 2,
      "period_to_disbursement": 1.6129032258064515,
      "prefixed_amount": 1.27772764,
      "period_workdays_to_disbursement": 2.0,
      "calendar_days_to_disbursement": 49,
      "workdays_to_disbursement": 35,
      "tax_amount": 0.07321709,
      "principal_amortization_amount": 18.22227236
    }
  ],
  "interest_type": "pre_price_days",
  "issue_amount": 36.14,
  "prefixed_interest_rate": {
    "interest_base": "calendar_days",
    "annual_rate": 1.25219159,
    "daily_rate": 0.00225783,
    "monthly_rate": 0.07
  },
  "tax_configuration": {
    "additional_rate": 0.0038,
    "base_rate": 0.000082
  },
  "total_iof": 0.24
}

Response Body Details

Campo	Tipo	Description	Máx. Caract.
annual_cet	float	Total effective cost expressed as a decimal per year	-
assignment_amount	float	Acquisition value of the credit operation	-
cet	float	Total effective cost expressed as a decimal per month.	-
fees	object	Object Fees - List of QI Tech fees charged on the operation	-
disbursed_amount	float	Amount disbursed in the credit operation	-
disbursement_date	date	Disbursement date of the operation	-
installments	list	Object Installments - Installments of the operation	-
interest_type	enum	Enumerator Interest Type - Amortization method and interest calculation method	-
additional_iof	float	Additional IOF amount	-
base_iof	float	Base IOF amount	-
total_iof	float	Total IOF amount	-
issue_amount	float	Issue/nominal value of the credit operation	-
tax_configuration	object	Object Tax Configuration - Rate iof values	-
first_due_date	date	Due date of the first installment	-
prefixed_interest_rate	object	Object Interest Rate - Nominal interest rate	-

Object Fees

Campo	Tipo	Description	Máx. Caract.
amount	float	Fee amount (in percentage or absolute value, depending on the value provided in the amount_type field)	-
amount_type	enum	Enumerators amount_type - Fee value unit	-
fee_amount	float	Absolute value of the fee charged in the operation	-
fee_type	enum	Enumerator Fee Type - Type of fee charged in the operation	-
type	enum	Enumerator Origin Type - Source of the fee charged in the operation	-

Object Installments

Campo	Tipo	Description	Máx. Caract.
calendar_days	int	Number of calendar days between installments	-
due_date	date	Installment due date in calendar days	-
due_principal	float	Remaining principal on the installment due date before its payment	-
has_interest	boolean	true - If true, interest applies to the installment	-
installment_number	int	Installment number	-
prefixed_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	-
amount	float	Installment total value	-
due_interest	float	Remaining interest after the installment due date before its payment	-
period	float	Installment period	-
period_workdays	float	Installment period in business days	-
period_to_disbursement	float	Period until disbursement	-
period_workdays_to_disbursement	float	Business days until disbursement	-
calendar_days_to_disbursement	int	Calendar days to disbursement	-
workdays	int	Business days between installments	-
workdays_to_disbursement	int	Business days until disbursement	-

Object Interest Rate

Campo	Description	Máx. Caract.
annual_rate	Annual fixed/floating interest rate expressed as a decimal	-
daily_rate	Daily fixed/floating interest rate expressed as a decimal	-
interest_base	Enumerator Interest Base - Interest calculation basis	-
monthly_rate	Monthly fixed/floating interest rate expressed as a decimal	-

Object Tax Configuration

Campo	Description	Máx. Caract.
base_rate	Base IOF rate value	-
additional_rate	Additional IOF rate value	-

Enumeratores

Enumerator Person Type

Enumerator	Description
legal	Legal person
natural	Natural person

Enumerator Account Type

Enumerator	Description
checking_account	Checking account
deposit_account	Deposit account
guaranteed_account	Guaranteed account
investment_account	Investment account
payment_account	Payment account
saving_account	Saving account
salary_account	Salary account

Enumerator Amount Type

Enumerator	Description
absolute	Absolute value
percentage	percentage value

Enumerator Interest Type

Enumerator	Description
pre_price_days	Price amortization method (equal installments) with daily fixed-rate interest calculation
pre_price	Price amortization method (equal installments) with fixed-rate interest calculation over 30-day periods
pre_sac	Constant principal amortization (SAC system) with interest calculated daily on a fixed-rate basis
post_sac	Constant principal amortization (SAC system) with daily interest calculation based on a fixed rate plus a floating-rate index (e.g., CDI, IPCA, or IGPM)
post_price	Price amortization method (equal installments) with interest calculated over 30-day periods based on a fixed rate plus a floating-rate index (e.g., CDI, IPCA, or IGPM)
post_price_days	Price amortization method (equal installments) with daily interest calculation based on a fixed rate plus a floating-rate index (e.g., CDI, IPCA, or IGPM)

Enumerator Credit Operation Type

Enumerator	Description
ccb	CCB
cce	CCE
cci	CCI
nce	NCE

Enumerator Interest Base

Enumerator	Description
workdays	Interest calculation basis in business days, assuming a 252-day year
calendar_days	Interest calculation basis in calendar days, assuming a 360-day year
calendar_days_365	Interest calculation basis in calendar days, assuming a 365-day year

Enumerator Fee Type

Each fee type must be previously enabled and configured by QI Tech

Enumerator	Description
tac	Registration Fee
spread	Premium included in the credit operation's acquisition value
warranty_analysis	Collateral analysis fee
ted_fee	TED transfer fee
spread_ted_fee	Premium on the TED transfer fee

Enumerator Origin Type

Each fee type must be previously enabled and configured by QI Tech

Enumerator	Description
internal	Internal fee
external	External fee

3. Debt Issuance for Individuals

This endpoint issues the debt and processes the contract signature via opt-in. Immediately after issuance, the debt is automatically disbursed. It is not necessary to pre-register the borrower; simply provide the registration details at the time of the debt request.

Request

ENDPOINT

/signed_debt

METHOD

POST

Request Body

{
    "simplified": true,
    "additional_data": {
        "contract": {
            "contract_number": "TIK11267101212",
            "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": "",
                            "lat": ""
                        },
                        "fingerprint_device": null
                    }
                }
            ]
        }
    },
    "financial": {
        "number_of_installments": 3,
        "credit_operation_type": "ccb",
        "interest_type": "pre_price_days",
        "annual_interest_rate": 3.81790482,
        "disbursed_amount": 200,
        "fine_configuration": {
            "contract_fine_rate": 0.02,
            "monthly_rate": 0.15,
            "interest_base": "calendar_days"
        },
        "interest_grace_period": 0,
        "rebates": null,
        "issue_date": "2025-10-27",
        "disbursement_date": "2025-10-27",
        "first_due_date": "2025-11-27",
        "principal_grace_period": 0
    },
    "disbursement_bank_accounts": [
        {
            "account_digit": "5",
            "document_number": "32402502000135",
            "bank_code": "329",
            "account_number": "00002",
            "percentage_receivable": 100,
            "branch_number": "0001",
            "name": "CONTA LOJISTA"
        }
    ],
    "purchaser_document_number": "32402502000135",
    "borrower": {
        "email": "alan.turing@email.com",
        "document_identification": "494598fd-c226-4332-a500-591ae3884673",
        "document_identification_back": "494598fd-c226-4332-a500-591ae3884673",
        "birth_date": "1990-11-20",
        "person_type": "natural",
        "profession": "Public server",
        "individual_document_number": "96969879003",
        "address": {
            "city": "São Paulo",
            "neighborhood": "CENTRO",
            "street": "Avenida Feliz",
            "complement": "AP 801",
            "postal_code": "49026100",
            "state": "SP",
            "number": "1000"
        },
        "phone": {
            "country_code": "055",
            "number": "912345678",
            "area_code": "11"
        },
        "mother_name": "MARIA TURING",
        "marital_status": "married",
        "nationality": "",
        "document_identification_number": "96969879003",
        "name": "Alan Mathison Turing"
    }
}

Response

The response to this debt request will return the payment plan as well as a DEBT-KEY, which is the identifier of the debt in QI SCD.

STATUS

201

Response Body

{
    "webhook_type": "debt",
    "key": "1ebd4a90-2721-4c39-a399-427fa16bca65",
    "status": "waiting_signature",
    "event_datetime": "2025-10-27 17:09:31",
    "data": {
        "borrower": {
            "name": "Alan Mathison Turing",
            "document_number": "96969879003",
            "related_party_key": "d6353266-30bc-4ab1-964e-2c7a643d8ba2"
        },
        "contract": {
            "document_key": "c8b191cb-7b90-4e37-9280-397a597babc1",
            "number": "TIK11267101212",
            "urls": [
                "https://storage.googleapis.com/sandbox-doc-api/documents/c8b191cb-7b90-4e37-9280-397a597babc1/RAFAELAEBENJAMINFINANCEIRALTDA-ALAN_MATHISON_TURING-CCB-TIK11267101212-20251027170925.pdf"
            ],
            "signature_information": [
                {
                    "signer_name": "Alan Mathison Turing",
                    "signer_document_number": "96969879003",
                    "signer_role": "issuer",
                    "signer_email": "alan.turing@email.com",
                    "signer_external_key": null,
                    "signature_url": null
                }
            ]
        },
        "requester_identifier_key": "1ebd4a90-2721-4c39-a399-427fa16bca65",
        "iof_charge_method": "financed",
        "collaterals": [],
        "contract_fees": [
            {
                "fee_type": "spread",
                "fee_amount": 1.01
            },
            {
                "fee_type": "spread_ted_fee",
                "fee_amount": 0.5
            }
        ],
        "external_contract_fees": [],
        "external_contract_fee_amount": 0,
        "net_external_contract_fee_amount": 0,
        "contract_fee_amount": 1.51,
        "issue_amount": 201.84,
        "assignment_amount": 203.35,
        "cet": "14,7500%",
        "annual_cet": "421,3334%",
        "number_of_installments": 3,
        "base_iof": 1.06,
        "additional_iof": 0.78,
        "total_iof": 1.84,
        "ipoc_code": "324025020203196969879003TIK11267101212",
        "prefixed_interest_rate": {
            "annual_rate": 3.81790482,
            "created_at": "2025-10-27T17:09:25",
            "daily_rate": 0.0043771607,
            "interest_base": "calendar_days",
            "monthly_rate": 0.14
        },
        "installments": [
            {
                "accrual_reference_date": null,
                "additional_costs": [],
                "advanced_paid_amount": 0,
                "bank_slip_key": null,
                "business_due_date": "2025-11-28",
                "calendar_days": 31,
                "digitable_line": null,
                "due_date": "2025-11-27",
                "due_interest": 0,
                "due_principal": 201.84,
                "fine_amount": null,
                "has_interest": true,
                "installment_history": [],
                "installment_key": "e25fb146-0a61-4319-a722-d01b2213d0f9",
                "installment_number": 1,
                "installment_payment": [],
                "installment_status": "created",
                "installment_type": "principal",
                "original_due_principal": 201.84,
                "original_pre_fixed_amount": 29.26477451,
                "original_principal_amortization_amount": 58.16522549,
                "original_total_amount": 87.43,
                "paid_amount": 0,
                "paid_at": null,
                "post_fixed_amount": 0,
                "pre_fixed_amount": 29.26477451,
                "principal_amortization_amount": 58.16522549,
                "qr_code_key": null,
                "qr_code_url": null,
                "renegotiation_proposal_key": null,
                "tax_amount": 0.147856,
                "total_accrual_amount": null,
                "total_amount": 87.43,
                "total_paid_amount": 0,
                "workdays": 22
            },
            {
                "accrual_reference_date": null,
                "additional_costs": [],
                "advanced_paid_amount": 0,
                "bank_slip_key": null,
                "business_due_date": "2025-12-30",
                "calendar_days": 30,
                "digitable_line": null,
                "due_date": "2025-12-27",
                "due_interest": 0,
                "due_principal": 143.67477451,
                "fine_amount": null,
                "has_interest": true,
                "installment_history": [],
                "installment_key": "2557de2b-6df1-4a8a-b46a-59206ece157f",
                "installment_number": 2,
                "installment_payment": [],
                "installment_status": "created",
                "installment_type": "principal",
                "original_due_principal": 143.67477451,
                "original_pre_fixed_amount": 20.11446867,
                "original_principal_amortization_amount": 67.31553133,
                "original_total_amount": 87.43,
                "paid_amount": 0,
                "paid_at": null,
                "post_fixed_amount": 0,
                "pre_fixed_amount": 20.11446867,
                "principal_amortization_amount": 67.31553133,
                "qr_code_key": null,
                "qr_code_url": null,
                "renegotiation_proposal_key": null,
                "tax_amount": 0.33671229,
                "total_accrual_amount": null,
                "total_amount": 87.43,
                "total_paid_amount": 0,
                "workdays": 20
            },
            {
                "accrual_reference_date": null,
                "additional_costs": [],
                "advanced_paid_amount": 0,
                "bank_slip_key": null,
                "business_due_date": "2026-01-28",
                "calendar_days": 31,
                "digitable_line": null,
                "due_date": "2026-01-27",
                "due_interest": 0,
                "due_principal": 76.35924318,
                "fine_amount": null,
                "has_interest": true,
                "installment_history": [],
                "installment_key": "cc503d1d-6387-4a1f-bd78-62b248d02ec8",
                "installment_number": 3,
                "installment_payment": [],
                "installment_status": "created",
                "installment_type": "principal",
                "original_due_principal": 76.35924318,
                "original_pre_fixed_amount": 11.07075682,
                "original_principal_amortization_amount": 76.35924318,
                "original_total_amount": 87.43,
                "paid_amount": 0,
                "paid_at": null,
                "post_fixed_amount": 0,
                "pre_fixed_amount": 11.07075682,
                "principal_amortization_amount": 76.35924318,
                "qr_code_key": null,
                "qr_code_url": null,
                "renegotiation_proposal_key": null,
                "tax_amount": 0.57605413,
                "total_accrual_amount": null,
                "total_amount": 87.43,
                "total_paid_amount": 0,
                "workdays": 21
            }
        ],
        "total_pre_fixed_amount": 60.45
    }
}

Main fields definitions*

For any doubts, feel free to consult QI Tech's documentation with the explanation of every field of Debt insuance API.

4. Webhooks

After the successful response, you will receive a webhook with the signed CCB and a webhook indicating the disbursement's success or failure.

Signature webhook

Response Body

{
  "webhook": {
    "key": "1ebd4a90-2721-4c39-a399-427fa16bca65",
    "status": "signature_finished",
    "webhook_type": "debt",
    "event_datetime": "2025-10-27 17:09:33",
    "signed_contract_url": "https://storage.googleapis.com/sandbox-doc-api/documents/c8b191cb-7b90-4e37-9280-397a597babc1/RAFAELAEBENJAMINFINANCEIRALTDA-ALAN_MATHISON_TURING-CCB-TIK11267101212-20251027170925_signed.pdf"
  }
}

Disbursement webhook

Response Body

{
  "webhook": {
    "key": "1ebd4a90-2721-4c39-a399-427fa16bca65",
    "data": {
      "installments": [
        {
          "due_date": "2025-11-27",
          "total_amount": 87.43,
          "installment_key": "e25fb146-0a61-4319-a722-d01b2213d0f9",
          "pre_fixed_amount": 29.26477451,
          "installment_number": 1,
          "principal_amortization_amount": 58.16522549
        },
        {
          "due_date": "2025-12-27",
          "total_amount": 87.43,
          "installment_key": "2557de2b-6df1-4a8a-b46a-59206ece157f",
          "pre_fixed_amount": 20.11446867,
          "installment_number": 2,
          "principal_amortization_amount": 67.31553133
        },
        {
          "due_date": "2026-01-27",
          "total_amount": 87.43,
          "installment_key": "cc503d1d-6387-4a1f-bd78-62b248d02ec8",
          "pre_fixed_amount": 11.07075682,
          "installment_number": 3,
          "principal_amortization_amount": 76.35924318
        }
      ],
      "ted_receipt_list": [],
      "requester_identifier_key": null
    },
    "status": "disbursed",
    "webhook_type": "debt",
    "event_datetime": "2025-10-27 17:10:21"
  }
}

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

Cancelation webhook

Response Body

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

Cancelation reasons

cancel_reason_enumerator	Description
disbursing_error	Operation canceled due to an error during disbursement.
waiting_signature	Operation canceled due to missing signature.
pix_max_retry	Operation canceled because the receiving bank could not process the disbursement.
manual	Operation canceled manually.
agencia_conta_invalida	Invalid agency or recipient account number.
invalid_account	The destination account number is nonexistent or invalid.
invalid_document_number	The CPF/CNPJ of the destination account is incorrect.
unsupported_transaction	The destination account does not support this type of transaction.
invalid_ispb	The ISPB number is invalid or nonexistent.
rejected_payment	Payment order was rejected by the receiving bank.
refund_after_payee_request	Refund requested by the payee
invalid_account	The destination account number is nonexistent or invalid.
invalid_document_number	The CPF/CNPJ of the destination account is incorrect.
rejected_payment	Payment rejected by the receiving bank.
blocked_account	The destination account is blocked.
unsupported_transaction	The destination account does not support this type of transaction.
amount_too_great	Payment/refund amount exceeds the limit for the credited destination account.
invalid_ispb	The ISPB number is invalid or nonexistent.
receiver_error	Transaction interrupted due to error on the receiver's PSP.
closed_account	The destination account is closed.
disbursing_hour_closed	Disbursement occurred outside of the allowed time frame.
unregistered_pix_key	The Pix key is not being used.
manual	Operation manually canceled.
spi_timeout	Timeout control in SPI.

5. Debt installments

If QI Tech is the collection agent for the operation, there is a specific API to retrieve information about the installments. The statuses that can be configured are:

webhook_type: installment.status_change
Webhook status: opened, paid, waiting_payment, paid_early, paid_partial, overdue, paid_partial_overdue and paid_overdue

Examples

Paid Installment

{
  "webhook": {
    "key": "1ebd4a90-2721-4c39-a399-427fa16bca65",
    "data": {
      "status": "paid",
      "installment": {
        "events": [
          {
            "amount": null,
            "created_at": null,
            "event_date": "2025-10-27T17:10:21",
            "old_due_date": null,
            "installment_event_type": {
              "enumerator": "open",
              "translation_path": "co.InstallmentEventType.open"
            },
            "installment_old_status": {
              "enumerator": "created",
              "translation_path": "co.InstallmentStatus.created"
            }
          },
          {
            "amount": 87.43,
            "created_at": "2025-10-27T17:10:21",
            "event_date": "2025-10-27T17:10:21",
            "old_due_date": null,
            "installment_event_type": {
                "enumerator": "payment",
                "translation_path": "co.InstallmentEventType.payment"
            },
            "installment_old_status": {
                "enumerator": "opened",
                "translation_path": "co.InstallmentStatus.opened"
            }
        }
        ],
        "paid_at": "2025-10-27T17:10:21",
        "due_date": "2026-01-27",
        "workdays": 21,
        "created_at": "2025-10-27T17:09:25",
        "tax_amount": 0.57605413,
        "updated_at": "2025-10-27T17:10:21",
        "fine_amount": null,
        "paid_amount": 87.43,
        "qr_code_key": null,
        "qr_code_url": null,
        "due_interest": 0.0,
        "has_interest": true,
        "payment_type": {
          "enumerator": "bankslip",
          "translation_path": "co.PaymentType.bankslip"
        },
        "total_amount": 87.43,
        "bank_slip_key": null,
        "calendar_days": 31,
        "due_principal": 76.35924318,
        "digitable_line": null,
        "installment_key": "cc503d1d-6387-4a1f-bd78-62b248d02ec8",
        "additional_costs": [],
        "installment_type": {
          "enumerator": "principal",
          "translation_path": "co.InstallmentType.principal"
        },
        "pre_fixed_amount": 11.07075682,
        "business_due_date": "2026-01-28",
        "cetip_settlements": [],
        "post_fixed_amount": 0.0,
        "total_paid_amount": 0.0,
        "installment_number": 3,
        "installment_status": {
          "enumerator": "opened",
          "translation_path": "co.InstallmentStatus.opened"
        },
        "installment_history": [],
        "installment_payment": [],
        "advanced_paid_amount": 0.0,
        "total_accrual_amount": null,
        "original_total_amount": 87.43,
        "accrual_reference_date": null,
        "original_due_principal": 76.35924318,
        "original_pre_fixed_amount": 11.07075682,
        "renegotiation_proposal_key": null,
        "principal_amortization_amount": 76.35924318,
        "original_principal_amortization_amount": 76.35924318
      },
      "is_finished": false
    },
    "webhook_type": "installment.status_change"
  }
}

Bank slips data

{
    "key": "1ebd4a90-2721-4c39-a399-427fa16bca65",
    "data": {
        "status": "update",
        "installments": [
            {
                "due_date": "2025-11-27",
                "qr_code_key": "eeb4f5a6-6cba-4901-8113-21c7261b54ac",
                "qr_code_url": "00020126930014br.gov.bcb.pix2571qrcode-h.sandbox.qitech.app/bacen/cobv/eeb4f5a66cba4901811321c7261b54ac5204000053039865802BR5925QISOCIEDADEDECREDITODIRET6008SaoPaulo61080145200062070503***6304D300",
                "total_amount": 87.43,
                "bank_slip_key": "524440c0-302b-4553-8211-5cf012f2e718",
                "digitable_line": "32990001031000700326159000000204112780000008743",
                "installment_key": "e25fb146-0a61-4319-a722-d01b2213d0f9",
                "pre_fixed_amount": 29.26477451,
                "principal_amortization_amount": 58.16522549
            },
            {
                "due_date": "2025-12-27",
                "qr_code_key": "98781ab0-318a-43c4-9ce6-fdc22514c540",
                "qr_code_url": "00020126930014br.gov.bcb.pix2571qrcode-h.sandbox.qitech.app/bacen/cobv/98781ab0318a43c49ce6fdc22514c5405204000053039865802BR5925QISOCIEDADEDECREDITODIRET6008SaoPaulo61080145200062070503***63040687",
                "total_amount": 87.43,
                "bank_slip_key": "ece5355a-4b51-48af-aa4b-f074b93c9fef",
                "digitable_line": "32990001031000700326160000000202613080000008743",
                "installment_key": "2557de2b-6df1-4a8a-b46a-59206ece157f",
                "pre_fixed_amount": 20.11446867,
                "principal_amortization_amount": 67.31553133
            },
            {
                "due_date": "2026-01-27",
                "qr_code_key": "289792ad-3e5a-4308-8e3d-7b75afe0fea5",
                "qr_code_url": "00020126930014br.gov.bcb.pix2571qrcode-h.sandbox.qitech.app/bacen/cobv/289792ad3e5a43088e3d7b75afe0fea55204000053039865802BR5925QISOCIEDADEDECREDITODIRET6008SaoPaulo61080145200062070503***630443CC",
                "total_amount": 87.43,
                "bank_slip_key": "09888b40-6844-4c8c-a474-f22a94e463a9",
                "digitable_line": "32990001031000700326161000000200313390000008743",
                "installment_key": "cc503d1d-6387-4a1f-bd78-62b248d02ec8",
                "pre_fixed_amount": 11.07075682,
                "principal_amortization_amount": 76.35924318
            }
        ]
    },
    "webhook_type": "installment.status_change"
}

Furthermore, there is an option to retrieve the duplicate copy of the installment:

ENDPOINT

/bank_slip/2-way/BANK_SLIP_KEY*

METHOD

PATCH

*BANK_SLIP_KEY (string): Payment slip identification key.

Duplicate Copy

{
  "key": "1150f778-b479-42ab-b76b-c6a76cdfcf50",
  "data": {
    "status": "update",
    "installments": [
      {
        "due_date": "2024-12-02",
        "qr_code_key": "56da9761-a425-488d-a65c-e54680346533",
        "qr_code_url": "00020126830014br.gov.bcb.pix2561qrcode.qitech.app/bacen/cobv/56da9761a425488da65ce543047339",
        "total_amount": 16.2,
        "bank_slip_key": "27e70d92-caee-4fe2-92f3-f967fd26ce70",
        "digitable_line": "32990001031000000000908001075103782160000759600",
        "installment_key": "e80a53c6-080a-48d6-ba12-dd01459650ed",
        "pre_fixed_amount": 16.2,
        "principal_amortization_amount": 0
      },
      {
        "due_date": "2025-03-05",
        "qr_code_key": "fbea5390-3a77-4432-b8f3-d174aff9c048",
        "qr_code_url": "00020126830014br.gov.bcb.pix2561qrcode.qitech.app/bacen/cobv/56da9761a425488da65ce543047339",
        "total_amount": 84.12,
        "bank_slip_key": "82f5741b-9cf6-4a9c-b9b4-8fcc29a94969",
        "digitable_line": "32990001031000000000908001075103782160000759600",
        "installment_key": "c8c43838-2ff0-4d4e-af1e-35ac20255030",
        "pre_fixed_amount": 47.5953627,
        "principal_amortization_amount": 36.5246373
      }
    ]
  },
  "webhook_type": "installment.status_change"
}

6. Debt inquiry

You can also query the debt later to retrieve information or track its status:

ENDPOINT

/v2/credit_operation/CREDIT-OPERATION-KEY

MÉTODO

GET

Path params

Campo	Tipo	Descrição	Caracteres
`credit_operation_key` *	string	Chave da operação de crédito.	UUID

Response

STATUS

200

Response Body

{
    "credit_operation_key": "1ebd4a90-2721-4c39-a399-427fa16bca65",
    "issue_amount": 201.84,
    "origin_key": "1ebd4a90-2721-4c39-a399-427fa16bca65",
    "total_iof": 1.84,
    "disbursement_start_date": "2025-10-27",
    "disbursement_end_date": "2025-10-27",
    "issue_date": "2025-10-27",
    "requester_identifier_key": "1ebd4a90-2721-4c39-a399-427fa16bca65",
    "installments": [
        {
            "business_due_date": "2025-11-28",
            "due_date": "2025-11-27",
            "calendar_days": 31,
            "due_interest": 0,
            "due_principal": 201.84,
            "fine_amount": 0,
            "has_interest": true,
            "post_fixed_amount": 0,
            "pre_fixed_amount": 29.26,
            "principal_amortization_amount": 58.17,
            "tax_amount": 0.15,
            "total_amount": 87.43,
            "workdays": 22,
            "accrual_reference_date": null,
            "advanced_paid_amount": 0,
            "bank_slip_key": "524440c0-302b-4553-8211-5cf012f2e718",
            "digitable_line": "32990001031000700326159000000204112780000008743",
            "installment_key": "e25fb146-0a61-4319-a722-d01b2213d0f9",
            "installment_status": "opened",
            "installment_type": "principal",
            "original_due_principal": 201.84,
            "original_pre_fixed_amount": 29.26,
            "original_principal_amortization_amount": 58.17,
            "paid_amount": 0,
            "original_total_amount": 87.43,
            "qr_code_key": "eeb4f5a6-6cba-4901-8113-21c7261b54ac",
            "qr_code_url": "00020126930014br.gov.bcb.pix2571qrcode-h.sandbox.qitech.app/bacen/cobv/eeb4f5a66cba4901811321c7261b54ac5204000053039865802BR5925QISOCIEDADEDECREDITODIRET6008SaoPaulo61080145200062070503***6304D300",
            "renegotiation_proposal_key": null,
            "total_accrual_amount": 0,
            "total_paid_amount": 0,
            "installment_number": 1,
            "paid_at": null,
            "updated_at": "2025-10-27T17:10:21",
            "principal_amortization_payment_amount": 0,
            "prefixed_interest_payment_amount": 0
        },
        {
            "business_due_date": "2025-12-30",
            "due_date": "2025-12-27",
            "calendar_days": 30,
            "due_interest": 0,
            "due_principal": 143.67477451,
            "fine_amount": 0,
            "has_interest": true,
            "post_fixed_amount": 0,
            "pre_fixed_amount": 20.11,
            "principal_amortization_amount": 67.32,
            "tax_amount": 0.34,
            "total_amount": 87.43,
            "workdays": 20,
            "accrual_reference_date": null,
            "advanced_paid_amount": 0,
            "bank_slip_key": "ece5355a-4b51-48af-aa4b-f074b93c9fef",
            "digitable_line": "32990001031000700326160000000202613080000008743",
            "installment_key": "2557de2b-6df1-4a8a-b46a-59206ece157f",
            "installment_status": "opened",
            "installment_type": "principal",
            "original_due_principal": 143.67,
            "original_pre_fixed_amount": 20.11,
            "original_principal_amortization_amount": 67.32,
            "paid_amount": 0,
            "original_total_amount": 87.43,
            "qr_code_key": "98781ab0-318a-43c4-9ce6-fdc22514c540",
            "qr_code_url": "00020126930014br.gov.bcb.pix2571qrcode-h.sandbox.qitech.app/bacen/cobv/98781ab0318a43c49ce6fdc22514c5405204000053039865802BR5925QISOCIEDADEDECREDITODIRET6008SaoPaulo61080145200062070503***63040687",
            "renegotiation_proposal_key": null,
            "total_accrual_amount": 0,
            "total_paid_amount": 0,
            "installment_number": 2,
            "paid_at": null,
            "updated_at": "2025-10-27T17:10:21",
            "principal_amortization_payment_amount": 0,
            "prefixed_interest_payment_amount": 0
        },
        {
            "business_due_date": "2026-01-28",
            "due_date": "2026-01-27",
            "calendar_days": 31,
            "due_interest": 0,
            "due_principal": 76.35924318,
            "fine_amount": 0,
            "has_interest": true,
            "post_fixed_amount": 0,
            "pre_fixed_amount": 11.07,
            "principal_amortization_amount": 76.36,
            "tax_amount": 0.58,
            "total_amount": 87.43,
            "workdays": 21,
            "accrual_reference_date": null,
            "advanced_paid_amount": 0,
            "bank_slip_key": "09888b40-6844-4c8c-a474-f22a94e463a9",
            "digitable_line": "32990001031000700326161000000200313390000008743",
            "installment_key": "cc503d1d-6387-4a1f-bd78-62b248d02ec8",
            "installment_status": "opened",
            "installment_type": "principal",
            "original_due_principal": 76.36,
            "original_pre_fixed_amount": 11.07,
            "original_principal_amortization_amount": 76.36,
            "paid_amount": 0,
            "original_total_amount": 87.43,
            "qr_code_key": "289792ad-3e5a-4308-8e3d-7b75afe0fea5",
            "qr_code_url": "00020126930014br.gov.bcb.pix2571qrcode-h.sandbox.qitech.app/bacen/cobv/289792ad3e5a43088e3d7b75afe0fea55204000053039865802BR5925QISOCIEDADEDECREDITODIRET6008SaoPaulo61080145200062070503***630443CC",
            "renegotiation_proposal_key": null,
            "total_accrual_amount": 0,
            "total_paid_amount": 0,
            "installment_number": 3,
            "paid_at": null,
            "updated_at": "2025-10-27T17:10:21",
            "principal_amortization_payment_amount": 0,
            "prefixed_interest_payment_amount": 0
        }
    ],
    "first_due_date": "2025-11-27",
    "requester_key": "6ca83592-ce8c-42f5-ac0d-5ce182dbe794",
    "original_total_iof": null,
    "contract_number": "TIK11267101212",
    "credit_operation_status_enumerator": "opened",
    "operation_type_enumerator": "structured_operation",
    "disbursement_date": "2025-10-27",
    "issuer_name": "Alan Mathison Turing",
    "issuer_document_number": "96969879003",
    "external_contract_fees": [],
    "cet": 14.75,
    "annual_cet": 421.33,
    "final_disbursement_amount": 200,
    "number_of_installments": 3,
    "disbursement_issue_amount": 200,
    "prefixed_interest_rate": {
        "annual_rate": 3.81790482,
        "daily_rate": 0.0043771607,
        "interest_base": {
            "enumerator": "calendar_days",
            "year_days": 360
        },
        "monthly_rate": 0.14
    },
    "fine_configuration": {
        "contract_fine_rate": 0.02,
        "fine_delay_rate": {
            "annual_rate": 4.35025011,
            "daily_rate": 0.0046696,
            "interest_base": {
                "enumerator": "calendar_days",
                "year_days": 360
            },
            "monthly_rate": 0.15
        }
    },
    "attached_documents": [
        {
            "document_key": "494598fd-c226-4332-a500-591ae3884673",
            "document_url": "https://storage.googleapis.com/sandbox-doc-api/documents/494598fd-c226-4332-a500-591ae3884673/3d684e68e7df4e557d0480d98e26be92.jpg",
            "signature_url": null,
            "document_type": "document_identification",
            "signature_required": false,
            "signed": false
        },
        {
            "document_key": "494598fd-c226-4332-a500-591ae3884673",
            "document_url": "https://storage.googleapis.com/sandbox-doc-api/documents/494598fd-c226-4332-a500-591ae3884673/3d684e68e7df4e557d0480d98e26be92.jpg",
            "signature_url": null,
            "document_type": "document_identification_back",
            "signature_required": false,
            "signed": false
        },
        {
            "document_key": "c8b191cb-7b90-4e37-9280-397a597babc1",
            "document_url": "https://storage.googleapis.com/sandbox-doc-api/documents/c8b191cb-7b90-4e37-9280-397a597babc1/RAFAELAEBENJAMINFINANCEIRALTDA-ALAN_MATHISON_TURING-CCB-TIK11267101212-20251027170925.pdf",
            "signature_url": "https://storage.googleapis.com/sandbox-doc-api/documents/c8b191cb-7b90-4e37-9280-397a597babc1/RAFAELAEBENJAMINFINANCEIRALTDA-ALAN_MATHISON_TURING-CCB-TIK11267101212-20251027170925_signed.pdf",
            "document_type": "ccb_pre_price_days",
            "signature_required": true,
            "signed": true
        }
    ]
}

STATUS

400

Response Body

{
  "data": "{\"title\": \"Bad Request\", \"description\": \"Invalid request body.\", \"translation\": \"Corpo da requisição inválido.\", \"extra_fields\": {}, \"code\": \"LEG000069\"}"
}

Homologation Roadmap - BNPL

Summary​

1. Document upload​

Request Body Upload​

Exemplo de chamada​

2. Debt Simulation​

Request Debt Simulation​

Request Body Details​

Response Debt Simulation​

Response Body Details​

Object Fees​

Object Installments​

Object Interest Rate​

Object Tax Configuration​

Enumeratores​

Enumerator Person Type​

Enumerator Account Type​

Enumerator Amount Type​

Enumerator Interest Type​

Enumerator Credit Operation Type​

Enumerator Interest Base​

Enumerator Fee Type​

Enumerator Origin Type​

3. Debt Issuance for Individuals​

Request​

Response​

4. Webhooks​

Signature webhook​

Disbursement webhook​

Cancelation webhook​

5. Debt installments​

Examples​

6. Debt inquiry​

Path params​

Response​

Summary

1. Document upload

Request Body Upload

Exemplo de chamada

2. Debt Simulation

Request Debt Simulation

Request Body Details

Response Debt Simulation

Response Body Details

Object Fees

Object Installments

Object Interest Rate

Object Tax Configuration

Enumeratores

Enumerator Person Type

Enumerator Account Type

Enumerator Amount Type

Enumerator Interest Type

Enumerator Credit Operation Type

Enumerator Interest Base

Enumerator Fee Type

Enumerator Origin Type

3. Debt Issuance for Individuals

Request

Response

4. Webhooks

Signature webhook

Disbursement webhook

Cancelation webhook

5. Debt installments

Examples

6. Debt inquiry

Path params

Response