Homologation Roadmap - BNPL

Summary

This document guides clients through integrating Buy Now Pay Later (BNPL) with the QI Tech platform. It outlines the essential steps and provides answers to common questions.

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

METHOD

POST

Response Body

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

Atenção

Remember to save the document_key, as this key is required to query the document.

API call example

Example for uploading an image from a 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" # This key is an example; please use your own key.
CLIENT_PRIVATE_KEY = ''''
-----BEGIN EC PRIVATE KEY-----
MIHbAgEBBEHh1hIeOPE5XNNhn6bxRAmVswsPZ0wZCmzVvP8Tl/LZK9ofVmRVGzll
srU1uezJEyHKYdOHrE2p52xUj+pHzjJvb6AHBgUrgQQAI6GBiQOBhgAEAAofUz1J
hBSOyGHLsnV9Sz0DSWmhl7U+ljqbfa8PKVFWSV3w16I1v2zME5/UzUhHn1gWsjnv
7/ekcLLAQbvqMPNXAfjIhFXLAPzqbB9iCuVua1v0Vgy52rBemOWrJka/Ws2bnKR8
h1N1OxOYeYr6C2jqMygBLktKMAs+282CEiEb4bIv
-----END EC PRIVATE KEY----- 
''' # This key is an example; please use your own key.

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):
    endpointeger= "/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 endpointeger= '/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-----`; // This key is an example; please use your own key.
  const api_key = '4c268c0a-53ff-429b-92b6-47ef98a6d89a' // This key is an example; please use your own key.

  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*	string	Type of credit agreement	Credit Operation Type Enumerator
disbursed_issue_amount*	float	The value actually released to the borrower	15,2
disbursement_date*	string	The specific date the loan funds are made available	10
first_due_date*	string	Due date of the first installment	10
force_installments_on_workdays*	boolean	If true, ensures all installment due dates are moved to the next business day	5
interest_type*	string	Amortization method	Interest Type Enumerator
issuer_person_type*	string	Defines whether the issuer is an individual (natural person) or a legal entity (corporation/business)	Person Type Enumerator
monthly_interest_rate*	float	The percentage charged on a principal balance over a one-month period	10,6
number_of_installments*	integer	Number of installments	3
principal_amortization_month_period*	integer	Period, in months, between installments	1

Response Debt Simulation

STATUS

200

Response Body

    {
        "disbursement_date": "2025-09-24",
        "issue_amount": 2821.32,
        "interest_type": "pre_price_days",
        "assignment_amount": 2829.78,
        "base_iof": 10.6,
        "total_iof": 21.32,
        "additional_iof": 10.72,
        "cet": 5.09,
        "annual_cet": 81.39,
        "first_due_date": "2025-10-24",
        "disbursed_amount": 2800,
        "prefixed_interest_rate": {
            "annual_rate": 0.6935459998,
            "daily_rate": 0.0014644728,
            "interest_base": "calendar_days",
            "monthly_rate": 0.04488
        },
        "tax_configuration": {
            "base_rate": 8.2e-05,
            "additional_rate": 0.0038
        },
        "fees": [
            {
                "amount": 0.3,
                "fee_amount": 8.46,
                "amount_type": "percentage",
                "fee_type": "spread",
                "type": "internal"
            }
        ],
        "installments": [
            {
                "due_date": "2025-10-24",
                "amount": 1507.4,
                "due_principal": 2821.32,
                "due_interest": 0,
                "has_interest": true,
                "period": 1,
                "period_workdays": 1.1,
                "calendar_days": 30,
                "workdays": 22,
                "installment_number": 1,
                "period_to_disbursement": 1,
                "prefixed_amount": 126.62083829,
                "period_workdays_to_disbursement": 1.1,
                "calendar_days_to_disbursement": 30,
                "workdays_to_disbursement": 22,
                "tax_amount": 3.39671674,
                "principal_amortization_amount": 1380.77916171
            },
            {
                "due_date": "2025-11-24",
                "amount": 1507.4,
                "due_principal": 1440.54083829,
                "due_interest": 0,
                "has_interest": true,
                "period": 1,
                "period_workdays": 1,
                "calendar_days": 31,
                "workdays": 20,
                "installment_number": 2,
                "period_to_disbursement": 2,
                "prefixed_amount": 66.85916171,
                "period_workdays_to_disbursement": 2.1,
                "calendar_days_to_disbursement": 61,
                "workdays_to_disbursement": 42,
                "tax_amount": 7.20558527,
                "principal_amortization_amount": 1440.54083829
            }
        ]
    }

Response Body Details

Field	Type	Description
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	string	Disbursement date of the operation
installments	array	Object Installments - Installments of the operation
interest_type	string	Enumerator Interest Type - Amortization method and interest calculation method
additional_iof	float	A fixed-rate tax applied to the transaction principal, independent of the duration of the credit operation
base_iof	float	The taxable amount or principal value used as the basis for calculating the Tax on Financial Operations
total_iof	float	The total amount of Tax on Financial Operations applied to the transaction
issue_amount	float	Issue/nominal value of the credit operation
tax_configuration	object	Object Tax Configuration - Rate iof values
first_due_date	string	Due date of the first installment
prefixed_interest_rate	object	Object Interest Rate - Nominal interest rate

3.Debt issuance for natural persons

This endpoint issues the debt and processes the contract signature via opt-in. Disbursement occurs automatically immediately after issuance. Pre-registration is not required; simply provide the borrower's details during the debt request.

Request

ENDPOINT

/signed_debt

METHOD

POST

Request Body

{
    "additional_data": {
        "contract": {
            "contract_number": "TIK11267101100",
            "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": 200,
        "fine_configuration": {
            "contract_fine_rate": 0.02,
            "monthly_rate": 0.15,
            "interest_base": "calendar_days"
        },
        "interest_grace_period": 0,
        "disbursement_date": "2026-02-06",
        "first_due_date": "2026-03-06",
        "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": "Accout Name"
        }
    ],
    "requester_identifier_key":"6b558426-6b6c-4c9e-bfb3-5734fe45a651",
    "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",
        "is_pep":false,
        "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",
        "document_identification_number": "96969879003",
        "name": "Alan Mathison Turing"
    }
}

Request Body Details

Field	Type	Description	Max. Char.
borrower *	object	Borrower Object - The debtor of the credit operation	Borrower Object
disbursement_bank_account *	object	Technical details of the bank account where the operation funds will be deposited.	Disbursement Bank Account Object
financial *	object	Contains all financial details and calculation parameters for the operation.	Financial Object
purchaser_document_number *	string	Assignee's Tax ID – The buyer of the credit operation (FIDC/Receivables Investment Fund).	14
additional_data *	object	Assignee's Tax ID – The buyer of the credit operation (FIDC/Receivables Investment Fund).	Additional Data Object

Borrower Object

Field	Type	Description	Max. Char.
name *	string	Full name of the borrower	100
email	string	Borrower's electronic mail address	254
phone	object	Borrower's contact telephone details	Phone Object
is_pep *	boolean	Politically Exposed Person (PEP) indicator	5
address *	object	Borrower's residential address details	Address Object
role_type *	enum	The role of the person in the operation. Default: issuer	-
birth_date *	date	Borrower's date of birth (Format: "YYYY-MM-DD")	10
mother_name *	string	Borrower's mother's full name	100
nationality	string	Borrower's nationality	50
person_type *	string	Person classification	7
individual_document_number *	string	Borrower's Tax ID (CPF) - numbers only	11
document_identification *	string	DOCUMENT_KEY of the uploaded identification document (RG or CNH)	36
document_identification_back	string	DOCUMENT_KEY of the uploaded back side of the identification document	36

Address Object

Field	Type	Description	Max. Char.
city *	string	City name of the address	100
state *	string	State abbreviation (two uppercase characters)	2
number *	string	Street number	10
street *	string	Street name	100
complement *	string	Address complement (free text)	100
postal_code *	string	Postal code (CEP) - numbers only	8
neighborhood *	string	Neighborhood or district name	100

Phone Object

Field	Type	Description	Max. Char.
number *	string	Subscriber's phone number	9
area_code *	string	Two-digit regional area code (e.g., "11")	2
country_code *	string	International dialing code (e.g., "055")	3

Disbursement Bank Account Object

Field	Type	Description	Max. Char.
name	string	Account holder's full name	50
document_number	string	Account holder's Tax ID (CPF)	11
bank_code *	string	Financial institution's COMPE code	3
branch_number *	string	Branch number (do not include the branch check digit!)	4
account_number *	string	Account number (do not include the account check digit!)	10
account_digit *	string	Account check digit (use zero instead of letters)	1
account_type	enum	Account Type Enumerator - Type of the bank account	Account Type Object

Additional Data Object

Field	Type	Description	Max. Char.
contract_number *	string	The unique identifier or reference number of the contract	12
signed *	boolean	Indicates if the contract has been successfully signed	5
signatures *	array	List of digital signature evidence objects (Opt-in)	-
name *	string	Full name of the signer	255
document_number *	string	Signer's tax identification number (CPF)	11
email *	string	Electronic mail address of the signer	100
area_code *	string	Two-digit regional area code (e.g., "11")	2
number *	string	Subscriber's phone number	9
country_code *	string	International dialing code (e.g., "055")	3
ip_address *	string	The IP address used during the signature process	45
timestamp *	string	Date and time of the signature (DD-MM-YYYY HH:mm:ss)	19
file_url *	string	Direct link to the signed contract document (PDF)	2048
file_type *	string	Format of the signature file (e.g., "pdf")	4
long *	string	Geographic longitude coordinate of the signature location	20
lat *	string	Geographic latitude coordinate of the signature location	20
fingerprint_device	string	Unique digital identifier of the device used	-

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": "a6dbf441-31b0-44df-9bb8-593553de2c45",
    "status": "issued",
    "event_datetime": "2026-02-10 00:01:20",
    "data": {
        "borrower": {
            "name": "Alan Mathison Turing",
            "document_number": "96969879003",
            "related_party_key": "6995ff6e-27c2-47e9-b4bf-640934b56b23"
        },
        "contract": {
            "document_key": null,
            "number": "TIK11267101100",
            "urls": [],
            "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": "6b558426-6b6c-4c9e-bfb3-5734fe45a651",
        "iof_charge_method": "financed",
        "collaterals": [],
        "contract_fees": [
            {
                "fee_type": "spread",
                "fee_amount": 0.6
            }
        ],
        "external_contract_fees": [],
        "external_contract_fee_amount": 0,
        "net_external_contract_fee_amount": 0,
        "contract_fee_amount": 0.6,
        "issue_amount": 201.49,
        "assignment_amount": 202.09,
        "cet": "7,6600%",
        "annual_cet": "142,5744%",
        "number_of_installments": 2,
        "base_iof": 0.73,
        "additional_iof": 0.76,
        "total_iof": 1.49,
        "ipoc_code": "324025020203196969879003TIK11267101100",
        "prefixed_interest_rate": {
            "annual_rate": 1.252191589,
            "created_at": "2026-02-10T00:01:18",
            "daily_rate": 0.0022578334,
            "interest_base": "calendar_days",
            "monthly_rate": 0.07
        },
        "installments": [
            {
                "accrual_reference_date": null,
                "additional_costs": [],
                "advanced_paid_amount": 0,
                "bank_slip_key": null,
                "business_due_date": "2026-03-06",
                "calendar_days": 28,
                "digitable_line": null,
                "due_date": "2026-03-06",
                "due_interest": 0,
                "due_principal": 201.49,
                "fine_amount": null,
                "has_interest": true,
                "installment_history": [],
                "installment_key": "5c121fac-20f8-4481-b7b6-d0647a0ce524",
                "installment_number": 1,
                "installment_payment": [],
                "installment_status": "created",
                "installment_type": "principal",
                "original_due_principal": 201.49,
                "original_pre_fixed_amount": 13.13403553,
                "original_principal_amortization_amount": 97.92596447,
                "original_total_amount": 111.06,
                "paid_amount": 0,
                "paid_at": null,
                "post_fixed_amount": 0,
                "pre_fixed_amount": 13.13403553,
                "principal_amortization_amount": 97.92596447,
                "qr_code_key": null,
                "qr_code_url": null,
                "renegotiation_proposal_key": null,
                "tax_amount": 0.22483801,
                "total_accrual_amount": null,
                "total_amount": 111.06,
                "total_paid_amount": 0,
                "workdays": 18
            },
            {
                "accrual_reference_date": null,
                "additional_costs": [],
                "advanced_paid_amount": 0,
                "bank_slip_key": null,
                "business_due_date": "2026-04-06",
                "calendar_days": 31,
                "digitable_line": null,
                "due_date": "2026-04-06",
                "due_interest": 0,
                "due_principal": 103.56403553,
                "fine_amount": null,
                "has_interest": true,
                "installment_history": [],
                "installment_key": "a8a21d7a-481e-43ba-b115-fd89253bcde9",
                "installment_number": 2,
                "installment_payment": [],
                "installment_status": "created",
                "installment_type": "principal",
                "original_due_principal": 103.56403553,
                "original_pre_fixed_amount": 7.49596447,
                "original_principal_amortization_amount": 103.56403553,
                "original_total_amount": 111.06,
                "paid_amount": 0,
                "paid_at": null,
                "post_fixed_amount": 0,
                "pre_fixed_amount": 7.49596447,
                "principal_amortization_amount": 103.56403553,
                "qr_code_key": null,
                "qr_code_url": null,
                "renegotiation_proposal_key": null,
                "tax_amount": 0.5010428,
                "total_accrual_amount": null,
                "total_amount": 111.06,
                "total_paid_amount": 0,
                "workdays": 20
            }
        ],
        "total_pre_fixed_amount": 20.63
    }
}

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

{
    "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

{
    "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. Cancellation

Cancel debt before disbursement

Request Body

ENDPOINT

/debt/DEBT-KEY/cancel

MÉTODO

PATCH

Path params

Field	Type	Description	Max. Char.
`debt_key` *	string	Debt unique identifier key returned at the moment of the credit operation creation.	32

Response Body

STATUS

200

Response Body

{
  "data": [
    {
      "borrower": {
        "document_number": "68394265057",
        "name": "Xuxa Meneguel"
      },
      "contract_fee_amount": 5.56,
      "installments": [
        {
          "bank_slip_key": null,
          "calendar_days": 57,
          "due_date": "2020-09-30",
          "due_principal": -0.00217819,
          "fine_amount": null,
          "has_interest": true,
          "installment_key": "28eb5907-ed25-4a86-bb9d-b6dc944f13df",
          "installment_number": 1,
          "installment_status": "opened",
          "installment_type": "principal",
          "paid_amount": 0,
          "post_fixed_amount": 0,
          "pre_fixed_amount": 268.75782181,
          "principal_amortization_amount": 1111.9,
          "tax_amount": 0,
          "total_amount": 1380.66,
          "workdays": 40
        }
      ],
      "operation_key": "7986dcc7-4331-478f-af47-adfbdf7f4a36",
      "status": "opened"
    }
  ],
  "pagination": {
    "current_page": 1,
    "next_page": null,
    "rows_per_page": 100,
    "total_pages": 1,
    "total_rows": 55
  }
}

Debt cancellation within seven days after disbursement

Request Body

ENDPOINT

/debt/reversal

MÉTODO

POST

Request Body

{
    "contract_number": "0000049343/TW"
}

Request Body Details

Field	Type	Description	Max. Char.
`contract_number` *	string	Contract Number of the CCB

Response Body

STATUS

200

Response Body

{
  "amount": "2026.93",
  "copy_paste_pix": "00020126930014br.gov.bcb.pix2571qrcode-h.dev.qitech.app/bacen/cobv/dece8d3e-32ce-439e-8204000053039865802BR5925Joao61080150400062070503***63046ECD",
  "expiration_date": "2022-09-28",
  "payer_document_number": "000000000008",
  "payer_name": "Teste",
  "reversal_key": "f98a1b7c-5e3c-4e6f-8887-c7fedfa0d5b5",
  "status": "waiting_payment"
}

6. Debt inquiry

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

ENDPOINT

/v2/credit_operation/CREDIT-OPERATION-KEY

METHOD

GET

Path params

Field	Type	Description	Max. Char.
`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\"}"
}

7. Assignment Inquiry

Assignment Confirmation Webhook

This webhook is triggered to notify the client that the assignment process has been initiated. It provides the essential metadata required to track the assignment.

Response Body

{
  "assignment_key": "77997168-5d61-430f-b5ae-08eb3d7b8c0e",
  "term_of_assignment_url": "https://example.com/assignment.pdf",
  "number_of_items": 5,
  "total_amount": 120000.00,
  "reference_date": "2026-02-06"
}

Field	Type	Description	Maximum lenght
assignment_key	string	Unique identifier for the assignment operation	36
term_of_assignment_url	string	URL to download the Term of Assignment (PDF)	2048
number_of_items	integer	Total number of credit operations (items) included in this assignment	5
total_amount	float	The sum of the present value of all items in the assignment	15,2
reference_date	string	The base date used for the assignment calculations (YYYY-MM-DD)	10

To query a specific assignment, the client can perform a GET request on the endpoint using the assignment identifier key (assignment_key).

Request Body

ENDPOINT

/v2/assignment/[assignment_key]

METHOD

GET

Params

Campo	Descrição
`assignment_key`	Assignment unique identifier key

Response

STATUS

200

Response Body

{
  "assignment_key": "77997168-5d61-430f-b5ae-08eb3d7b8c0e",
  "creation_datetime": "2023-10-01T12:00:00",
  "reference_date": "2023-10-01",
  "total_amount": 120000,
  "number_of_items": 5,
  "term_of_assignment_url": "https://example.com/assignment.pdf",
  "status": "settled",
  "signable_term_url": "https://example.com/signable_term.pdf"
}

To query the contracts within an assignment, use a GET request on the endpoint with the same assignment_key.

Request Body

ENDPOINT

/v2/assignment/[assignment_key]/assignment_items

METHOD

GET

Params

Campo	Descrição
`assignment_key`	Assignment unique identifier key

The response is a paginated list containing information for each contract in the assignment (status 200):

Response Body

STATUS

200

Response Body

{
    "data": [
        {
            "assignment_item_key": "439b1257-82ac-4741-a416-a4428a9a7327",
            "control_number": "0001",
            "credit_operation_key": "d7f2ba40-30ea-4462-890c-6a99a7d85659",
            "issuer_name": "João Santos",
            "issuer_document_number": "12345678912",
            "issue_amount": 50000,
            "disbursed_amount": 45000,
            "disbursement_date": "2023-01-01",
            "number_of_installments": 12,
            "contract_number": "XXX182938",
            "present_amount": 48000,
            "status": "settled",
            "endorsement_url": "https://example.com/endorsement.pdf",
            "purchaser_document_number": "1234567890001"
        }
    ],
    "pagination": {
        "page": 1,
        "page_size": 10
    }
}

8. Technical Specifications and Enums

Fees Object

Campo	Tipo	Description
amount	float	Fee amount (in percentage or absolute value, depending on the value provided in the amount_type field)
amount_type	enum	Fee value unit
fee_amount	float	Absolute value of the fee charged in the operation
fee_type	string	Type of fee charged in the operation
type	string	Source of the fee charged in the operation

Installments Object

Campo	Tipo	Description
calendar_days	integer	Number of calendar days between installments
due_date	string	Installment due date in calendar days
due_principal	float	Remaining principal on the installment due date before its payment
has_interest	boolean	true - If true, interest applies to the installment
installment_number	integer	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	integer	Calendar days to disbursement
workdays	integer	Business days between installments
workdays_to_disbursement	integer	Business days until disbursement

Interest Rate Object

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

Tax Configuration Object

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

Enumeratores

Person Type Enumerator

Enumerator	Description
legal	Legal person
natural	Natural person

Account Type Enumerator

Enumerator	Description
checking_account	Checking account

Amount Type Enumerator

Enumerator	Description
absolute	Absolute value
percentage	Percentage value

Interest Type Enumerator

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

Credit Operation Type Enumerator

Enumerator	Description
ccb	Bank Credit Note

Interest Base Enumerator

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

Fee Type Enumerator

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

Enumerator	Description
spread	Premium included in the credit operation's acquisition value
spread_ted_fee	Premium on the TED transfer fee

Origin Type Enumerator

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

Enumerator	Description
internal	Internal fee
external	External fee

Homologation Roadmap - BNPL

Summary​

1. Document upload​

Request Body Upload​

API call example​

2. Debt Simulation​

Request Debt Simulation​

Request Body Details​

Response Debt Simulation​

Response Body Details​

3.Debt issuance for natural persons​

Request​

Request Body Details​

Borrower Object​

Address Object​

Phone Object​

Disbursement Bank Account Object​

Additional Data Object​

Response​

4. Webhooks​

Signature webhook​

Disbursement webhook​

Cancelation webhook​

5. Cancellation​

Cancel debt before disbursement​

Request Body​

Path params​

Response Body​

Debt cancellation within seven days after disbursement​

Request Body​

Request Body Details​

Response Body​

6. Debt inquiry​

Path params​

Response​

7. Assignment Inquiry​

Assignment Confirmation Webhook​

Request Body​

Params​

Response​

Request Body​

Params​

Response Body​

8. Technical Specifications and Enums​

Fees Object​

Installments Object​

Interest Rate Object​

Tax Configuration Object​

Enumeratores​

Person Type Enumerator​

Account Type Enumerator​

Amount Type Enumerator​

Interest Type Enumerator​

Credit Operation Type Enumerator​

Interest Base Enumerator​

Fee Type Enumerator​

Origin Type Enumerator​

Summary

1. Document upload

Request Body Upload

API call example

2. Debt Simulation

Request Debt Simulation

Request Body Details

Response Debt Simulation

Response Body Details

3.Debt issuance for natural persons

Request

Request Body Details

Borrower Object

Address Object

Phone Object

Disbursement Bank Account Object

Additional Data Object

Response

4. Webhooks

Signature webhook

Disbursement webhook

Cancelation webhook

5. Cancellation

Cancel debt before disbursement

Request Body

Path params

Response Body

Debt cancellation within seven days after disbursement

Request Body

Request Body Details

Response Body

6. Debt inquiry

Path params

Response

7. Assignment Inquiry

Assignment Confirmation Webhook

Request Body

Params

Response

Request Body

Params

Response Body

8. Technical Specifications and Enums

Fees Object

Installments Object

Interest Rate Object

Tax Configuration Object

Enumeratores

Person Type Enumerator

Account Type Enumerator

Amount Type Enumerator

Interest Type Enumerator

Credit Operation Type Enumerator

Interest Base Enumerator

Fee Type Enumerator

Origin Type Enumerator