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.