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

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 Change Webhook

When you send a change statement, Webhooks are sent that contain the status of the change in the boleto. They are:

Status 0 = Change instruction created;
Status 1 = Change instruction is being prepared to be sent to the registry;
Status 2 = Sent to register;
Status 3 = Processed (Final success status);
Status 4 = Cancelled;
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.