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

Boleto Write-Off Cancellation Webhook

There is a process called "Boleto Write-Off Cancellation", which can occur within 2 business days. In this way, the Recipient FI returns the bill to the Recipient FI, who consequently must refund the amount to the end customer (payer of the bill).
All refund traceability by FitBank (Recipient IF) already exists, because the write-off cancellation records are confirmed in the ACMP 615 files, in the LDL messages, and in consultations on the invoices returned in the PCR.
FItBank makes this refund within business days from the date of payment. The Receiving FI must refund the amount to the Final Payer.

The Webhook should only be sent for the following return reasons:

51 - Payment slip settled for excess or minor value;
68 - Duplicate transfer by the FI Receiving Slip of settled payments;

CancelWriteOffWebhook

{
    "Boleto": {
        "BoletoInfo": {
            "DocumentNumber": " ",
            "OurNumber": " ",
            "ExternalNumber": " ",
            "Barcode": " ",
            "TypableLine": " "
        },
        "PaymentInfo": {
            "PaymentChanel": "1",
            "OriginalValue": 10,
            "FinalValue": 11,
            "Rebate": 0.2,
            "Discount": 0.2,
            "Fine": 0.2,
            "Interest": 0.2,
            "PaidValue": 9,
            "PaymentDate": "2022-12-15T14:17:11.66",
            "PayerBankCode": null,
            "PayerBankBranchCode": null
        }
    },
    "ReasonCode": 51, 
    "Identifier": " ",
    "BusinessUnitId": "",
    "Method": "Cancelamento de Baixa"
}

Description

Parameter	Type	Description
DocumentNumber	String	Boleto Document Number
PaymentChanel	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
OriginalValue	String	Initial value
FinalValue	String	Expected Value for Settlement, plus interest, fine, discount and rebate
Rebate	Decimal	Calculated rebate value
Discount	Decimal	Calculated discount value
Fine	Decimal	Calculated fine value
Interest	Decimal	Calculated interest value
PaidValue	Decimal	Paid Value
PaymentDate	String	Payment Date
PayerBankCode	Number	Boleto paying bank code
PayerBankBranchCode	String	Branch of the paying bank
ReasonCode	Number	Reason for return informed by the Treasury
Identifier	String	Identifier
BusinessUnitId	Long	FitBank provided ID
Method	String	"Cancelamento de Baixa"

Boleto Recurrence Webhook

The issuance of recurring bills is carried out asynchronously. When using the GenerateRecurrinceBoletoIn API, the system only returns the ID of the generated recurrence.

Subsequently, all invoices associated with this recurrence will be issued. For the customer to have access to the IDs of each bill, they must receive a webhook with this information.

BoletoInRecurrenceWebhook

{
    "Payee": {
        "Name": "Fulano",
        "TaxNumber": "***851***13",
        "Bank": {
            "Code": 260,
            "Branch": 1332,
            "Account": 1132,
            "AccountDigit": 1
        }
    },
    "Payer": {
        "Name": "Fulano",
        "TaxNumber": "16985164013"
    },
    "Installments": [
        {
            "DocumentNumber": 26566,
            "DueDate": "2023-12-20"
        },
        {
            "DocumentNumber": 26567,
            "DueDate": "2023-12-20"
        },
        {
            "DocumentNumber": 26568,
            "DueDate": "2023-12-20"
        },
        {
            "DocumentNumber": 26569,
            "DueDate": "2023-12-20"
        }
    ],
    "ExternalNumber": "12245",
    "URL": "",
    "BoletoRecurrenceId": 12345,
    "BusinessUnitId": 672,
    "Method": "BoletoRecurrenceIn"
}

Description

Parameter	Type	Description
`Payee`	Object	Beneficiary information.
`Payee.Name`	String	Beneficiary's name.
`Payee.TaxNumber`	String	Beneficiary's CPF/CNPJ.
`Payee.Bank`	Object	Beneficiary's bank information.
`Payee.Bank.Code`	Number	Beneficiary's bank code.
`Payee.Bank.Branch`	Number	Beneficiary's bank branch.
`Payee.Bank.Account`	Number	Beneficiary's account number.
`Payee.Bank.AccountDigit`	Number	Beneficiary's account check digit.
`Payer`	Object	Payer information.
`Payer.Name`	String	Payer's name.
`Payer.TaxNumber`	String	Payer's CPF/CNPJ.
`Installments`	Array of Objects	List of installments associated with the payment.
`Installments[].DocumentNumber`	Number	Document number related to the installment.
`Installments[].DueDate`	String	Installment due date in the format "YYYY-MM-DD".
`ExternalNumber`	String	External identification number of the payment.
`URL`	String	Return URL (only present when `Type` is "Carnê").
`BoletoRecurrenceId`	Number	Unique identifier for the "Carnê", returned when generating recurring boletos.
`BusinessUnitId`	Long	Business unit identifier.
`Method`	String	Payment method, specified here as "BoletoRecurrenceIn".