5 - Webhooks (COPIA)

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

ParameterTypeDescription
BoletoDocumentNumberStringBoleto Document Number
InterestValueDecimalInterest Value
FineValueDecimalFine Value
BarcodeStringBoleto barcode
DueDateDateTime (yyyy/mm/dd)
DigitableLineStringDigitable Line
ReturnCodesStringReturn Codes
PayerBankCodeStringPayer Bank Code
PayerBankBranchCodeStringPayerBank Branch Code
ReceiverTaxNumberStringCPF/CNPJ of the Boleto receiver
ReceiverNameStringLegal Name of the Boleto receiver
ReceiverBankStringInternal account receiver identification Bank
ReceiverBankBranchStringInternal account receiver identification Bank Branch
ReceiverBankAccountStringInternal account receiver identification Bank Account
ReceiverBankDigitStringInternal account receiver identification Bank Account Digit 
CustomerMailStringE-mail of the payer
CustomerNameStringPayer name
CustomerPhoneStringPhone number of the payer
CustomerTaxNumberStringCPF/CNPJ of the payer
RateValueDecimal0 - Default
1 - Value send at the ratevalue
AddressLine1StringPayer address
AddressLine2StringPayer's Address additional
AddressCityStringPayer City
AddressStateStringPayer State (Ex: SP, RJ, BA, etc)
AddressNeighborhoodStringPayer neighborhood
DivergentPaymentTypeInteger1: Any value.
2: Between minimum and maximum
3: Do not accept payment with divergent value
4: Only the minimum value
MinPaymentValueDecimalMinimum value for boleto payment
MaxPaymentValueDecimalMaximum value for boleto payment
Products--
SellerPersonTypeShort Type of Issuer of the boleto, 0 for Individuals and 1 for Company
SellerNameStringLegal Name of the Boleto issuing account
SellerTaxNumberStringCPF/CNPJ of the Boleto issuing account 
ReceiverPersonTypeShortType of receiver of the boleto, 0 for Individuals and 1 for Company
ReceiverNameStringLegal Name of the Boleto receiver
ReceiverTaxNumberStringCPF/CNPJ of the Boleto receiver
ReferenceStringTransaction description
ProductNameStringTransaction description
ProductQtyDecimalTransaction description
ProductValueDecimalValue of boleto
TagsStringTag List
PartnerIdLongFitBank provided ID
DocumentNumberStringInternal Document Number
IdentifierStringIdentifier
EntryIdLongEntry ID
StatusStringStatus 3 - Registered
Status 5 - Paid
Status 7 - Cancelled
TotalValueDecimalTotal Value
PaymentDateDateTime Payment Date
FineInterestDecimalFine Interest
DiscountValueDecimalDiscount Value
IofValueDecimalIOF Value
PaidValueDecimalPaid Value
OtherValuesDecimalOther Values
CreditDateDateTime Payment Date
OccurrenceDateDateTime Payment Date
URLStringURL of boleto
BankCodeStringBank Code
BankBranchStringBank Branch
BankAccountStringBank Account
BankAccountDigitStringBank Account Digit
ReturnCodeStringMovement's Code
ReturnMessageStringMovement's Message
PaymentProtocolStringPayment Protocol
MethodStringBoleto
BusinessUnitIdLong 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

ParameterTypeDescription
BoletoInfoObjectBoleto Information
DocumentNumberStringBoleto Document Number
StatusStringPreSettled
OcurrenceDateStringStatus change date
BarcodeStringBarcode
OurNumberStringOurNumber
ExternalNumberStringExternalNumber
PaymentInfoObjectPayment Information
PaymentChannelStringPayment 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
PaidValueDecimalPaid Value, including interest, fines, discounts and rebates
PaymentDateStringPayment Date
PayerBankCodeStringPayer Bank Code
PayerBankBranchCodeStringPayer Bank Branch Code
IdentifierStringIdentifier
MethodStringSendBoletoInWebhook
BusinessUnitIdLongFitBank 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

ParameterTypeDescription
DocumentNumberStringBoleto Document Number
IdentifierStringIdentifier
OldValueStringvalue before change
NewValueStringvalue after change
InstructionTypeInt"Type of changed information
ChangeRebateBoleto = 0
ChangeDueDateBoleto = 1,
ChangePrincipalValueBoleto = 2"
StatusInt"Change status
Created = 0,
Sending = 1,
Sent = 2,
Processed = 3,
Canceled = 4,  
Error = 5"
TotalValueDecimalBoleto value
PartnerIdStringFitBank provided ID
MethodString"ChangeBoleto"
BusinessUnitIdLongFitBank provided ID

🚧

Pay attention to status number

Each status number represents an instruction type.