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:
- 3 - Registered
- 5 - Paid
- 7 - Cancel
Registered boleto webhook
{
"Boleto": {
"BoletoInfo": {
"DocumentNumber": "1633565",
"Status": 3,
"OcurrenceDate": "2024-06-18T09:26:38.57",
"Barcode": "45097920600000002000067300000010001031992222",
"OurNumber": "0011001123333590",
"ExternalNumber": "2323233"
}
},
"ReturnMessage": "Entrada Confirmada",
"ReturnCode": "02",
"Identifier": "465656-ghfgfg-6465-wjaklv5",
"BusinessUnitId": "1261",
"Method": "UpdateBoletoInWebhook"
}
Paid boleto webhook
{
"Boleto": {
"BoletoInfo": {
"DocumentNumber": "1633565",
"Status": 5,
"OcurrenceDate": "2024-06-18T09:26:38.57",
"Barcode": "45097920600000002000067300000010001031992222",
"OurNumber": "0011001123333590",
"ExternalNumber": "2323233"
},
"PaymentInfo": {
"PrincipalValue": 10,
"PaymentChannel": 3,
"PaidValue": 8,
"Rebate": 2,
"Discount": 0,
"Fine": 0,
"Interest": 0,
"PaymentDate": "2024-06-17T00:00:00.00",
"CreditDate": "2024-06-18T09:26:38.57",
"PayerBankCode": 450,
"PayerBankBranchCode": 0001
}
},
"ReturnMessage": "Liquidação Normal",
"ReturnCode": "06",
"Identifier": "465656-ghfgfg-6465-wjaklv5",
"BusinessUnitId": "1261",
"Method": "UpdateBoletoInWebhook"
}
Canceled boleto webhook
Canceled after registration
{
"Boleto": {
"BoletoInfo": {
"DocumentNumber": "1633565",
"Status": 7,
"Reason": "Cancelamento de boleto processado",
"OcurrenceDate": "2024-06-18T09:26:38.57",
"Barcode": "45097920600000002000067300000010001031992222",
"OurNumber": "0011001123333590",
"ExternalNumber": "2323233"
}
},
"ReturnMessage": "Baixa automática",
"ReturnCode": "09",
"Identifier": "465656-ghfgfg-6465-wjaklv5",
"BusinessUnitId": "1261",
"Method": "UpdateBoletoInWebhook"
}
Canceled before registration
{
"Boleto": {
"BoletoInfo": {
"DocumentNumber": "1633565",
"Status": 7,
"Reason": "Cancelamento de boleto processado",
"OcurrenceDate": "2024-06-18T09:26:38.57",
"Barcode": "45097920600000002000067300000010001031992222",
"OurNumber": "0011001123333590",
"ExternalNumber": "2323233"
}
},
"ReturnMessage": "Entrada Rejeitada",
"ReturnCode": "03",
"Identifier": "465656-ghfgfg-6465-wjaklv5",
"BusinessUnitId": "1261",
"Method": "UpdateBoletoInWebhook"
}
Description - Boleto status webhooks
Parameter | Type | Description |
---|---|---|
Boleto | Object | - |
BoletoInfo | Object | - |
DocumentNumber | Decimal | Boleto Document Number |
Status | Decimal | 3 - Registered 5 - Paid 7 - Canceled |
Reason | String | Description of boleto cancellation. The "Reason" field is only sent for boletos with canceled status. |
OcurrenceDate | String | Date of occurrence: If boleto registered, then the registration date will be returned If boleto canceled, then the cancellation date will be returned If boleto paid, then the payment date will be returned |
Barcode | String | Barcode |
OurNumber | String | "Nosso Número" of the boleto |
ExternalNumber | String | External identification number |
PaymentInfo | Object | Only sent when the boleto status is Paid |
PrincipalValue | Decimal | Original boleto value |
PaymentChannel | Number | 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 |
Rebate | Decimal | Calculated rebate value |
Discount | Decimal | Calculated discount value |
Fine | Decimal | Calculated fine value |
Interest | Decimal | Calculated interest value |
PaymentDate | String | Payment Date |
CreditDate | String | Date of credit to the beneficiary's or final beneficiary's account |
PayerBankCode | Number | Boleto paying bank code |
PayerBankBranchCode | String | Branch of the paying bank |
ReturnMessage | String | Movement's Message Entrada Confirmada Entrada Rejeitada Liquidação Normal Baixa automática |
ReturnCode | String | Movement's Code 02 (Boleto Entry Confirmed) 03 (Entry Rejected) 06 (Normal Settlement) 09 (Automatic retirement) |
Identifier | String | Identifier |
BusinessUnitId | Number | FitBank provided ID |
Method | String | UpdateBoletoInWebhook |
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 3 - Processed 5 - Error |
TotalValue | Decimal | Boleto value |
PartnerId | String | FitBank provided ID |
Method | String | "ChangeBoleto" |
BusinessUnitId | Long | FitBank provided ID |
Updated 4 months ago