Technical Callback Procedure

Introduction

Callbacks, or webhooks, are mechanisms that allows a function to be executed in response to a specific event.

In the context of the BMP APIs, a callback is sent automatically whenever specific events occur in the system.

This allows efficient communication between different parts of an application.

This mechanism is used to notify updates to the status of proposals, eliminating the need for constant checks.

In this context, information is received automatically and in real time, without the need for the partner to execute a command to update itself with a response.

In this document, we present how this procedure works, its importance in integrations and how to use it in the development of your application when using BMP APIs.

Our callbacks should not be mapped in a restricted way. Additional fields can be included in the payloads of the returned callbacks. Please check the Updates and Announcements page.

Settings

1. Partner Configuration

   Partners can configure how they want to receive the callback notifications, defining the following characteristics:

2. Authentication

   To ensure the security of the callback sent, we recommend that the partner define an authentication method.

   The following are the available authentication methods:

   Available options include:

   Accepted authentication methods

   Authentication	Key	Example Token
   Bearer Token	Authorization	Bearer eyJhbGciOiJIUzI1CI6IkpXVCJ9
   API Key	API-Key	1234567890abcdef1234567890abcdef
   Basic Authentication	Authorization	Basic dXNlcm5hbWU6cGFzc3dvcmQ
   X-API-Key	X-API-Key	0987654321fedcba0987654321fedcba
   JWT (JSON Web Token)	Authorization	Bearer eyJhbGciOiJIUzI1NiIs
   HMAC (Hash-based Message Authentication Code)	Authorization	HMAC 5d41402abc4b19d911017c592

   All authentication methods accept up to 255 characters.
3. Proposal callback example

   Here is an example of a URL and how we parameterize it for reception:

   www.example-url.com.br?proposta={PROPOSTA}&situacao={SITUACAO}&identificador={IDENTIFICADOR}
   

   Proposal callback parameters table

   Parameter	Parameter description
   Proposal	Unique GUID generated in the response during proposal inclusion.
   Status	Proposal status ID in our system.
   Identifier	If sent, this field represents the operation code sent when the proposal was included.

   Proposal status identification table

   ID	Description	Purpose
   2	Approved	Proposal was created and is awaiting signature.
   4	Canceled	Proposal was canceled automatically or by the integrator.
   5	Pending	Proposal was marked as pending and requires intervention by the integrator to request endorsement again.
   6	Completed	Endorsement was requested at CEF (Caixa Econômica Federal).
   8	Released	Proposal successfully endorsed and released for disbursement.
   9	Paid	Proposal disbursement was made.
   10	Assigned	Proposal was added to an assignment shipment and assigned to the fund.
   11	Pending Payment	The proposal is pending payment due to inconsistent bank details, requiring the integrator to correct them and return it to the payment queue.

   If the callback is sent with the POST method, in addition to the data sent in the Query, the partner will receive in the body of the request:

   • Status 9: 00 - Credit or debit made;
   • Status 10: AB - Description of the occurrence.

   If a problem occurs while receiving the proposal callback, the system will make up to 3 attempts to send it.
4. Contract Management Events
5. 1. Creation of Contract Management
6. This callback is used to communicate the creation of an installment schedule, detailing information about installments, amounts, and relevant dates.
7. Example of return:
8. {
     "QtdeParcelas": 8,
     "VlrTotalDivida": 11.2,
     "DtFinanciado": "06-09-2024",
     "Credito": {
       "DtCredito": null,
       "Conta": {
         "CodigoBanco": null,
         "NomeBanco": null,
         "Agencia": null,
         "Conta": null,
         "ContaDigito": null
       }
     },
     "Parcelas": [
       {
         "NroParcela": 1,
         "VlrParcela": 1.4,
         "VlrPrincipal": 1.25,
         "VlrDespesas": 0.15,
         "VlrSaldoDevedor": 9.8,
         "DtVencimento": "16-09-2024"
       },
       {
         "NroParcela": 2,
         "VlrParcela": 1.4,
         "VlrPrincipal": 1.25,
         "VlrDespesas": 0.15,
         "VlrSaldoDevedor": 8.4,
         "DtVencimento": "16-10-2024"
       }
     ]
   }
   

9. FieldTypeDescriptionQtdeParcelasIntDescribes the number of installmentsVlrTotalDividaFloatTotal debt amount, including taxes and feesDtFinanciadoDateDate of financing agreementDtCreditoDateDate when the credit was granted, disbursement of the amountCodigoBancoIntBank identification codeNomeBancoStringBank nameAgênciaIntAgency identification numberContaIntAccount identification numberContaDigitoIntAccount digitNroParcelaIntInstallment numberVlrParcelaFloatTotal installment amountVlrPrincipalFloatAmount excluding taxes, interest, and feesVlrDespesasFloatAdditional expenses included in the installment (taxes and interest)VlrSaldoDevedorFloatOutstanding balance after the installment paymentDtVencimentoDateInstallment due date
10. 2. Cancellation of Contract Management
11. Callback used to notify the cancellation of a previously created schedule, including event details and the associated proposal number.
12. Example of return:
13.  {
      "TipoEvento": 1,
      "NomeEvento": "Cancelamento de Agenda",
      "NroProposta": 3543743,
      "DtEvento": "2024-09-05",
      "AcrescimoAbatimento": null,
      "LancamentoParcela": null,
      "ProrrogacaoVencimento": null,
      "GeracaoBoleto": null,
      "CancelamentoBoleto": null
    }
    

14. CampoTypeDescriptionTipoEventoIntNumeric identifier of the event typeNomeEventoStringName of the eventNroPropostaIntNumber of the associated proposalDtEventoStringDate when the event occurredAcrescimoAbatimentoObjectObject containing information about increases or reductions related to the eventLancamentoParcelaObjectObject containing information about the installment entryGeracaoBoletoObjectObject containing information about the invoice generationProrrogacaoVencimentoDatetimeDate and time of the due date extensionCancelamentoBoletoObjectObject containing information about the invoice cancellation
15. 4. Increases/Reductions
16. Callback that informs financial changes in proposal installments, whether due to increases or reductions applied.
17. Example of return:
18.  {
      "TipoEvento": 2,
      "NomeEvento": "Acréscimo/Abatimento",
      "NroProposta": 3543753,
      "DtEvento": "2024-09-05",
      "AcrescimoAbatimento": {
        "NroParcela": 2,
        "VlrSaldo": 0,
        "VlrAcrescimo": 10,
        "VlrAbatimento": 0,
        "VlrSaldoAtual": 10
      },
      "LancamentoParcela": null,
      "ProrrogacaoVencimento": null,
      "GeracaoBoleto": null,
      "CancelamentoBoleto": null
    }
    

19. FieldTypeDescriptionTipoEventoIntNumeric identifier of the event typeNomeEventoStringName of the eventNroPropostaIntNumber of the associated proposalDtEventoStringDate when the event occurredAcrescimoAbatimentoObjectObject containing information about increases or reductions related to the eventNroParcelaIntNumber of the installment affected by the increase/reductionLancamentoParcelaObjectObject containing information about the installment entryGeracaoBoletoObjectObject containing information about the invoice generationProrrogacaoVencimentoDatetimeDate and time of the due date extensionCancelamentoBoletoObjectObject containing information about the invoice cancellationVlrAcrescimoFloatValue of the increase applied to the installmentVlrAbatimentoFloatValue of the reduction applied to the installment
20. 5. Entry of Installment
21. Callback that communicates events related to installment entries, such as payment, reductions, charges, or settlement.
22. Example of return:
23. {
      "TipoEvento": 3,
      "NomeEvento": "Lançamento na Parcela",
      "NroProposta": 3543603,
      "DtEvento": "2024-09-05",
      "AcrescimoAbatimento": null,
      "LancamentoParcela": {
        "NroParcela": 1,
        "VlrOriginalParcela": 72.24,
        "VlrSaldo": 0,
        "ParcelaLiquidada": true,
        "VlrEncargos": 0,
        "VlrAbatimento": 0,
        "VlrPagamento": 72.24,
        "VlrDesconto": 0,
        "VlrSaldoAtual": 0,
        "VlrExcedente": 0,
        "DtVencimento": "2024-09-15",
        "DtVencimentoAtual": "2024-10-30",
        "Boleto": {
          "NroBoleto": null,
          "Liquidacao": null
        }
      },
      "ProrrogacaoVencimento": null,
      "GeracaoBoleto": null,
      "CancelamentoBoleto": null
    }
    

24. FieldTypeDescriptionDtEventoDateDate when the event occurredAcrescimoAbatimentoObjectIncrease or reduction applied (not applicable)NroParcelaIntInstallment numberVlrOriginalParcelaFloatOriginal value of the installmentVlrSaldoFloatRemaining balance after payment (initially 0)ParcelaLiquidadaBooleanIndicates whether the installment was fully settledVlrEncargosFloatValue of charges applied (if any)VlrAbatimentoFloatValue of reduction applied (if any)VlrPagamentoFloatAmount effectively paidVlrDescontoFloatValue of discount granted (if any)VlrSaldoAtualFloatCurrent balance after paymentVlrExcedenteFloatExcess amount paid (if any)DtVencimentoDateOriginal due date of the installmentDtVencimentoAtualDateUpdated due date of the installmentNroBoletoIntAssociated invoice number (not applicable)LiquidacaoBooleanIndicates whether settlement occurred (not applicable)
25. 6. Extension of Due Date
26. Callback used to notify extensions of installment due dates, providing the new date and the reasons for the change.
27. Example of return:
28. {
      "TipoEvento": 4,
      "NomeEvento": "Prorrogação de Vencimento",
      "NroProposta": 3543603,
      "DtEvento": "2024-09-05",
      "AcrescimoAbatimento": null,
      "LancamentoParcela": null,
      "ProrrogacaoVencimento": {
        "NroParcela": 1,
        "DtVencimentoAnterior": "2024-09-15",
        "DtVencimentoAtual": "2024-10-30"
      },
      "GeracaoBoleto": null,
      "CancelamentoBoleto": null
    }
    

29. FieldTypeDescriptionCodigoPropostaStringUID of the proposal returned in the inclusion responsecodigoOperacaoStringUnique identifier of the operationnroParcelaIntInstallment number affected by the extensionNovoVencimentoStringNew due date of the installmentMotivoAlteracaoStringDescription of the reason for the due date extensionTipoEventoIntNumeric identifier of the event typeNomeEventoStringName of the extension eventNroPropostaIntNumber of the proposal associated with the eventDtEventoStringDate when the extension event occurredProrrogacaoVencimentoObjectDetails of the due date extension- NroParcelaIntNumber of the extended installment- DtVencimentoAnteriorStringOriginal due date before the extension- DtVencimentoAtualStringNew due date after the extension
30. 7. Generation of Invoice
31. Callback that informs the generation of an invoice related to a proposal, including the amount, number, and due date.
32. Example of return:
33. {
      "TipoEvento": 5,
      "NomeEvento": "Geração de Boleto",
      "NroProposta": 3544197,
      "DtEvento": "2024-09-06",
      "AcrescimoAbatimento": null,
      "LancamentoParcela": null,
      "ProrrogacaoVencimento": null,
      "GeracaoBoleto": {
        "CodigoBoleto": "8a72e6a3-cf73-46cb-99ee-b698335f1e12",
        "NroBoleto": 48924,
        "VlrBoleto": 1.4,
        "DtVencimento": "2024-09-25",
        "Liquidacao": true
      },
      "CancelamentoBoleto": null
    }
    

34. FieldTypeDescriptionTipoEventoIntNumeric identifier of the event typeNomeEventoStringName of the eventNroPropostaIntNumber of the associated proposalDtEventoStringDate when the event occurredAcrescimoAbatimentoObjectObject containing information about increases or reductions related to the eventLancamentoParcelaObjectObject containing information about the installment entryGeracaoBoletoObjectObject containing information about the invoice generationCodigoBoletoStringInvoice identification codeLiquidaçãoBooleanIndicates whether the settlement status is true or falseVlrBoletoFloatInvoice amountDtVencimentoDateInvoice due dateNroBoletoIntInvoice identification numberProrrogacaoVencimentoDatetimeDate and time of the due date extensionCancelamentoBoletoObjectObject containing information about the cancellation
35. 8. Cancellation of Invoice
36. Callback used to notify the cancellation of an invoice, including the canceled invoice code and the associated installments.
37. Example of return:
38. {
      "TipoEvento": 6,
      "NomeEvento": "Cancelamento de Boleto",
      "NroProposta": 3541909,
      "DtEvento": "2024-08-30",
      "AcrescimoAbatimento": //Object
      "LancamentoParcela": //Object
      "ProrrogacaoVencimento": null, //Datetime
      "GeracaoBoleto": null, //Object
      "CancelamentoBoleto": {
        "CodigoBoleto": "8f3898e2-c99b-40f2-9d13-6a23e5b7e082",
        "NroBoleto": 48681,
        "Parcelas": [
          3
        ]
      }
    }
    

39. FieldTypeDescriptionTipoEventoIntNumeric identifier of the event typeNomeEventoStringName of the eventNroPropostaIntNumber of the associated proposalDtEventoStringDate when the event occurredAcrescimoAbatimentoObjectObject containing information about increases or reductions related to the eventLancamentoParcelaObjectObject containing information about the installment entryGeracaoBoletoObjectObject containing information about the invoice generationProrrogacaoVencimentoDatetimeDate and time of the due date extensionCancelamentoBoletoObjectObject containing information about the cancellation