5 - Webhooks
Boleto status webhooks
For the communication between systems, webhooks are used, which offer real time updates on the Boleto status.
In the field Status the following returns are possible:
- Registered
- Paid
- Cancel
For the statuses registered, settled and canceled the field ReturnCode will be mapped, which describes the transaction applied on the Boleto. In it the following returns are possible:
- 02 - Boleto Entry Confirmed (Status: Registered)
- 03 - Entry Rejected (Status: Cancel)
- 06 - Normal Settlement (Status: Paid)
- 09 - Automatic retirement (Status: Cancel)
Boleto webhook status Registered
{
"BoletoDocumentNumber": "01031992222",
"InterestValue": 3,
"FineValue": 4,
"Barcode": "45097920600000002000067300000010001031992222",
"DueDate": "2022-12-21T00:00:00",
"DigitableLine": "45090067320000001000910319922224792060000000200",
"ReturnCodes": [
"02"
],
"PayerBankCode": null,
"PayerBankBranchCode": null,
"ReceiverTaxNumber": "33445235031",
"ReceiverName": "Rosalia",
"ReceiverBank": "450",
"ReceiverBankBranch": "0101",
"ReceiverBankAccount": "101112",
"ReceiverBankDigit": "8",
"CustomerMail": "[email protected]",
"CustomerName": "Fernanda",
"CustomerPhone": "85992679310",
"CustomerTaxNumber": "49154332427",
"RateValue": 1,
"AddressLine1": "Rua dois 234",
"AddressLine2": null,
"AddressCity": "Sao Paulo",
"AddressState": "SP",
"AddressNeighborhood": "Tatuapé",
"DivergentPaymentType": 3,
"MinPaymentValue": null,
"MaxPaymentValue": null,
"Products": [
{
"SellerPersonType": 0,
"SellerName": "Rosalia",
"SellerTaxNumber": "33445235031",
"ReceiverPersonType": 0,
"ReceiverName": "Rosalia",
"ReceiverTaxNumber": "33445235031",
"Reference": "1",
"ProductName": "Teste AutomaticType",
"ProductQty": 1,
"ProductValue": 2
}
],
"Tags": [
"Boleto",
"Teste?API"
],
"PartnerId": 668,
"DocumentNumber": "114387",
"Identifier": "38c01e13-db08-42bc-8e72-dc71482a065f",
"EntryId": 769274567,
"Status": "Registered",
"TotalValue": 2,
"PaymentDate": null,
"FineInterest": 0,
"DiscountValue": 0.2,
"DiscountValue2": 0.1,
"DiscountValue3": 0.05,
"DiscountDate": "2022-12-16T00:00:00",
"DiscountDate2": "2022-12-19T00:00:00",
"DiscountDate3": "2022-12-20T00:00:00",
"RebateValue": 0.8,
"IofValue": null,
"PaidValue": null,
"OtherValues": 0,
"CreditDate": "2022-12-15T14:14:39.777",
"OccurrenceDate": "2022-12-15T14:14:39.87",
"URL": "https://sandboxboletos.fitbank.com.br/pdf/2022-12-15/aqftuybl.pdf",
"BankCode": "450",
"BankBranch": null,
"BankAccount": null,
"BankAccountDigit": null,
"ReturnCode": "02",
"ReturnMessage": "Entrada Confirmada",
"PaymentProtocol": null,
"Method": "Boleto",
"BusinessUnitId": 673
}
Boleto webhook status Paid
{
"BoletoDocumentNumber": "01031992222",
"InterestValue": 3,
"FineValue": 4,
"Barcode": "45097920600000002000067300000010001031992222",
"DueDate": "2022-12-21T00:00:00",
"DigitableLine": "45090067320000001000910319922224792060000000200",
"ReturnCodes": [
"02",
"06"
],
"PayerBankCode": null,
"PayerBankBranchCode": null,
"ReceiverTaxNumber": "33445235031",
"ReceiverName": "Rosalia",
"ReceiverBank": "450",
"ReceiverBankBranch": "0101",
"ReceiverBankAccount": "101112",
"ReceiverBankDigit": "8",
"CustomerMail": "[email protected]",
"CustomerName": "Fernanda",
"CustomerPhone": "85992679310",
"CustomerTaxNumber": "49154332427",
"RateValue": 1,
"AddressLine1": "Rua dois 234",
"AddressLine2": null,
"AddressCity": "Sao Paulo",
"AddressState": "SP",
"AddressNeighborhood": "Tatuapé",
"DivergentPaymentType": 3,
"MinPaymentValue": null,
"MaxPaymentValue": null,
"Products": [
{
"SellerPersonType": 0,
"SellerName": "Rosalia",
"SellerTaxNumber": "33445235031",
"ReceiverPersonType": 0,
"ReceiverName": "Rosalia",
"ReceiverTaxNumber": "33445235031",
"Reference": "1",
"ProductName": "Teste AutomaticType",
"ProductQty": 1,
"ProductValue": 2
}
],
"Tags": [
"Boleto",
"Teste?API"
],
"PartnerId": 668,
"DocumentNumber": "114387",
"Identifier": "38c01e13-db08-42bc-8e72-dc71482a065f",
"EntryId": 769274567,
"Status": "Paid",
"TotalValue": 2,
"PaymentDate": "2022-12-15T14:17:11.66",
"FineInterest": 0,
"DiscountValue": 0.2,
"DiscountValue2": 0.1,
"DiscountValue3": 0.05,
"DiscountDate": "2022-12-16T00:00:00",
"DiscountDate2": "2022-12-19T00:00:00",
"DiscountDate3": "2022-12-20T00:00:00",
"RebateValue": 0.8,
"IofValue": null,
"PaidValue": 2,
"OtherValues": 0,
"CreditDate": "2022-12-15T14:17:11.66",
"OccurrenceDate": "2022-12-15T14:17:11.66",
"URL": "https://sandboxboletos.fitbank.com.br/pdf/2022-12-15/aqftuybl.pdf",
"BankCode": "450",
"BankBranch": null,
"BankAccount": null,
"BankAccountDigit": null,
"ReturnCode": "06",
"ReturnMessage": "Liquidação Normal",
"PaymentProtocol": null,
"Method": "Boleto",
"BusinessUnitId": 673
}
Boleto webhook status Cancel
Canceled after registration
{
"BoletoDocumentNumber": "01031992226",
"InterestValue": 3,
"FineValue": 4,
"Barcode": "45091920600000002000067300000010001031992226",
"DueDate": "2022-12-21T00:00:00",
"DigitableLine": "45090067320000001000910319922265192060000000200",
"ReturnCodes": [
"02"
],
"PayerBankCode": "450",
"PayerBankBranchCode": null,
"ReceiverTaxNumber": "33445235031",
"ReceiverName": "Rosalia",
"ReceiverBank": "450",
"ReceiverBankBranch": "0101",
"ReceiverBankAccount": "101112",
"ReceiverBankDigit": "8",
"CustomerMail": "[email protected]",
"CustomerName": "Fernanda",
"CustomerPhone": "85992679310",
"CustomerTaxNumber": "49154332427",
"RateValue": 1,
"AddressLine1": "Rua dois 234",
"AddressLine2": null,
"AddressCity": "Sao Paulo",
"AddressState": "SP",
"AddressNeighborhood": "Tatuapé",
"DivergentPaymentType": 4,
"MinPaymentValue": 14.00,
"MaxPaymentValue": null,
"Products": [
{
"SellerPersonType": 0,
"SellerName": "Rosalia",
"SellerTaxNumber": "33445235031",
"ReceiverPersonType": 0,
"ReceiverName": "Rosalia",
"ReceiverTaxNumber": "33445235031",
"Reference": "1",
"ProductName": "Teste AutomaticType",
"ProductQty": 1,
"ProductValue": 2
}
],
"Tags": [
"Boleto",
"Teste?API"
],
"PartnerId": 668,
"DocumentNumber": "114392",
"Identifier": "2fbbcee4-5c69-4c2b-a00d-e00f62350502",
"EntryId": 769289924,
"Status": "Cancel",
"TotalValue": 2,
"PaymentDate": null,
"FineInterest": 0,
"DiscountValue": 0.2,
"DiscountValue2": 0.1,
"DiscountValue3": 0.05,
"DiscountDate": "2022-12-16T00:00:00",
"DiscountDate2": "2022-12-19T00:00:00",
"DiscountDate3": "2022-12-20T00:00:00",
"RebateValue": 0.8,
"IofValue": null,
"PaidValue": null,
"OtherValues": 0,
"CreditDate": "2022-12-15T14:20:58.49",
"OccurrenceDate": "2022-12-15T14:20:58.537",
"URL": "https://sandboxboletos.fitbank.com.br/pdf/2022-12-15/cfds5jf1.pdf",
"BankCode": "450",
"BankBranch": null,
"BankAccount": null,
"BankAccountDigit": null,
"ReturnCode": "09",
"ReturnMessage": "Baixa Automática",
"PaymentProtocol": null,
"Method": "Boleto",
"BusinessUnitId": 673
}
Canceled before registration
{
"BoletoDocumentNumber": "01031992226",
"InterestValue": 3,
"FineValue": 4,
"Barcode": "45091920600000002000067300000010001031992226",
"DueDate": "2022-12-21T00:00:00",
"DigitableLine": "45090067320000001000910319922265192060000000200",
"ReturnCodes": [
"02"
],
"PayerBankCode": "450",
"PayerBankBranchCode": null,
"ReceiverTaxNumber": "33445235031",
"ReceiverName": "Rosalia",
"ReceiverBank": "450",
"ReceiverBankBranch": "0101",
"ReceiverBankAccount": "101112",
"ReceiverBankDigit": "8",
"CustomerMail": "[email protected]",
"CustomerName": "Fernanda",
"CustomerPhone": "85992679310",
"CustomerTaxNumber": "49154332427",
"RateValue": 1,
"AddressLine1": "Rua dois 234",
"AddressLine2": null,
"AddressCity": "Sao Paulo",
"AddressState": "SP",
"AddressNeighborhood": "Tatuapé",
"DivergentPaymentType": 4,
"MinPaymentValue": 14.00,
"MaxPaymentValue": null,
"Products": [
{
"SellerPersonType": 0,
"SellerName": "Rosalia",
"SellerTaxNumber": "33445235031",
"ReceiverPersonType": 0,
"ReceiverName": "Rosalia",
"ReceiverTaxNumber": "33445235031",
"Reference": "1",
"ProductName": "Teste AutomaticType",
"ProductQty": 1,
"ProductValue": 2
}
],
"Tags": [
"Boleto",
"Teste?API"
],
"PartnerId": 668,
"DocumentNumber": "114392",
"Identifier": "2fbbcee4-5c69-4c2b-a00d-e00f62350502",
"EntryId": 769289924,
"Status": "Cancel",
"TotalValue": 2,
"PaymentDate": null,
"FineInterest": 0,
"DiscountValue": 0.2,
"DiscountValue2": 0.1,
"DiscountValue3": 0.05,
"DiscountDate": "2022-12-16T00:00:00",
"DiscountDate2": "2022-12-19T00:00:00",
"DiscountDate3": "2022-12-20T00:00:00",
"RebateValue": 0.8,
"IofValue": null,
"PaidValue": null,
"OtherValues": 0,
"CreditDate": "2022-12-15T14:20:58.49",
"OccurrenceDate": "2022-12-15T14:20:58.537",
"URL": "https://sandboxboletos.fitbank.com.br/pdf/2022-12-15/cfds5jf1.pdf",
"BankCode": "450",
"BankBranch": null,
"BankAccount": null,
"BankAccountDigit": null,
"ReturnCode": "03",
"ReturnMessage": "Entrada Rejeitada",
"PaymentProtocol": null,
"Method": "Boleto",
"BusinessUnitId": 673
}
Description
| Parameter | Type | Description |
|---|---|---|
| BoletoDocumentNumber | String | Boleto Document Number |
| InterestValue | Decimal | Interest Value |
| FineValue | Decimal | Fine Value |
| Barcode | String | Boleto barcode |
| DueDate | DateTime | (yyyy/mm/dd) |
| DigitableLine | String | Digitable Line |
| ReturnCodes | String | Return Codes |
| PayerBankCode | String | Payer Bank Code |
| PayerBankBranchCode | String | PayerBank Branch Code |
| ReceiverTaxNumber | String | CPF/CNPJ of the Boleto receiver |
| ReceiverName | String | Legal Name of the Boleto receiver |
| ReceiverBank | String | Internal account receiver identification Bank |
| ReceiverBankBranch | String | Internal account receiver identification Bank Branch |
| ReceiverBankAccount | String | Internal account receiver identification Bank Account |
| ReceiverBankDigit | String | Internal account receiver identification Bank Account Digit |
| CustomerMail | String | E-mail of the payer |
| CustomerName | String | Payer name |
| CustomerPhone | String | Phone number of the payer |
| CustomerTaxNumber | String | CPF/CNPJ of the payer |
| RateValue | Decimal | 0 - Default 1 - Value send at the ratevalue |
| AddressLine1 | String | Payer address |
| AddressLine2 | String | Payer's Address additional |
| AddressCity | String | Payer City |
| AddressState | String | Payer State (Ex: SP, RJ, BA, etc) |
| AddressNeighborhood | String | Payer neighborhood |
| DivergentPaymentType | Integer | 1: Any value. 2: Between minimum and maximum 3: Do not accept payment with divergent value 4: Only the minimum value |
| MinPaymentValue | Decimal | Minimum value for boleto payment |
| MaxPaymentValue | Decimal | Maximum value for boleto payment |
| Products | - | - |
| SellerPersonType | Short | Type of Issuer of the boleto, 0 for Individuals and 1 for Company |
| SellerName | String | Legal Name of the Boleto issuing account |
| SellerTaxNumber | String | CPF/CNPJ of the Boleto issuing account |
| ReceiverPersonType | Short | Type of receiver of the boleto, 0 for Individuals and 1 for Company |
| ReceiverName | String | Legal Name of the Boleto receiver |
| ReceiverTaxNumber | String | CPF/CNPJ of the Boleto receiver |
| Reference | String | Transaction description |
| ProductName | String | Transaction description |
| ProductQty | Decimal | Transaction description |
| ProductValue | Decimal | Value of boleto |
| Tags | String | Tag List |
| PartnerId | Long | FitBank provided ID |
| DocumentNumber | String | Internal Document Number |
| Identifier | String | Identifier |
| EntryId | Long | Entry ID |
| Status | String | Status 3 - Registered Status 5 - Paid Status 7 - Cancelled |
| TotalValue | Decimal | Total Value |
| PaymentDate | DateTime | Payment Date |
| FineInterest | Decimal | Fine Interest |
| DiscountValue | Decimal | Discount Value |
| IofValue | Decimal | IOF Value |
| PaidValue | Decimal | Paid Value |
| OtherValues | Decimal | Other Values |
| CreditDate | DateTime | Payment Date |
| OccurrenceDate | DateTime | Payment Date |
| URL | String | URL of boleto |
| BankCode | String | Bank Code |
| BankBranch | String | Bank Branch |
| BankAccount | String | Bank Account |
| BankAccountDigit | String | Bank Account Digit |
| ReturnCode | String | Movement's Code |
| ReturnMessage | String | Movement's Message |
| PaymentProtocol | String | Payment Protocol |
| Method | String | Boleto |
| BusinessUnitId | Long | FitBank provided ID |
Boleto Pre-Settled Webhook
Boleto settlement follows a two-stage process. Initially, in the first stage, the institution issuing the boleto is notified of the payment made. Then, in the second stage, the payment is received and credited to the beneficiary customer's account.
The pre-settlement webhook sends a notification to the customer when FitBank receives the boleto payment information, which corresponds to the first stage of the process. These notifications are sent from 5am for boletos paid up to 11.59pm on the previous day and from 3pm for boletos paid up to 1.29pm on the current day.
This notification is not the settlement of the boletos, as the amounts are only credited to the beneficiary's account once payment has been received, in the second phase of the process. This follows the established settlement cycles, starting at 08:20 or 16:10.
{
"Boleto": {
"BoletoInfo": {
"DocumentNumber": "4900067",
"Status": "PreSettled",
"OcurrenceDate": "2024-04-04T17:31:45.367",
"Barcode": "45095900000000000010010000054524087700000000",
"OurNumber": "0010000000000000",
"ExternalNumber": "4957867"
},
"PaymentInfo": {
"PaymentChannel": "3",
"PaidValue": 0.01,
"PaymentDate": "2024-04-04T00:00:00",
"PayerBankCode": "450",
"PayerBankBranchCode": "0001"
}
},
"Identifier": "e449f322-4cbe-b727-8d5cc3e760ce",
"Method": "SendBoletoInWebhook",
"BusinessUnitId": 1259
}
Description
| Parameter | Type | Description |
|---|---|---|
| BoletoInfo | Object | Boleto Information |
| DocumentNumber | String | Boleto Document Number |
| Status | String | PreSettled |
| OcurrenceDate | String | Status change date |
| Barcode | String | Barcode |
| OurNumber | String | OurNumber |
| ExternalNumber | String | ExternalNumber |
| PaymentInfo | Object | Payment Information |
| PaymentChannel | String | Payment Channel 1 - Branches 2 - Self-service terminal 3 - Internet 5 - Correspondent banking 6 - Phone/Call Center 7 - Electronic Archive 8 - DDA 9 - Digital banking correspondent |
| PaidValue | Decimal | Paid Value, including interest, fines, discounts and rebates |
| PaymentDate | String | Payment Date |
| PayerBankCode | String | Payer Bank Code |
| PayerBankBranchCode | String | Payer Bank Branch Code |
| Identifier | String | Identifier |
| Method | String | SendBoletoInWebhook |
| BusinessUnitId | Long | FitBank provided ID |
Boleto Change Webhook
When you send a change statement, Webhooks are sent that contain the status of the change in the boleto. They are:
- Status 3 = Processed (Final success status);
- Status 5 = Instruction registration error.
You can send multiple change instructions for a boleto in a single request. In this case, a webhook will be sent for each instruction type.
Example: If the boleto contains 3 change instructions in one request, 3 webhooks will be sent
(To see the existing types of instructions, you can go to the link.)
ChangeRebateBoleto
{
"DocumentNumber": "2394793",
"Identifier": "5067dbfb-234d-9e86-1c460891",
"OldValue": "0.10",
"NewValue": "0.05",
"InstructionType": 0,
"Status": 3,
"TotalValue": 1,
"PartnerId": 678,
"Method": ChangeBoleto,
"BusinessUnitId": 1261
}
ChangeDueDateBoleto
{
"DocumentNumber": "2394603",
"Identifier": "f1716826-4bbb-4456-9ae515dc4",
"OldValue": "2023-01-31",
"NewValue": "2023-02-01",
"InstructionType": 1,
"Status": 3,
"TotalValue": 1,
"PartnerId": 678,
"Method": ChangeBoleto,
"BusinessUnitId": 1261
}
ChangePrincipalValueBoleto
{
"DocumentNumber": "2394627",
"Identifier": "85706573-e575-872a-2c96f4",
"OldValue": "1.00",
"NewValue": "2.0",
"InstructionType": 2,
"Status": 3,
"TotalValue": 2,
"PartnerId": 678,
"Method": ChangeBoleto,
"BusinessUnitId": 1261
}
Description
| Parameter | Type | Description |
|---|---|---|
| DocumentNumber | String | Boleto Document Number |
| Identifier | String | Identifier |
| OldValue | String | value before change |
| NewValue | String | value after change |
| InstructionType | Int | "Type of changed information ChangeRebateBoleto = 0 ChangeDueDateBoleto = 1, ChangePrincipalValueBoleto = 2" |
| Status | Int | "Change status Created = 0, Sending = 1, Sent = 2, Processed = 3, Canceled = 4, Error = 5" |
| TotalValue | Decimal | Boleto value |
| PartnerId | String | FitBank provided ID |
| Method | String | "ChangeBoleto" |
| BusinessUnitId | Long | FitBank provided ID |
Pay attention to status number
Each status number represents an instruction type.
Updated 16 days ago