Webhooks
Throughout the bankslip life cycle, the system sends webhooks to notify the integrating partner about status changes. All the events use the bankslip_collection.bankslip_status_change type.
Webhook configuration
To receive webhooks, you need to have a callback URL configured with QI Tech. Contact integracao@qitech.com.br to set it up.
Webhook structure
All the bankslip webhooks follow the same base structure:
| Field | Type | Description |
|---|---|---|
webhook_type | string | Webhook type. Always bankslip_collection.bankslip_status_change. |
webhook_datetime | string | Date and time of the event in the ISO 8601 format. |
data | object | Data of the event. See the table below. |
data attributes
| Field | Type | Description |
|---|---|---|
bankslip_key | string (UUID) | Unique identifier of the bankslip. |
bankslip_configuration_key | string (UUID) | Identifier of the bankslip configuration. |
bankslip_profile_key | string (UUID) | Identifier of the bankslip profile. |
status | string | Current status of the bankslip. |
fund_class | object | Data of the fund class associated with the bankslip. |
external_participant_control_number | string | External control number of the participant. |
participant_control_number | string | Internal control number of the participant. |
face_value | float | Face value of the bankslip. |
due_date | string | Due date in the YYYY-MM-DD format. |
borrower | object | Data of the drawee (debtor). |
assignor | object | Data of the assignor. |
settlement_instructions | array | List of settlement instructions linked to the bankslip. |
our_number | integer | (Optional) "Nosso número" assigned by the issuing bank. |
our_number_digit | string | (Optional) Check digit of the "nosso número". |
order_number | string | (Optional) Order number. |
digitable_line | string | (Optional) Digitable line of the bankslip. Present when available after the registration. |
barcode | string | (Optional) Barcode of the bankslip. Present when available after the registration. |
fund_class attributes
| Field | Type | Description |
|---|---|---|
document_number | string | CNPJ of the fund class. |
fund_class_key | string (UUID) | Identifier of the fund class. |
name | string | Name of the fund class. |
settlement_instructions attributes
| Field | Type | Description |
|---|---|---|
asset_key | string (UUID) | Identifier of the associated asset. |
asset_type | string | Asset type (e.g. duplicata_mercantil, duplicata_servicos, ccb). |
issue_date | string | Issue date of the asset in the YYYY-MM-DD format. |
maturity_date | string | Maturity date of the asset in the YYYY-MM-DD format. |
face_value | float | Face value of the asset. |
status | string | Status of the settlement instruction. |
external_id | string | (Optional) External identifier of the asset. |
installment_number | integer | (Optional) Installment number, when applicable (e.g. installment CCBs). |
order_number | string | (Optional) Order number of the instruction. |
Events by status
Bankslip Registration
STATUS
pending_registrationSent when a bankslip is created and submitted to the issuing bank for registration. The bankslip awaits confirmation from the banking institution. Depending on the bank, the digitable_line, barcode and our_number fields may be present when the bank returns them immediately upon registration. For other banks, those fields are filled in only after the confirmation via the return file.
Webhook Body
{
"webhook_type": "bankslip_collection.bankslip_status_change",
"webhook_datetime": "2026-04-15T12:55:35Z",
"data": {
"bankslip_key": "7a26c259-1b1f-4d73-9a5b-48230022b8f2",
"bankslip_configuration_key": "b6b4ff70-917c-4003-bc4d-ebc4ccdd606c",
"bankslip_profile_key": "5666937c-944a-44c6-98e6-3591f99fe4ff",
"status": "pending_registration",
"fund_class": {
"document_number": "17.645.194/0001-85",
"fund_class_key": "d81118d0-527b-45b0-8c60-76e9d3ab3aa3",
"name": "Nome da Classe do Fundo"
},
"external_participant_control_number": "XO0QYVBF1JU9LFBBKGT7XYQV9",
"participant_control_number": "XO0QYVBF1JU9LFBBKGT7XYQV9",
"face_value": 629.33,
"due_date": "2026-09-17",
"borrower": {
"document_number": "631.430.668-06",
"name": "Nome do Sacado",
"person_type": "natural_person",
"address": {
"postal_code": "05425-020"
}
},
"assignor": {
"name": "Nome do Cedente",
"document_number": "37.341.966/0001-00",
"person_type": "legal_person"
},
"settlement_instructions": [
{
"asset_key": "22fc5c95-3622-48ad-b26a-99f8d0499e69",
"external_id": "758638e4-6fe6-4b69-8799-30728ca16a22",
"asset_type": "duplicata_mercantil",
"issue_date": "2025-01-17",
"maturity_date": "2026-09-17",
"face_value": 629.33,
"status": "pending_bankslip_payment"
}
],
"our_number": 10507,
"our_number_digit": "0"
}
}
Bankslip Registered
STATUS
registeredSent when the issuing bank confirms the registration of the bankslip. From this moment on, the bankslip is ready for payment by the drawee. In this webhook, the digitable_line, barcode, our_number and our_number_digit fields will be present.
Webhook Body
{
"webhook_type": "bankslip_collection.bankslip_status_change",
"webhook_datetime": "2026-04-15T13:10:22Z",
"data": {
"bankslip_key": "7a26c259-1b1f-4d73-9a5b-48230022b8f2",
"bankslip_configuration_key": "b6b4ff70-917c-4003-bc4d-ebc4ccdd606c",
"bankslip_profile_key": "5666937c-944a-44c6-98e6-3591f99fe4ff",
"status": "registered",
"fund_class": {
"document_number": "17.645.194/0001-85",
"fund_class_key": "d81118d0-527b-45b0-8c60-76e9d3ab3aa3",
"name": "Nome da Classe do Fundo"
},
"external_participant_control_number": "XO0QYVBF1JU9LFBBKGT7XYQV9",
"participant_control_number": "XO0QYVBF1JU9LFBBKGT7XYQV9",
"face_value": 629.33,
"due_date": "2026-09-17",
"borrower": {
"document_number": "631.430.668-06",
"name": "Nome do Sacado",
"person_type": "natural_person",
"address": {
"postal_code": "05425-020"
}
},
"assignor": {
"name": "Nome do Cedente",
"document_number": "37.341.966/0001-00",
"person_type": "legal_person"
},
"settlement_instructions": [
{
"asset_key": "22fc5c95-3622-48ad-b26a-99f8d0499e69",
"external_id": "758638e4-6fe6-4b69-8799-30728ca16a22",
"asset_type": "duplicata_mercantil",
"issue_date": "2025-01-17",
"maturity_date": "2026-09-17",
"face_value": 629.33,
"status": "pending_bankslip_payment"
}
],
"our_number": 10507,
"our_number_digit": "0",
"digitable_line": "03399.87654 32100.012345 67890.123456 1 00000000062933",
"barcode": "03391000000000629333987654321000123456789012345"
}
}
Bankslip Rejected
STATUS
rejectedSent when the issuing bank rejects the registration of the bankslip. The bankslip will not be available for payment and will not advance in the flow. The linked settlement instructions are also marked as rejected.
Webhook Body
{
"webhook_type": "bankslip_collection.bankslip_status_change",
"webhook_datetime": "2026-04-15T13:10:22Z",
"data": {
"bankslip_key": "7a26c259-1b1f-4d73-9a5b-48230022b8f2",
"bankslip_configuration_key": "b6b4ff70-917c-4003-bc4d-ebc4ccdd606c",
"bankslip_profile_key": "5666937c-944a-44c6-98e6-3591f99fe4ff",
"status": "rejected",
"fund_class": {
"document_number": "17.645.194/0001-85",
"fund_class_key": "d81118d0-527b-45b0-8c60-76e9d3ab3aa3",
"name": "Nome da Classe do Fundo"
},
"external_participant_control_number": "XO0QYVBF1JU9LFBBKGT7XYQV9",
"participant_control_number": "XO0QYVBF1JU9LFBBKGT7XYQV9",
"face_value": 629.33,
"due_date": "2026-09-17",
"borrower": {
"document_number": "631.430.668-06",
"name": "Nome do Sacado",
"person_type": "natural_person",
"address": {
"postal_code": "05425-020"
}
},
"assignor": {
"name": "Nome do Cedente",
"document_number": "37.341.966/0001-00",
"person_type": "legal_person"
},
"settlement_instructions": [
{
"asset_key": "22fc5c95-3622-48ad-b26a-99f8d0499e69",
"external_id": "758638e4-6fe6-4b69-8799-30728ca16a22",
"asset_type": "duplicata_mercantil",
"issue_date": "2025-01-17",
"maturity_date": "2026-09-17",
"face_value": 629.33,
"status": "rejected"
}
],
"our_number": 10507,
"our_number_digit": "0"
}
}
Bankslip Written Off
STATUS
written_offSent when the bankslip is written off at the issuing institution. This can happen upon a cancellation request.
Webhook Body
{
"webhook_type": "bankslip_collection.bankslip_status_change",
"webhook_datetime": "2026-04-15T14:30:00Z",
"data": {
"bankslip_key": "7a26c259-1b1f-4d73-9a5b-48230022b8f2",
"bankslip_configuration_key": "b6b4ff70-917c-4003-bc4d-ebc4ccdd606c",
"bankslip_profile_key": "5666937c-944a-44c6-98e6-3591f99fe4ff",
"status": "written_off",
"fund_class": {
"document_number": "17.645.194/0001-85",
"fund_class_key": "d81118d0-527b-45b0-8c60-76e9d3ab3aa3",
"name": "Nome da Classe do Fundo"
},
"external_participant_control_number": "XO0QYVBF1JU9LFBBKGT7XYQV9",
"participant_control_number": "XO0QYVBF1JU9LFBBKGT7XYQV9",
"face_value": 629.33,
"due_date": "2026-09-17",
"borrower": {
"document_number": "631.430.668-06",
"name": "Nome do Sacado",
"person_type": "natural_person",
"address": {
"postal_code": "05425-020"
}
},
"assignor": {
"name": "Nome do Cedente",
"document_number": "37.341.966/0001-00",
"person_type": "legal_person"
},
"settlement_instructions": [
{
"asset_key": "22fc5c95-3622-48ad-b26a-99f8d0499e69",
"external_id": "758638e4-6fe6-4b69-8799-30728ca16a22",
"asset_type": "duplicata_mercantil",
"issue_date": "2025-01-17",
"maturity_date": "2026-09-17",
"face_value": 629.33,
"status": "written_off"
}
],
"our_number": 10507,
"our_number_digit": "0",
"digitable_line": "03399.87654 32100.012345 67890.123456 1 00000000062933",
"barcode": "03391000000000629333987654321000123456789012345"
}
}