​
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:

1.1

URL

The partner must specify the URL of the callback that will be called to send the information.

Example:

www.example-url.com
1.2

Environments

The callback for monitoring the status of proposals must be sent to both the approval environment and the production environment. It is recommended that different URLs be used for each environment.

1.3

Call methods

The partner can select the HTTP method for sending the callback.

Available options include: GET, POST and PUT.

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

AuthenticationKeyExample Token
Bearer TokenAuthorizationBearer eyJhbGciOiJIUzI1CI6IkpXVCJ9
API KeyAPI-Key1234567890abcdef1234567890abcdef
Basic AuthenticationAuthorizationBasic dXNlcm5hbWU6cGFzc3dvcmQ
X-API-KeyX-API-Key0987654321fedcba0987654321fedcba
JWT (JSON Web Token)AuthorizationBearer eyJhbGciOiJIUzI1NiIs
HMAC (Hash-based Message Authentication Code)AuthorizationHMAC 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

ParameterParameter description
ProposalUnique GUID generated in the response during proposal inclusion.
StatusProposal status ID in our system.
IdentifierIf sent, this field represents the operation code sent when the proposal was included.

​
Proposal status identification table

IDDescriptionPurpose
2ApprovedProposal was created and is awaiting signature.
4CanceledProposal was canceled automatically or by the integrator.
5PendingProposal was marked as pending and requires intervention by the integrator to request endorsement again.
6CompletedEndorsement was requested at CEF (Caixa Econômica Federal).
8ReleasedProposal successfully endorsed and released for disbursement.
9PaidProposal disbursement was made.
10AssignedProposal was added to an assignment shipment and assigned to the fund.
11Pending PaymentThe 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